Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
402d873
docs: define the launcher contract for gateway supervision
cursoragent Oct 16, 2026
53da7e2
fix: an unreadable executable path exits 1, not 75
cursoragent Oct 16, 2026
2f9334e
docs: name Intel Mac once and keep the signer closed
cursoragent Oct 16, 2026
7239d8b
fix: exit 75 restarts only for a replaced binary or a changed hash
cursoragent Oct 16, 2026
9db30cc
fix: bind gateway readiness and passkeys to the localhost origin
cursoragent Oct 16, 2026
1e63148
fix: keep local passkey fixtures on the localhost relying party
cursoragent Oct 16, 2026
6c76752
fix: let a gateway inside serve start without taking the host lock again
claude Oct 17, 2026
a41378d
fix: tell the person which address to open when a passkey origin is r…
claude Oct 17, 2026
5e0e9f8
docs: state the readiness and listen-socket gaps in the launcher cont…
claude Oct 17, 2026
756dad1
deps: move zip to 9.x for RUSTSEC-2026-0367/0368/0369
claude Oct 17, 2026
519a2df
Merge fix/zip-9-rustsec into cursor/launcher-contract-1297
claude Oct 17, 2026
ce5d187
fix: listen on every localhost address and move IP Home pages to loca…
claude Oct 17, 2026
9c9766b
docs: make the launcher contract the one source for the Home address
claude Oct 17, 2026
c1507ac
Merge remote-tracking branch 'origin/cursor/launcher-contract-1297' i…
claude Oct 17, 2026
f1fcb21
model-provider: held-lock journal test takes its lock with the bounde…
andersalm Oct 17, 2026
3672007
fix: prove gateway lock ownership from the held flock, not the lock r…
claude Oct 17, 2026
85f3142
fix: prove host lock ownership in one step against the holder's own lock
claude Oct 17, 2026
eed83a7
fix: open the subordinate runtime lane only on the held gateway lock
claude Oct 17, 2026
4bb19dc
fix: report a host lock holder whose record cannot be read
claude Oct 17, 2026
13cdcad
docs: state that the host lock proves possession, not that the holder…
claude Oct 18, 2026
d30027e
Merge origin/develop into cursor/launcher-contract-1297
claude Oct 18, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 26 additions & 24 deletions capsules/object-provider/Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

10 changes: 6 additions & 4 deletions docs/HOME_LOCAL_SETUP.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,10 +42,12 @@ export HOME_URL="http://localhost:61180/apps/home/"

`HOME_URL` is the browser URL you open.

You may choose a different loopback port if it is free. The Mac source-home
examples in this repository use `localhost:61180`. The agent smoke script
defaults to `localhost:8090`; that is only a script default, not product
authority.
These values are for the developer source-home lane. You may choose a
different loopback port if it is free. The Mac source-home examples in this
repository use `localhost:61180`. The installed Home address is
`http://localhost:8090/home/`; the
[launcher contract](LAUNCHER_CONTRACT.md#readiness-and-home-url) owns that
address and the redirect from a loopback IP address to `localhost`.

## Know the two host lanes

Expand Down
4 changes: 3 additions & 1 deletion docs/INSTALL.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,9 @@ the bootstrap and connection contract.
The installer detects the platform (Linux `x86_64`/`aarch64` or
macOS Apple silicon), verifies the signed release, installs Runtime, and
fetches the Home profile from the trusted publisher. It
starts Home at `http://localhost:8090/home/` and opens your browser. Keep the
starts Home at `http://localhost:8090/home/` and opens your browser. The
[launcher contract](LAUNCHER_CONTRACT.md#readiness-and-home-url) owns this
address. Keep the
terminal open while you use Home; Ctrl+C stops it. With no interactive terminal,
setup completes and prints the full command for opening Home later. The installer
uses the installed binary's full path, so editing PATH is optional.
Expand Down
152 changes: 152 additions & 0 deletions docs/LAUNCHER_CONTRACT.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,152 @@
# Launcher Contract

A supervisor starts Home with the gateway command below. This repository owns the
gateway, the readiness probe, the passkey origin, and the exit codes. A desktop
launcher is a separate program. This document states the behavior the Runtime
implements today.

## Start

```bash
elastos gateway --addr localhost:8090
```

`--addr` is `host:port`. `elastos home` binds `localhost:8090` and opens the
Home URL below. The gateway command leaves the system browser closed. The
default `--addr` of the gateway command is `127.0.0.1:8090`, so a launcher
passes `--addr localhost:8090`.

For the host name `localhost`, the gateway listens on every loopback address
that a client can use for that name on the given port: each address that the
computer resolves for `localhost`, and also `127.0.0.1` and `::1`, which
browsers use for `localhost`. Each of these listeners serves the same Home.
When the computer has no IPv6, the gateway listens without `::1`. The gateway
exits 1 and its error names the address when another program already uses one
of these addresses, when it cannot listen on one of them for another reason,
or when `localhost` resolves to an address that is not loopback. For an IP
address in `--addr`, the gateway listens on that one address.

On Windows, Home runs in WSL2. This repository does not test how Windows
forwards `localhost` into WSL2; that is a gap in this contract.

`elastos serve` is the operator runtime. Its readiness route is `GET /api/health`.
A Home supervisor uses `gateway` and `/healthz`.

## Readiness and Home URL

When this gateway process holds the host lock `{data}/host-process.lock`
with role `gateway` or `gateway-public`:

```text
GET http://localhost:8090/healthz
```

returns HTTP 200 and the two bytes `OK`. Otherwise it returns HTTP 503: when
no process holds the lock, when another process holds it, when the file at
that path was removed or replaced after the gateway took its lock, and when
the gateway has released it. A gateway that `elastos serve` starts keeps the
`serve` lock, so its `/healthz` returns 503.

What proves that this gateway holds the lock: the process that owns the
listening socket answers, and it checks its own state. It holds an exclusive
lock (`flock`) on an open file, `{data}/host-process.lock` names that same file
now (the same device and inode), and a new open of that file cannot take the
lock. The JSON record in the file is not proof. Any process that runs as the
same user can rewrite it, so `/healthz` does not read it, and a gateway does
not skip taking the lock because the record names its pid.

The lock proves possession, not identity. A process that holds the `flock`
has the host lock. That does not prove that the holder is a gateway, or that
it is ElastOS. Any process that runs as the same user can open
`{data}/host-process.lock` and hold the lock. While it holds the lock, a
gateway for that data directory does not start (see "Data directory and
lock"), and a gateway that does not hold the lock itself returns 503 from
`/healthz`. A gateway can prove only that it holds the lock itself, so `OK` is
a statement that the gateway makes about itself.

The same limit applies to a Home terminal that the gateway starts. The gateway
gives it `ELASTOS_GATEWAY_HOST_PID`, its own pid, and
`ELASTOS_GATEWAY_HOST_LOCK_FD`, a descriptor of the open file that holds the
lock. The terminal checks that its parent has that pid and that the descriptor
holds the lock now. This proves lock possession, not that the parent is the
gateway. A process that runs as the same user and holds the lock can give the
same variables and its descriptor to a child of its own, and that child's
check accepts them.

The process that answers on the port gives this reply about its own data
directory. If an ElastOS gateway for another data directory already listens on
the port, that gateway also returns `OK`, and so can any other program that
listens on the port. The reply does not name the process.
Before it trusts `OK`, a supervisor confirms that the child it started is still
running and that `{data}/host-process.lock` records the pid of that child with
role `gateway`. That record is a hint, not proof, for the reasons above: a
process that is not that child can hold the lock and write a record that names
the child. A reply that names the lock holder is a gap in this contract.

The Home origin is:

```text
http://localhost:8090/home/
```

`localhost` is the one Home origin. Other documents cite this section for the
Home address. When the gateway listens on `localhost`, a `GET` or `HEAD`
request for a Home page (`/`, `/home`, `/home/`, `/apps/home`, or
`/apps/home/`) whose `Host` is a loopback IP address, such as `127.0.0.1` or
`[::1]`, gets HTTP 308. Its `Location` is the same path and query at
`http://localhost:<port>`. `/healthz`, `/api/` routes, Home assets, and app
routes answer on every listening address without a redirect. A gateway with an
IP address in `--addr` serves its Home pages at that address.

The passkey relying party id is `localhost`. Registration and sign-in use that
origin. An IP-literal origin, including `http://127.0.0.1:8090`, is refused
with HTTP 403. For a loopback address, the reply tells the person to open
`http://localhost:<port>/home/`.

Each release takes the relying party id from the host of the page, and browsers
refuse an IP address as a relying party id. A passkey from an earlier release
therefore names the host where it was made. Sign-in accepts that passkey at
the same host on any port, and refuses it at every other host.

## Data directory and lock

| Item | Path |
| --- | --- |
| Linux data directory | `$XDG_DATA_HOME/elastos`, or `~/.local/share/elastos` |
| macOS data directory | `~/Library/Application Support/elastos` |
| Host lock | `{data}/host-process.lock` |

The lock record stores `pid`, `role`, and `addr`. `addr` is the `--addr`
value as given, for example `localhost:8090`. The record is for people and
tools to read; the `flock` on the file is the lock. A second live host for the
same data directory exits 1. Its error contains `another ElastOS host already owns`.
The gateway gives this error when any process holds the lock, also a process
that is not ElastOS. The error names the holder from the record, and the
record can be false.

## Stop

The gateway handles `SIGTERM` and `SIGINT` by signalling its process group,
waiting, and then signalling that group again. Exit 75 comes from
`std::process::exit` in the binary watch and skips that handler.

While the gateway is running, the binary watch exits 75 when the installed
binary is replaced, when its path changes, or when the watch cannot read it.
The install transaction replaces that binary by renaming the staged file onto
the installed path. On Linux that running path then ends in ` (deleted)`.

## Exit codes

| Code | Meaning |
| --- | --- |
| 0 | The command finished. |
| 1 | The command failed. A second host for the same data directory is one case. |
| 2 | The `elastos` command line is invalid. |
| 75 | The running gateway's binary watch exited. |

A supervisor uses these exit codes. It does not parse English sentences from
stdout. Exit 0 covers more than one successful update outcome. A later issue
owns a machine-readable update status.

Intel Mac's release id is `x86_64-darwin`. This contract does not publish a
download for that id.
2 changes: 2 additions & 0 deletions docs/MAC.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,8 @@ On first launch, Home shows `Set up Home`. Enter a passkey name, choose
passkey becomes the Home admin. Later launches show `Sign in` / `Use passkey`.
Use `http://localhost:61180/apps/home/`; do not switch the visible origin to
`127.0.0.1`, because passkey RP/origin state is bound to the browser origin.
Port `61180` is the developer source-home lane. The installed Home address is
in the [launcher contract](LAUNCHER_CONTRACT.md#readiness-and-home-url).

## Browser VM Artifacts

Expand Down
2 changes: 2 additions & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,8 @@ Each top-level ledger has one job:
lifecycle, and child intents
- [Interactive runtime contract](INTERACTIVE_RUNTIME_CONTRACT.md): interactive
sessions and return behavior
- [Launcher contract](LAUNCHER_CONTRACT.md): install, gateway start, `/healthz`,
Home URL, data directory, lock, stop, and update
- [Execution](EXECUTION.md): release execution boundaries
- [Command runtime matrix](COMMAND_MATRIX.md): Runtime ownership for every
command
Expand Down
3 changes: 2 additions & 1 deletion docs/WINDOWS.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,8 @@ WSL2.

- Package the Runtime as a signed or importable ElastOS WSL distribution.
- Provide a small Windows launcher that starts, stops, updates, health-checks,
and opens `http://localhost:61180/apps/home/`.
and opens the Home origin in the
[launcher contract](LAUNCHER_CONTRACT.md#readiness-and-home-url).
- Keep Runtime state in the Linux filesystem, not in mixed host paths.
- Enforce explicit storage budgets and cleanup.
- Keep localhost and passkey origin stable.
Expand Down
Loading
Loading