@stim-cli/server 1.14.0 → 1.16.0

package/README.md

@@ -3,8 +3,9 @@
 `stim-server` serves Stim state to paired clients, such as the Stim phone app,
 and lets the clients the Mac grants control run `stim reload` and `stim stop`
 in a workspace. It runs on the Mac, next to Stim. It changes Stim state only
-through those two commands, and writes only its own pairing state and action
-log under `$STIM_HOME/server/`.
+through those two commands. It writes only its own pairing state and action
+log under `$STIM_HOME/server/`, and the device recordings described under
+[Recording](#recording).
 
 The design is in
 [`docs/specs/2026-09-25-stim-server-design.md`](../../docs/specs/2026-09-25-stim-server-design.md).
@@ -15,35 +16,178 @@ The design is in
 stim-server [--port <n>]          # serve paired clients, port 7787 by default
 stim-server pair [--port <n>] [--control]
                                   # print a single-use pairing payload
-stim-server devices [list]        # list paired devices
-stim-server devices grant <id> --control|--read
-                                  # let a paired device run actions, or only read
-stim-server devices revoke <id>   # revoke a paired device
+stim-server devices [list]        # list paired devices, approved clients and access requests
+stim-server devices grant <id> --control|--read|--build|--device-host
+                                  # let a paired device run actions, or only read;
+                                  # --build approves builds; --device-host approves device hosting
+stim-server devices revoke <id>   # revoke a paired device or client, or deny a request
 stim-server log                   # list the actions paired devices ran
+stim-server setup --client <node-id> --ticket <t> --expires <iso> --build|--device-host
+                                  # worker-side approval and setup, see below
+stim-server service install|status|update|rollback|uninstall
+                                  # run stim-server as a macOS LaunchAgent, see below
 ```
 
+`--env KEY=VALUE` and `--path-prepend <dir>` (each repeatable) apply to the
+serving command: see [Run as a service](#run-as-a-service).
+
 `pair --json` prints `{ "qr": <payload>, "expiresAt": "<ISO time>" }`, and
 `devices --json` prints `{ "devices": [...] }` with each device's `id`, `name`,
-`identity`, `pairedAt`, `lastSeenAt` and `capabilities`, never its token hash.
+`identity`, `pairedAt`, `lastSeenAt` and `capabilities`, never its token hash,
+followed by the [build clients](#build-access) and [device-host clients](#device-host-approval).
+New client records carry `requestedCapability` (`build` or `device-host`),
+including after approval. Pending records also carry `pendingUntil`; a legacy
+pending record without `requestedCapability` is a build request.
 `log --json` prints `{ "actions": [...] }`, the records described under
 [Actions](#actions).
 
 `GET http://127.0.0.1:7787/health` answers requests from this Mac with the
-server's name, versions, protocol, `stimHome`, and the Tailscale state it
-started with. While Tailscale runs, it also carries `route`, read from
+server's name, versions, `stimBuild` (the digest of the bundled Stim's build,
+which offload compares between Macs), protocol, `stimHome`, `startup`, `busy`
+(the offloaded `builds` and `hostedSessions` running now) and the current
+Tailscale state. It answers HTTP 200 once `startup.state` is `ready`; while the
+state is `pending` or `degraded` (see the LaunchAgent notes below) it answers
+HTTP 503 with the same body. While Tailscale runs, it also carries `route`, read from
 `tailscale serve status --json` on each request: `routed` with the HTTPS
 `port` that proxies to the server, `funneled` with the Funnel `ports` that do,
 `missing`, or `unknown` with a `reason`; the last three carry the `port` the
-setup command would use. Stim Desktop uses it to find a running server and
-show its route. A request through
-`tailscale serve`, on a Tailscale address, or with a `Host` other than
-`127.0.0.1` or `localhost` gets HTTP 426, like any other plain HTTP request.
+setup command would use. When the server runs under Stim Host, it also carries
+`host`: `{ name, screenRecording, accessibility }`, the grants macOS gives that
+app (checked at most every 5 seconds), or `null` when the check fails. Stim
+Desktop uses it to find a running server and show its route. A request through `tailscale serve` or on a Tailscale address
+without an `Origin` or `Sec-Fetch-Site` header, which a web page's request
+carries, gets only `{ "server": "stim-server", "version", "protocol" }`, which Stim
+Desktop's Build machines list uses to find stim-server on the other Macs of the
+tailnet. A request from this Mac with a `Host` other than `127.0.0.1` or
+`localhost` gets HTTP 426, like any other plain HTTP request.
+
+`GET /setup/<hash>` returns a setup journal over the tailnet HTTP route. The
+hash is exactly 64 lowercase hex characters: SHA-256 of the optional
+`auth.setupTicket` on a build or device-host request (43 base64url characters).
+The registry stores only `setupTicketHash` and retains it after approval;
+missing or invalid tickets leave ordinary access requests unchanged.
+
+The journal lives at `$STIM_HOME/server/setup/<hash>.json`, written atomically
+only by stim-server and read through core's state reader. It contains the
+client node, ISO `expiresAt`, requested capabilities, steps, granted request
+ids, completion state and optional exit code; it contains no tokens. Only the
+matching tailnet node can read an unexpired journal. Browser requests, loopback,
+invalid paths, missing or malformed journals and other nodes get the same 404. Like the agent route, the caller address is the `X-Forwarded-For` header the tailnet route sets, so a local process that forges it is outside this model.
+The route returns 503 until startup is ready, caches peer identity for 30 seconds
+and returns 429 after repeated identity failures. All responses use
+`cache-control: no-store`. Steps whose ids start with `tools` appear only after
+a build grant. The server prunes journals more than one hour past expiry at
+startup and hourly.
 
 `stim-server` runs the `stim` version this package was released with, not the
 one on your PATH. It reads the login shell's environment once at start, so
 `PATH`, `ANDROID_HOME`, and `STIM_*` variables match your terminal even when
 another app starts it.
 
+## Set up a worker Mac
+
+A person on the worker runs the command generated for their client Mac:
+
+```bash
+stim-server setup --client <node-id> --ticket <43-base64url-characters> --expires <ISO-time> \
+  --build --device-host [--port <n>] [--label <name>] \
+  [--env KEY=VALUE]... [--path-prepend <dir>]... [--yes] [--json]
+```
+
+If the server is not installed globally, use `npx --yes --package @stim-cli/server@<version> stim-server`
+in place of `stim-server`, with the exact version from the client Mac.
+At least one capability is required. The expiry must be in the future and at
+most two hours ahead. The defaults are port 7787 and label `dev.stim.server`.
+Argument and preflight refusals change nothing. Preflight requires macOS,
+Node 22.12+, running Tailscale, the client node on this tailnet, and this user's
+GUI login session.
+
+Running setup on the worker is the worker-side approval. It pre-approves at
+most one request per chosen capability, from this node, carrying this ticket,
+until this expiry. A terminal asks y/N for each grant (default No); use `--yes`
+to approve without those questions, including without a terminal. Without
+a terminal or `--yes`, setup refuses before installing anything unless every
+chosen capability already has a matching approval. A person on
+the worker still approves; an SSH-driven run is not offered. Build and
+device-host requests are separate grants. Build never includes read or control.
+A rerun before expiry reports matching approved requests as already approved
+and never grants a second request. After expiry it refuses with exit 2 before
+any change. Requests themselves lapse after 15 minutes.
+
+Setup installs its exact server release into
+`~/Library/Application Support/Stim/services/<label>/versions/`, installs
+Stim Host, installs or reuses the managed LaunchAgent, and creates or reuses a
+tailnet-only HTTPS route on 7443 or the next free port. Older managed services
+use the service update busy-wait and rollback behavior. Newer versions stay
+installed; tools report a Stim build difference. A reused server must be at
+least **1.16.0** (ignoring its prerelease suffix for this floor), the first version with setup ticket storage and the journal
+route. An older app server refuses immediately with an update remedy.
+
+When a Desktop-run server already answers on the port, setup reuses it and
+installs no LaunchAgent. It requires an existing tailnet route and refuses
+to create one it cannot record. Its permissions belong to that app. The server must
+use the same Stim home. Export a scratch `STIM_HOME` in the shell before
+running setup; `--env` cannot set it. Repeatable `--env KEY=VALUE` and
+`--path-prepend <absolute-dir>` have the same validation and environment order
+as service install. A new LaunchAgent inherits only `STIM_HOME` and `SHELL`;
+pass paths and variables needed for CocoaPods, Java or Android explicitly.
+
+For device hosting, setup checks screen recording and device control, requests
+normal macOS prompts, and opens the matching Privacy & Security panes after
+about ten seconds without a grant. Prompts appear on this Mac's screen. A
+terminal accepts `s` to skip each permission. Without a terminal, each missing
+permission waits at most five minutes and remains pending in the journal.
+Missing screen recording prevents viewing hosted simulators; missing device
+control prevents controlling them. For a Desktop-run server, allow its app
+in the same panes. Setup never changes TCC or enables Funnel. Funneled or
+unreadable routes refuse with a remedy. Tool checks print fixes for Xcode,
+simulator runtimes, CocoaPods, JDK, Android SDK and the Stim build; they install
+nothing. Android and CocoaPods checks are not needed for hosting alone.
+
+Plain progress goes to stdout; errors use `stim-server: <message>` on stderr.
+`--json` sends progress to stderr and prints one final payload with `ok`,
+`label`, `port`, `route` (state, DNS name, HTTPS port), `server` (version and
+Stim build), `managed`, separate `granted` request ids and client identities,
+`permissions`, `tools` and `warnings`. Final permission values are `granted`,
+`denied` (not authorized), `skipped` or `not-needed`; a timed-out wait remains
+`pending` in the journal and names its unavailable feature. Exit codes come
+from the final journal:
+
+| Exit | Meaning                                                                                                               |
+| ---- | --------------------------------------------------------------------------------------------------------------------- |
+| 0    | Every chosen capability, needed permission and tool is ready.                                                         |
+| 1    | A refusal or failed step. Completed earlier steps remain in place.                                                    |
+| 2    | No grant before expiry, or an already expired command.                                                                |
+| 3    | At least one grant, but another chosen capability, permission or tool is missing; the output names affected features. |
+
+Setup writes `$STIM_HOME/server/setup/<sha256(ticket)>.json` from its first
+step and after every change, including completion and the exit code. The
+node-bound `GET /setup/<hash>` route described above mirrors it until expiry,
+hiding tools until a build grant. Each valid setup run prunes journals more
+than one hour past expiry. A dedicated `server/setup.claims` ownership claim
+serializes runs; the service update claim is released before waiting for
+requests and permissions. A competing setup refuses with the exact claim
+and removal command. Ctrl-C or SIGTERM finishes the running step as failed
+with detail `interrupted`, completes the journal, releases the setup claim,
+and exits 1. A typed N also exits 1; a question timeout follows ticket expiry
+and exits 2.
+
+The summary lists what is ready and the undo commands:
+
+```bash
+stim-server devices revoke <build-request-id>
+stim-server devices revoke <device-host-request-id>
+stim-server service uninstall --label <label>
+```
+
+If route verification or recording fails, setup removes the route it just
+created; a failed removal prints the exact `tailscale serve --https=<port> off`
+remedy. Uninstall removes only a route the managed install created. A reused app's
+server and route remain managed by that app. If its health response omits
+permission grants, setup keeps those checks pending or lets a terminal skip
+them; Stim Host's grants do not stand in for another app's permissions. Pairings, Stim Host and its macOS
+permissions remain; remove permission grants in System Settings if desired.
+
 ## Tailscale
 
 Tailscale carries and encrypts the traffic between the phone and the Mac, on
@@ -52,7 +196,15 @@ cryptography of its own. You need Tailscale on the Mac and on the phone, in the
 same tailnet or with the Mac shared to the phone's user.
 
 `stim-server` listens only on `127.0.0.1` and on the Mac's Tailscale
-addresses, never on every interface. Run this once so clients can use
+addresses, never on every interface. It re-reads the Tailscale state in the
+background, so a server that started before Tailscale was up, or while it did
+not answer, starts listening on the Tailscale addresses once it runs, and stops
+when it goes away. In Stim Desktop, choose **Set up connection** in Settings >
+Phones to create and verify the private route without a terminal command. A
+missing or unreadable route keeps Desktop pairing unavailable; HTTPS setup may
+require Tailscale browser approval. Existing routes stay unchanged.
+
+For manual server setup, run this once so clients can use
 `wss://<mac>.<tailnet>.ts.net:7443` with a valid certificate:
 
 ```bash
@@ -73,6 +225,15 @@ Funnel port makes it public, and `pair` refuses.
 When Tailscale is not running, `stim-server` listens on loopback only and
 says so on stderr. Start Tailscale, then restart `stim-server`.
 
+Desktop uses `route.setup` with no parameters on its authenticated loopback
+control connection. The result is a verified `ServeRoute`; an existing route is a
+no-op. The server refuses forwarded, browser-origin or tailnet connections,
+read-only clients, unknown configuration and any route exposing this server
+through Funnel. Only the fixed `tailscale serve --bg --https=<free port>
+http://127.0.0.1:<server port>` invocation runs, followed by route verification.
+No LaunchAgent or Funnel configuration is created. Failure output remains
+available for an explicit retry, including Tailscale's HTTPS approval link.
+
 ## Pairing
 
 `stim-server pair` prints the JSON that the pairing QR code encodes:
@@ -102,20 +263,944 @@ A connection must send `hello` within 5 seconds. Five failed attempts from the
 same peer within a minute block new connections from it for up to a minute.
 
 Paired devices live in `$STIM_HOME/server/devices.json`. Revoking a device
-closes its open connections.
+closes its open connections. The server checks registrations on file changes
+and once a second, so a missed filesystem notification cannot leave a revoked
+connection authorized.
 
 ## Scopes
 
 A paired device has the `read` capability, which serves state, or also
-`control`, which runs [actions](#actions) and [controls devices](#control). Pairing grants `read` only, unless
-the pairing code came from `stim-server pair --control`. On the Mac,
+`control`, which runs [actions](#actions) and [controls devices](#control).
+With the `workspace-diff` feature, `read` also serves changed and untracked
+text file contents in registered workspaces, including any non-ignored
+untracked text file such as an unignored `.env`. Pairing grants `read` only,
+unless the pairing code came from `stim-server pair --control`. On the Mac,
 `stim-server devices grant <id> --control` adds control to a paired device and
 `--read` takes it away. Nothing a client sends changes its own capabilities.
 The server checks the device's capabilities in `devices.json` on every action
 and control session, and ends a device's control sessions when it loses
-`control`, so taking control away applies to open connections at once. `hello` reports
+`control`, so taking control away applies to open connections on the next
+registration check. `hello` reports
 the capabilities and actions of the connection's device when it connects; a
-connection sees a new grant after it reconnects.
+connection sees a new grant after it reconnects. Under Stim Host, an approved
+`hello` also carries the same `host` grants as `/health`, which `stim doctor`
+reports for hosting machines.
+
+Every method other than `hello` needs `read`. A device with only `build`
+gets `forbidden` for all of them.
+
+## Build access
+
+`build` lets another Mac on the tailnet run its project's code on this Mac to
+build for it: config plugins, CocoaPods hooks, Xcode script phases and Gradle
+plugins run as the user `stim-server` runs as. It never comes with `read` or
+`control`, and `devices grant` never turns a paired device into a build
+client. Grant it only to Macs you trust with that. A connection from this Mac,
+over loopback, cannot get it: it has no tailnet node to bind the token to.
+Because the server trusts `X-Forwarded-For` on loopback (see
+[Pairing](#pairing)), a process on this Mac can still claim a tailnet peer's
+address. Run `stim-server` as a user no one else can run processes as when
+other people use this Mac, and approve a request only when you expect it.
+
+A Mac gets `build` only by asking and being approved on this Mac. The client
+sends `hello` with `auth` set to `{ "request": "build", "deviceName" }`, a
+name of at most 64 UTF-16 code units with no control or format characters.
+The server records a pending build client bound to the peer's node, answers
+with a `deviceToken`, no capabilities and
+`approval: { "state": "pending", "expiresAt" }`, and closes the connection.
+`stim-server devices` lists it as `pending build`. On this Mac,
+`stim-server devices grant <id> --build` approves it, or a person runs
+[`stim-server setup`](#set-up-a-worker-mac) on this Mac with its node and ticket, and
+`stim-server devices revoke <id>` denies it; Stim Desktop's **Allow** and
+**Deny** run those commands. Until then, `hello` with its token
+fails with `approval-pending`, which does not count as a failed attempt, while
+the request itself does, so a peer cannot send more requests than failed
+attempts. A request lapses after 15 minutes. Each node has at most one pending
+request, the newest, and the server holds at most 8; more fail with
+`limit-exceeded`. There is no pairing code for `build`: `stim-server pair`
+never grants it.
+
+`devices grant` never gives `build` to a paired device, or `read` or
+`control` to a build client. Build clients live in
+`$STIM_HOME/server/build-clients.json`, apart from `devices.json`, so a
+`stim-server` release without `build` never reads them and refuses their
+tokens.
+
+## Device-host approval
+
+Device hosting has a separate `device-host` capability. An approved client can
+reserve, boot, reconnect to and stop its own iOS simulator or Android emulator
+through the protocol. It can deliver, install and launch a compatible iOS app
+bundle, Android APK or prebuilt macOS app, stream the iOS simulator or macOS app and control it. The hosted iOS
+app connects back to Metro on the client Mac. Automatic CLI placement and
+Android Metro and viewing remain in [#2266](https://github.com/appandflow/stim/issues/2266).
+
+The Stim client can name expected hosts with
+`stim settings set hosting.machines '["<mac>"]'` and request access with
+`stim doctor --fix`. It stores a separate private credential in
+`$STIM_HOME/device-host-machines.json`, pins the worker's tailnet node, and
+reports approval under `deviceHosts` in doctor JSON. Plain doctor makes no
+approval request. This setup does not yet place CLI sessions remotely.
+
+A client on the tailnet sends `hello` with
+`auth: { "request": "device-host", "deviceName": "Laptop" }`. As with a build
+request, the server returns a token and pending approval, then closes the
+connection. It binds the token to the peer's tailnet node. Requests expire
+after 15 minutes; each node keeps only its newest pending request of this kind,
+and at most eight device-host requests can be pending. Build requests have a
+separate limit. The same name validation and failed-attempt limit apply.
+
+On the hosting Mac, inspect `stim-server devices`, then approve the matching
+request with `stim-server devices grant <id> --device-host`, run
+[`stim-server setup`](#set-up-a-worker-mac) there with its node and ticket, or use **Allow**
+in Stim Desktop. Approve only an expected request: it authorizes that Mac to
+reserve session-owned simulators or emulators and run native app code. **Deny**
+or `stim-server devices revoke <id>` removes it; revocation also closes its
+open authenticated connections. The local-process trust boundary described in
+[Build access](#build-access) applies here too.
+
+Hosting clients live in `$STIM_HOME/server/device-host-clients.json`, separate
+from phone pairings and build clients. A hosting token grants no `read`,
+`control` or `build` access, including access to unrelated workspaces. Existing
+read, control and build tokens cannot gain hosting through `devices grant`.
+Loopback requests and `pair --device-host` are refused.
+
+### Hosted availability offers
+
+Before reserving, an approved hosting client can send:
+
+```json
+{ "id": 1, "method": "device-host.offer", "params": { "platform": "ios", "runtime": "27.0" } }
+```
+
+Use `platform: "android"` with optional `systemImage` and `deviceProfile`, or
+`ios` with optional `deviceType` and `runtime`. Use `macos` without selectors
+for the host architecture and macOS version. Omit selectors for the same
+installed defaults used by reserve. The response includes `platform`, the
+selected SDK `choice` (runtime/model/image and host architecture), `resources`,
+`capacity` and a nullable `declined` reason. An unavailable SDK choice is `null`
+with a reason; unknown or elevated memory pressure declines. The query creates
+no session, simulator, AVD or ownership claim.
+
+`capacity.running` counts every reservation not confirmed stopped, including
+unresolved sessions. `max` is `concurrency.maxDevices`; zero means uncapped and
+`available` is then `null`. Android offers also decline when all supported
+console ports are already recorded as occupied. macOS offers decline when all
+64 app slots are reserved. Resource values are advisory:
+`cpus`, five-minute `loadPerCore`, `memoryFreeBytes`, `memoryPressure` (nullable
+when unknown), and `workerDiskFreeBytes` (nullable when unreadable). Disk space
+is measured on the Stim home volume, which can differ from Android AVD storage.
+
+An offer is a snapshot, not a reservation or a boot guarantee. Capacity,
+memory, installed SDKs and local device producers can change before reserve;
+reserve still takes atomic admission and revalidates native preflight. A
+non-null choice with a non-null `declined` reason is currently unavailable.
+This protocol does not select a host for `stim ios` or `stim android`.
+
+### Agent driver route
+
+On the hosting Mac, `hosting.agentDriver` names the tool that lets a client's
+coding agent drive the macOS app hosted for that client. `none` (the default)
+starts nothing. `stim-server` reference-counts the driver's daemon on running
+hosted macOS apps: it starts with the first, stops after the last, on
+revocation and on server shutdown, and restarts if it exits while apps run. The
+daemon is held under an ownership claim at `server/agent-device.claims` whose
+child is the daemon, and its state lives in `server/agent-device`.
+
+Each hosted app gets a grant scoped to one client and one app. The grant's
+token is kept in memory only, is returned to that client in `app.launch` and
+`app.attach` results, and is never journaled or logged. The route
+
+```text
+ANY /device-host/agent/<session>/<driver path>
+```
+
+on the tailnet `serve` route is forwarded to the loopback daemon, with the
+daemon's own token, only when all of these hold: the request carries that
+session's token as a bearer token, it comes from the tailnet node pinned to the
+session's approved device-host client, the client still holds `device-host`, and
+the session's app is running. Loopback requests, browser requests and other
+sessions' tokens are refused with 403, an unknown or stopped session with 404.
+
+The `agent-device` adapter runs the binary that `STIM_AGENT_DEVICE_BIN` names
+in `stim-server`'s environment, or else the first of
+`~/.local/bin/agent-device`, `/opt/homebrew/bin/agent-device` and
+`/usr/local/bin/agent-device`; it never searches `PATH`. It starts
+`agent-device proxy` with the native macOS app backend and a daemon policy that
+admits only requests under a `macos-app` lease and only the commands that drive
+one app. It starts only when the daemon's `/health` lists the `macos-app` lease
+backend (callstack/agent-device#3229); otherwise the grant is
+`{ "driver": "none" }` with a notice, and Stim never hands out the Mac's desktop.
+
+For each running hosted app, the adapter allocates a `macos-app` lease for
+`<bundleId>@<pid>` over agent-device's loopback `/admin/leases` route with the
+daemon token, renews it while the app runs and releases it when the app stops
+or the grant is revoked. The grant carries the lease id and owner scope. The
+forward passes only `POST /rpc`, `GET /health` and `GET /artifacts/...`, and it
+rewrites every command and lease call to that session's lease, tenant and
+tenant session isolation, so a client cannot name another lease or session. It
+refuses commands outside the daemon policy's list (also inside a `batch`),
+drops device selectors and runtime hints, and sets `platform` to `macos`.
+
+### Hosted iOS session protocol
+
+An approved client sends `device-host.reserve` with an opaque attempt ID and
+its workspace/slot identity:
+
+```json
+{
+  "id": 1,
+  "method": "device-host.reserve",
+  "params": {
+    "workspace": "/client/app",
+    "slot": "default",
+    "platform": "ios",
+    "attempt": "run-1",
+    "deviceType": "iPhone 17 Pro",
+    "runtime": "27.0"
+  }
+}
+```
+
+Omit `deviceType` and `runtime` to use the worker's installed defaults. The
+response names an opaque session and its `preparing`, `ready`, `stopping`,
+`stopped` or `unknown` state. Native work runs in a separate bounded child, so
+the connection remains available. Poll `device-host.attach` with
+`{"session":"<id>"}` or `{"attempt":"run-1"}`; a ready session includes the
+exact simulator, runtime and architecture selected on the worker.
+
+After a lost reply or connection, replay the same reserve request or attach to
+its attempt. That resolves the same session; a changed request with that attempt
+is refused. Another attempt cannot replace an occupied workspace/slot. The
+client never supplies a worker filesystem path or another client's session.
+`device-host.stop` with `{"session":"<id>"}` deletes only its recorded,
+ledger-owned simulator. Poll attach for completion. A new attempt may reserve
+after the previous one is confirmed stopped. Stopped session homes and device records remain for reconciliation. At start,
+stim-server retires leftover stopped iOS and Android devices through their exact
+private ledger ownership.
+
+The worker persists the journal under `$STIM_HOME/server/device-host-sessions/`
+and chooses an isolated worker home under `$STIM_HOME/device-host/sessions/`.
+An uncertain create, child exit, journal or deletion outcome retains the slot
+as `unknown`. Explicit stop can reconcile a complete record after a server
+restart; a live or unverifiable owner is refused. Missing ownership records
+need operator investigation, never a replacement inferred from a simulator name.
+Revoking this client's approval stops its sessions without granting access to
+the worker's other devices.
+
+`concurrency.maxDevices` bounds hosted reservations atomically, including
+unresolved sessions. Ordinary local producers do not join that reservation
+transaction, so this is not a machine-wide hard capacity guarantee. Unknown
+inventory or elevated/unknown memory pressure refuses native creation. This
+protocol slice does not change `stim ios` placement.
+
+### Hosted Android session protocol
+
+The same reserve/attach/stop methods accept `platform: "android"` with optional
+`systemImage` (an installed `system-images;android-<api>;<tag>;<abi>` package)
+and `deviceProfile` (an installed avdmanager profile). iOS selectors refuse on
+Android requests. The image must match the host architecture. Omitted selectors
+use Stim's existing compatible installed-image and default-profile choice.
+The worker process needs an Android SDK and a JDK that `avdmanager` can use.
+
+```json
+{
+  "id": 1,
+  "method": "device-host.reserve",
+  "params": {
+    "workspace": "/client/worktree",
+    "slot": "default",
+    "platform": "android",
+    "attempt": "android-1",
+    "systemImage": "system-images;android-30;google_apis;arm64-v8a",
+    "deviceProfile": "pixel_6"
+  }
+}
+```
+
+A preparing Android result includes a server-selected `consolePort`. The journal
+reserves distinct ports among hosted sessions and excludes the ports in the
+host's local config. The worker refuses an observed occupied port before
+creation and before boot. Local producers do not participate in this reservation,
+so a racing local launch can still refuse a hosted boot; this is not a
+machine-wide hard port or device-capacity guarantee.
+
+A ready Android `device` has `avdName`, `serial`, `consolePort`, `systemImage`,
+`deviceProfile` and `architecture` (`arm64-v8a` or `x86_64`). The worker verifies
+its exact AVD name and running ABI before reporting ready. Creation remains
+inside the worker's claimed process group. The worker opens no emulator viewer.
+Stop and revocation use centralized teardown only for its private ledger's exact
+AVD. They delete that AVD and retain the session home and record. At start,
+stim-server retires leftover stopped sessions; unknown native outcomes retain
+the reservation and require explicit reconciliation. Android Metro
+and screen/input routing remain follow-ups in #2266. Android sessions
+refuse the iOS Metro, view and input routes.
+
+### Hosted iOS app delivery
+
+App offers, chunks and launches require a ready session held by this server.
+After its owner disappears, session attach reports `unknown`; app operations
+refuse until explicit stop reconciles the retained session. A ready journal
+entry alone does not authorize another native operation.
+
+Send `device-host.app.offer` with the ready session, a new opaque app `attempt`,
+the expected `bundleId`, `mode: "development"|"release"`, and
+`manifest: {"sha256":"<digest>","size":<bytes>}`. The manifest is a UTF-8 JSON
+array of `{path, kind, size, sha256}` entries, where `kind` is `file`, `exec` or
+`link`. Paths are relative to the `.app` root. A link's content is its relative
+target; it must resolve inside the bundle. No entry may sit below a file or
+link. Duplicate paths, including Unicode/case aliases, are refused.
+
+macOS offers may also include an optional `arguments` string array: at most 32
+entries, 1024 characters per entry and 8192 characters total, with no NUL, CR or
+LF. Empty strings are allowed; an empty array is omitted. Other session platforms
+refuse non-empty arguments. The host passes them as plain executable arguments,
+without environment injection, stores them in the app receipt and echoes them in
+delivery replies. They are visible in process listings, so do not put secrets
+there. Older hosts ignore this field; Stim warns to update `stim-server` on the
+host when its delivery does not report the requested arguments.
+
+An offer returns `{delivery, missing}`. Upload each missing digest with
+`device-host.app.chunk` and `{session, attempt, sha256, offset, data}`; `data` is
+base64 for at most 32 KiB of raw bytes. The reply names the next byte `offset`.
+Replay of the same bytes is safe after a lost reply. Re-offer to learn received
+offsets. Upload the manifest first, then re-offer for its missing file content.
+The manifest is limited to 8 MiB and 20,000 entries, with at most 1 GiB per file,
+1 KiB per link, and 4 GiB of declared bundle content. An app attempt cannot
+change its identity, mode, arguments or manifest. Complete a receiving attempt or stop the
+session before starting another transfer. Manifest, file and partial blobs are shared
+by attempts of one session in its content-addressed store; offers recheck complete
+blob digests and request only missing bytes.
+
+An iOS simulator or macOS session can take its content from a build this Mac ran instead: after
+the manifest arrives, send `device-host.app.handoff` with
+`{session, attempt, build: {handoff, sha256}}`, where `handoff` is the token
+and `sha256` the archive digest from that job's `build.artifact` answer. The
+server hands the build over only when the build client that ran it still has
+`build`, the caller has `device-host`, and both approvals belong to the same
+tailnet node. It copies only regular files, and links where the manifest
+declares links, whose directory resolves inside the staged bundle and whose
+bytes match their manifest digest; it answers `{files, bytes}` for what it
+took. The token is spent once the handoff starts. Re-offer and upload whatever
+is still missing; an older server answers `unknown-method`. For iOS, check the
+`hosted-ios-data` hello feature before requesting handoff; without it, upload.
+
+After every digest is verified, call `device-host.app.launch` with
+`{session, attempt}`. Poll `device-host.app.attach` for `installed` or `unknown`.
+Reconnect to the same app attempt to reconcile a lost launch reply; replay
+does not install or launch twice. Session attach includes the latest
+`appAttempt`. Development offers may include `devClientScheme` for an Expo
+development client; the attempt cannot change that scheme. The worker verifies the plist identity and simulator metadata,
+the executable's Mach-O platform, architecture and minimum OS, then rechecks
+the exact private device ledger before install and launch.
+
+Development launch reports `launched: "unverified"`: a bridge or native process
+alone does not prove bundle delivery. Release launch reports `true` only after observing a live native app
+process; absent evidence remains `"unverified"`. Stop and approval revocation
+cancel an in-flight install before shutting down the owned simulator. Uncertain
+native outcomes retain the session as `unknown`; explicitly stop it before
+retrying. Receipts and artifacts remain in the server-chosen session area;
+artifact retention and session reuse/retirement remain under
+[#2266](https://github.com/appandflow/stim/issues/2266) and
+[#2348](https://github.com/appandflow/stim/issues/2348).
+
+### Hosted Android app delivery
+
+Android sessions use the same app offer/chunk/launch/attach methods, with
+`bundleId` naming the expected Android package. Their manifest has exactly one
+`file` entry named `App.apk`, with the APK's byte size and SHA-256. Upload the
+manifest first, then the APK through the same resumable 32 KiB chunks.
+
+The worker verifies both digests, inspects the APK's package identity, minimum
+SDK and native library ABIs with installed Android build-tools, and rechecks the
+private ledger, exact running AVD and ABI before installation and launch. It
+resolves adb from that SDK even when the worker PATH does not include it. A
+signature or installation conflict refuses; hosting does not uninstall an
+existing app to resolve it.
+
+Release launch reports `true` only after observing a live package process.
+Development launch remains `unverified`; this driver launches the activity but
+does not wire an Android Metro bridge. Replaying an installed app attempt does
+not install or launch again. Owner loss, stop, revocation and uncertain outcomes
+retain the same reconciliation rules as iOS. Android viewing, Metro and client
+placement remain under [#2266](https://github.com/appandflow/stim/issues/2266).
+
+### Hosted macOS app sessions
+
+The same offer/reserve/attach/stop methods accept `platform: "macos"` without
+selectors. A macOS reservation counts toward `concurrency.maxDevices` and takes
+the lowest free `appSlot` from 1 through 64. Unresolved sessions retain their
+slot; only a confirmed stop frees it. The ready device describes the host's
+`architecture` (`arm64` or `x86_64`), `macosVersion` and `appSlot`. No simulator,
+emulator or created-device ledger entry is needed.
+
+```json
+{
+  "id": 1,
+  "method": "device-host.reserve",
+  "params": {
+    "workspace": "/client/app",
+    "slot": "default",
+    "platform": "macos",
+    "attempt": "macos-1"
+  }
+}
+```
+
+Deliver a prebuilt `.app` using the same digest manifest and resumable chunks.
+The manifest must include `Contents/Info.plist` as a file and an executable under
+`Contents/MacOS/`. Only release offers are accepted, with no `devClientScheme`
+and no `com.apple.` bundle identity. The host verifies the plist identity,
+contained executable, architecture slice, MACOS Mach-O platform and minimum OS.
+URL registrations (`CFBundleURLTypes`) and update feeds (`SUFeedURL`) refuse.
+
+Before launch the worker stamps `<bundleId>.hosted<appSlot>` and ad hoc signs
+its frameworks and bundle. That identity must fit within 249 characters so its
+`.plist` preferences filename fits within the 255-byte filename limit. The
+existing macOS supervisor owns the app process, with `HOME`, `CFFIXED_USER_HOME`
+and `TMPDIR` pointing into the session's private app home. This is home and
+identity isolation, not an OS sandbox for the client's native code.
+The supervisor and app receive only the host's set `PATH`, `LANG`, `LC_ALL`,
+`LC_CTYPE`, `USER`, `LOGNAME`, `SHELL` and `TERM`, plus the worker `STIM_HOME`
+and isolated home and temporary paths.
+`launched: true` requires matching live app and supervisor process identities.
+Stop and revocation verify and stop those processes, then delete only the last
+recorded hosted bundle identity's preferences domain and plist. A replacement
+app with a different identity removes the prior hosted identity's preferences
+after stopping its processes. macOS preferences use the real user's preferences
+service despite the isolated home. Stop removes the app home and delivered bytes
+from every app attempt, keeping logs and receipts so `app.attach` can still report
+the recorded state.
+
+Once a macOS app is `installed`, `device-host.app.launch` and
+`device-host.app.attach` return the agent grant the host's driver issued for that
+session, or `agent: { driver: 'none' }` while no driver runs or it cannot scope
+the app; the driver's reason, if any, is the result's `notice`. The field is
+built for the response and never stored in the receipt or journal; it is absent
+before installation, after stop and for iOS and Android sessions. The worker
+reports the app's pid, `DeviceHost` registers the running app with the agent
+driver before the receipt reads `installed`, and ends that registration when the
+session stops, is revoked or the server closes.
+
+`device-host.logs.query` with `{session, cursor?}` returns `{records, cursor, more, checkpoint?}`:
+the NDJSON records the session's macOS app wrote to its captured log (stdout and
+stderr as `client` records, and its exit). iOS sessions capture app-filtered native
+logs as `device` records through bounded `simctl log show` worker queries, with
+a persisted time checkpoint in the isolated home. Windows adapt to the backlog,
+overlap by five seconds and de-duplicate event identities. `checkpoint` is the last
+completed iOS window in epoch milliseconds. `log show` reads persisted entries;
+info-level entries and persistence delayed beyond the overlap may be unavailable.
+The worker holds a separate child-aware log claim. Queries coalesce onto an
+in-flight collection or read captured files; collection starts at most once every
+three seconds per session. App offers, chunks, handoff, launch admission, view and
+control stay available. Installation and stop cancel and settle collection under
+bounded worker and termination deadlines before native work. Each native collection has a
+10-second step budget inside its 15-second worker deadline. The client drain has
+a 30-second bound, reports progress on stderr and stops on a stalled cursor and
+checkpoint. The host collects once more before deletion on stop, revocation or
+server close, preferring the recent tail if the remaining backlog will not fit.
+If the final collection drops a backlog interval and eventually succeeds, one
+`device` warning record names the interval. Missing or damaged checkpoints are
+ignored and rebuilt; they never prevent reading collected logs.
+The client waits up to 180 seconds for stop. The worker paths fit within that
+wait: the 90-second stop worker,
+15-second final collection and up to three 10-second worker group-settle bounds
+leave 45 seconds for polling and transport. An in-flight handoff copy and closing
+Metro or view transports are outside those worker bounds.
+The client pulls that final collection after stop. Stop removes the session blob
+store and materialized apps, retaining receipts and collected logs. `cursor` maps each log file name to the
+byte offset after the last complete line read; pass the previous result's cursor to
+receive only newer records, and repeat while `more` is true. Without a cursor, each
+file starts at most 4 MiB before its end. A page holds at most 1 MiB; a file that
+rotated since the cursor is read from the end of its previous generation. The
+session's own client only, for iOS and macOS sessions, and also after the session stopped,
+because stop keeps captured logs. iOS clients check hello feature `hosted-ios-data`;
+without it, they show an update note and copied logs. Servers that predate macOS queries answer `forbidden` or
+`unknown-method`.
+
+macOS sessions refuse Metro. Viewing and control are supported while the hosted
+app is running. Automatic CLI placement remains a follow-up in [#2403](https://github.com/appandflow/stim/issues/2403).
+
+### Private hosted Metro
+
+The client keeps its verified workspace Metro on loopback. It creates a
+`createMetroGateway` from `@stim-cli/core`, binds it only to its own Tailscale
+address, and supplies the pinned worker's literal tailnet address, local Metro
+port and a fresh 32-byte secret encoded as 64 lowercase hex characters. The
+gateway accepts only that worker address and authenticates each connection
+before forwarding to the fixed local Metro port. It never targets a client
+supplied URL. Close the gateway when its session ends.
+
+Call `device-host.metro.open` with `{session, gatewayPort, secret}` on the
+approved hosted connection. The server connects only to that connection's
+authenticated tailnet peer and returns `{port}` for the worker's loopback
+endpoint. Development installation uses that port for `RCT_jsLocation` and,
+when offered, the Expo development-client deep link. HTTP and WebSocket bytes
+stream over WireGuard with socket backpressure; no public tunnel, Funnel or
+Tailscale serve configuration change is needed. The 64 KiB server message
+limit remains unchanged.
+
+Replaying the same open request keeps the port. Client disconnection leaves
+the bridge available for the same session while its server owner lives. Call
+`device-host.metro.close` to replace a gateway, then reopen on the same port;
+an occupied port refuses rather than sending the app to another listener.
+Closing a bridge interrupts its active streams. Stop, revocation and server
+shutdown close its sockets before device retirement. After a server owner
+disappears, the retained session requires explicit stop, as app delivery does.
+
+Expo dev-launcher and CLI versions that send and honor the `Forwarded` header
+resolve relative manifest URLs against the worker origin. Older versions may
+embed the client's local port instead; this slice does not rewrite manifests
+or claim that those versions work through a different worker port. Client
+placement still needs to check that contract before selecting hosted Metro.
+Bare React Native uses the worker `RCT_jsLocation`. Bridge readiness and
+manifest requests are not launch proof; development remains `unverified` until
+the workspace observes the app's own bundle delivery.
+This is a protocol API for approved clients; automatic iOS CLI placement,
+Android Metro/viewing remains in [#2266](https://github.com/appandflow/stim/issues/2266).
+
+### Hosted viewer relay
+
+The client's stim-server relays a hosted workspace's iOS simulator or macOS view and input to
+its host using the client's approved device-host credential over the pinned
+tailnet connection. Stim Desktop and phones keep talking only to their own
+server. The `macos-hosted` and `ios-hosted` features advertise these relays.
+iOS resolves `ios.host` by the requested slot; macOS retains its default slot.
+The local platform and slot replace the host's private target fields in events
+and iOS control audit records. H.264 packets retain their flags and payload and
+carry the local subscription ID, which identifies the platform and slot.
+The relay forwards iOS device artwork and orientation metadata. Hosted targets
+refuse replay (`at`/`rate`), `duoFrame` and `physical` with `bad-request`.
+All of the client's relayed subscriptions and control sessions for one host share one connection,
+whichever local client opened them. Each request still checks the credential
+and the pinned node; a changed credential or endpoint opens a new connection.
+Ending a subscription or session sends `device-host.unsubscribe` or
+`device-host.control.end`, and the connection closes when the last one ends.
+The host's per-connection limits, such as its 32 subscriptions and input
+budgets, therefore apply to all of the client's relayed use of that host.
+While a local client is behind on a relayed H.264 subscription, the relay drops
+its packets until the next keyframe and, when the host advertises the
+`hosted-congestion` feature, sends `device-host.frames.congested` at most every
+250 ms, so the host lowers that app's bitrate as it does for a local subscriber
+whose socket backs up.
+Hosted macOS frames and control require the default slot; hosted iOS supports named slots.
+`control.begin` still needs the local `control` grant. For macOS apps, Screen Recording for
+viewing and Accessibility for control are granted on the host, not the client.
+
+### Hosted iOS and macOS view and input
+
+An approved hosting client can subscribe to its ready session's exact owned
+iOS simulator or running macOS app without access to the worker's registered
+workspaces:
+
+```json
+{
+  "id": 8,
+  "method": "device-host.frames.subscribe",
+  "params": { "session": "<hosted-session-id>", "fps": 5, "maxEdge": 1280 }
+}
+```
+
+The result contains a subscription ID. JPEG delivery uses the existing `frame`
+events; `video: ["h264"]` selects the existing H.264 binary stream and its
+backpressure/keyframe rules. `device-host.frames.keyframe`,
+`device-host.frames.congested` and `device-host.unsubscribe` take that
+subscription ID as `params.subscription`. `device-host.frames.congested`
+(feature `hosted-congestion`) reports that a client further downstream is
+behind on that H.264 subscription; it lowers the bitrate the same way a backed-up
+socket does.
+Hosted capture requires the compiled `stim-frames` helper and does not support
+replay, device artwork or screenshot fallback. macOS frames show only the one
+window of the hosted app. Viewing is refused before launch and after the app
+exits. On the hosting Mac, `stim-server service install` runs the server and
+`stim-frames` under Stim Host, whose Screen Recording and control grants they
+need. Install shows macOS's own requests; `stim-server service status` shows the
+grants. Servers launched by Stim Desktop keep Desktop's grants. Missing Screen &
+System Audio Recording ends the stream; missing Device Control and Data Access
+(Accessibility on macOS 26 and earlier) leaves viewing available.
+See [Run as a service](#run-as-a-service) for the settings panes and Dev caveat.
+
+Start control with `device-host.control.begin` and
+`{"session":"<hosted-session-id>"}`. Its result returns a connection-bound
+control session ID and `lease: null`: the hosted lifetime claim protects this
+private device. Only one controller can drive the device; `takeOver: true`
+replaces the previous controller. Use the returned control ID with
+`device-host.input.touch|text`, using the same parameters as ordinary input.
+iOS also supports `device-host.input.button|rotate|posture`. macOS also supports
+`device-host.input.scroll|key`; these two methods are for macOS sessions only.
+Touch coordinates range from 0 to 1 on the streamed display.
+End it with `device-host.control.end` and `{"session":"<control-id>"}`.
+
+The worker derives the workspace, slot and device or app identity from its owned
+session; callers cannot select arbitrary worker devices. Every begin and input rechecks session
+ownership and current approval. Hosting approval grants neither ordinary
+`frames.subscribe` nor ordinary `control.begin` access. Disconnecting releases
+that connection's capture and input; reconnect to the same hosted session and
+subscribe again.
+
+Installation, stop, revocation and server close end capture and input before
+native work reuses the session claim. In-flight native input settles before
+teardown even after disconnect or takeover; a timeout waits for its child to
+terminate. Known capture closes even if the journal
+is unreadable or unwritable; unresolved native state and claims remain retained.
+Hosted posture commands hold a separate child-aware input claim. A surviving
+command or unresolved child identity blocks replacement ownership, install and
+stop even after the server and capture helper exit; the refusal names the claim
+and its manual cleanup command. An unknown or lost owner requires explicit stop
+before replacement. This worker
+protocol does not add CLI placement or a local viewer relay; those remain in
+[#2266](https://github.com/appandflow/stim/issues/2266).
+
+## Run as a service
+
+`stim-server service install` runs stim-server as a per-user LaunchAgent on
+macOS, so a build machine or a phone-serving Mac keeps it running without a
+terminal:
+
+```bash
+stim-server service install [--port <n>] [--label <name>] [--serve]
+                            [--env KEY=VALUE]... [--path-prepend <dir>]...
+stim-server service status [--label <name>] [--json]
+stim-server service update [--label <name>] --release <version>|--from <dir>
+stim-server service rollback [--label <name>]
+stim-server service uninstall [--label <name>]
+```
+
+`install` writes `~/Library/LaunchAgents/<label>.plist` (label `dev.stim.server`
+by default) and starts it with `launchctl bootstrap gui/<uid>`. The job starts
+Stim Host, which stays alive as the parent of the absolute `node` and
+`stim-server.mjs` of the install that ran the command, on
+`--port` (default 7787), with `RunAtLoad`, `KeepAlive` and a 30 second
+`ThrottleInterval`, and logs to `~/Library/Logs/Stim/<label>.log`. When
+`STIM_HOME` or `SHELL` is set in the installing shell, the job carries it. It
+takes the `node` from PATH when that path resolves to the running binary, so a
+Homebrew Node upgrade does not break the plist. Running `install` again
+rewrites the plist and restarts the job; if the new job cannot start, it puts
+the old plist and job back. `install` and `uninstall` act only on a plist
+that `install` wrote, and refuse a port that another stim-server (Stim
+Desktop's, for example) already answers on. Install from a permanent
+installation, not from an `npx` cache, because the plist stores its paths. It never touches pairings, anything
+under `$STIM_HOME/server` or settings. `install` waits up to 15 seconds for a
+`/health` answer that is no longer `pending`. An installed LaunchAgent with no
+answer reports readiness as unavailable, and one that answers `degraded` reports
+the reason; both point to `status` and its log. Installation success alone does
+not prove that the server is ready.
+
+Install downloads the Stim Host release this package pins from the
+`host-v<version>` GitHub release, checks the pinned SHA-256 and App & Flow's
+Developer ID signature, and installs **Stim Host** (`dev.stim.host`) at
+`~/Applications/Stim Host.app`; grants then survive Stim Host updates. Install
+keeps an identical bundle untouched. A Mac that ran the earlier **Stim Host Dev**
+keeps `~/Applications/Stim Host Dev.app`; its owner can delete it and its System
+Settings entries.
+
+After starting the service, install shows macOS's own permission requests on
+this Mac's screen, one at a time: Stim Host keeps running after install returns,
+asks for Device Control and Data Access once the Screen Recording request is
+answered (it waits up to two minutes for each), and opens that System Settings
+pane with Stim Host listed when macOS shows no request for it. You only
+approve; over SSH, use Screen Sharing to see that screen. If a request does not
+appear, turn Stim Host on in **System
+Settings > Privacy & Security > Screen & System Audio Recording** (**Screen
+Recording** on macOS 14) and **Device Control and Data Access** (**Accessibility**
+on macOS 26 and earlier). Stim never changes these settings itself. Servers
+launched by Stim Desktop keep Desktop's grants. For an older node-first service,
+run `stim-server service install` again to use Stim Host.
+
+The server binds its port before it touches the Stim home. It then reads the
+Stim home, its `server` and `workspaces` directories and the recording
+ownership directories in a read-only child process, so a read that never
+returns, such as one on a stalled external volume, cannot block the server's
+event loop. Until that read returns, `/health` answers HTTP 503 with
+`startup: { "state": "pending" }`, WebSocket upgrades and device-host agent
+requests get 503, and no status follower, native helper, file watcher or
+recorder starts. A read that does not return within 10 seconds, plus up to one
+second to stop the child, leaves the server listening with
+`startup: { "state": "degraded", "reason": "..." }` and HTTP 503 on `/health`,
+logs the reason once, and reads again every 30 seconds. When a read returns,
+the server starts its watchers and recorder, `/health` answers 200 with
+`startup: { "state": "ready" }`, and no restart is needed. `service status`
+prints `health: degraded` or `health: starting` and the reason, and `service
+install` reports a listening but degraded server instead of success. Returned
+filesystem errors still go through the recorder's existing claim refusal;
+missing directories are created by that protocol. The check preserves claims and
+recordings. It does not restore an inaccessible volume or change the server's
+permissions, and a stall that starts after the check passes still blocks the
+server until the operating system returns.
+
+The job runs in your GUI login session, so it starts when you log in and not at
+boot. On a Mac with no one at the screen, turn on automatic login. Moving the
+install, or changing its Node, needs `install` again.
+
+`--serve` adds the tailnet-only route from [Tailscale](#tailscale) on the port
+`stim-server` would suggest. It refuses when Funnel is on for a port that
+reaches the server, and it never enables Funnel. When a route already reaches
+the port, `install` records that it did not create it. `uninstall` removes a
+route only when `install` created it and it still points at this port. Without
+`--serve`, `install` prints the command to run. A route that exists only in a
+foreground `tailscale serve` session counts as present. To move a service that
+created a route to another `--port`, run `uninstall` first.
+
+`--env KEY=VALUE` and `--path-prepend <dir>` pin variables and PATH entries for
+the server. stim-server replaces its environment with the login shell's at
+start, so a `PATH` or `GEM_HOME` in the plist alone is lost and an entry in
+`~/.zshrc` changes the terminal too. These flags apply after that capture, to
+the server and to the builds it starts, and the plist stores them as
+`ProgramArguments`. `--path-prepend` puts directories in front of PATH in the
+order given; `--env` cannot set `STIM_HOME`. The values sit in plain text in the plist and in the process arguments, so do not pass secrets. For a private CocoaPods:
+
+```bash
+stim-server service install --serve \
+  --path-prepend /Volumes/SSD/gems/bin \
+  --env GEM_HOME=/Volumes/SSD/gems --env GEM_PATH=/Volumes/SSD/gems \
+  --env LANG=en_US.UTF-8 --env LC_ALL=en_US.UTF-8
+```
+
+`status` prints whether launchd loaded the job, its state, pid, run count and
+last exit code (a server that exits at start, for example on a port in use,
+restarts every 30 seconds), the `/health` answer, the serve route and whether
+`install` created it, the host app and its permission grants, the log path, and the digest of the bundled Stim's build
+next to the `stim` on PATH. Offload needs the same digest on the client, so a
+mismatch there is not an offload match either. `--json` prints the same fields
+as one object.
+
+`update` installs another stim-server beside the one the job runs and switches
+the job to it. `--release <version>` takes an exact version from the public npm
+registry (`https://registry.npmjs.org/`, never a registry `.npmrc` names), and
+npm checks each package against the registry's integrity. `--from <dir>`
+installs the `.tgz` packages in that directory, such as `pnpm pack` output of
+the `@stim-cli/core`, `@stim-cli/cache`, `@stim-cli/metro`, `stim` and
+`@stim-cli/server` packages of a checkout, and records each file's sha256.
+Either way, `npm audit signatures` must verify the registry signature of every
+package that came from the registry, and the provenance attestation of each one
+that has it, or the update stops before it touches the job. Install scripts
+never run. Each install goes to
+`~/Library/Application Support/Stim/services/<label>/versions/`, in a directory
+named by its version, Stim build and server code, and must start with the job's
+`node` before the switch. `update` then waits up to 30 minutes for `/health` to
+report no offloaded build and no hosted session (a server older than `busy` in
+`/health` restarts without waiting), rewrites only the server script in the
+plist (recording the previous one), restarts the job and waits up to 90 seconds
+for `/health` to answer with the new version and Stim build. When it does not,
+`update` puts the previous plist back and restarts it. Interrupt signals wait
+for the switch to finish. A second update to the same build reuses its
+directory, and after a switch `update` removes the installs neither the current
+nor the previous script uses. `rollback` switches the job back to the previous
+script under the same checks, and running it again returns to the newer one.
+Neither touches the node, the host app, the `--env` and `--path-prepend` pins,
+pairings, approvals, `$STIM_HOME` or the serve route. Install, update, rollback
+and uninstall of one label run one at a time.
+
+`uninstall` boots the job out, removes the plist, the servers `update`
+installed and, when `install` created it, the serve route. Logs, pairings and the host app stay; other labels may use the app. Use `--label` and `--port` to run a
+second service beside the first, for example with another `STIM_HOME`.
+
+To set up a build machine: install Stim and stim-server on the Mac, run
+`stim-server service install --serve` (with the pins its toolchain needs), set
+`offload.workerRoot` there, and on each client run
+`stim settings set offload.machines '["<mac>"]'` and `stim doctor --fix`.
+Approve the request on the build machine with
+`stim-server devices grant <id> --build`.
+
+## Remote update
+
+A Mac this one approved for builds (`--build`) or device hosting
+(`--device-host`) can update this Mac's `stim-server service` over its tailnet
+connection, so the build machine keeps up with the client without ssh. A
+server that offers it lists `server-update` in its `hello` features. A paired
+phone, a `read` or `control` device and a connection from this Mac cannot. The
+methods need that approval, not `read`:
+
+- `server.update.status` returns `server` (`version` and `stimBuild`),
+  `service` (the label of the LaunchAgent this server runs under, or `null` when
+  it does not run as a `stim-server service` and so cannot update itself),
+  `acceptsClientBuilds`, `running` (the update in progress, with its `state`,
+  `missing` package bytes and the last lines of its `log`) and `last` (how the
+  label's last `service update` ended, whoever ran it).
+- `server.update.start` takes `{ "release": "<version>" }`, an exact version
+  that `stim-server service update --release` installs, or
+  `{ "packages": [{ "name", "size", "sha256" }] }`, at most 8 `.tgz` packages
+  of the client's own build. Packages need `server.acceptClientBuilds` set to
+  `true` on this Mac (`stim settings set server.acceptClientBuilds true`); a
+  release needs no setting. One update runs at a time.
+- `server.update.chunk` takes `{ id, name, offset, data }`, at most 32 KiB of
+  base64 at the package's next offset. A package whose bytes do not match its
+  `sha256` ends the update. The upload lapses after 10 minutes without a chunk.
+
+Once the release is named or the last package arrives, the server stops taking
+new offloaded builds and hosted sessions, and runs
+`stim-server service update --label <label> --release|--from` with its own
+node and script as a detached process, which outlives the restart it causes
+and writes to `~/Library/Application Support/Stim/services/<label>/update.log`.
+The connection closes when the job restarts. The client reconnects and reads the
+outcome from `hello` and `server.update.status`. An update that ends while this
+server still runs (a refused upload, a failed install) takes new work again.
+The action log records each update as `server.update.started`, and as
+`server.update.ended` when it ends while this server still runs. A chunk that
+arrives once every package is in gets `action-busy`, and a retried reservation
+of an existing hosted session still answers during the drain.
+
+Stim Desktop starts these updates through its own local stim-server with two
+methods that only the local Desktop control connection may call:
+`machines.update.start` takes `{ "machine" }`, an approved `offload.machines`
+or `hosting.machines` entry. It connects to that machine's pinned node with
+the stored credential and asks it for this server's npm release. When this
+server runs from a Stim checkout, it instead packs the checkout's workspace
+packages as `npm pack` would and sends them. `machines.update.status` takes
+the same `{ "machine" }` and returns `remote` (the machine's
+`server.update.status`), `unreachable` (why it could not be read, also while it
+restarts) and `upload` (`sent`, `total` and `error` of the packages).
+
+## Offloaded builds
+
+A client with `build` runs its iOS simulator builds and Android emulator
+debug builds and macOS SwiftPM Debug builds here with these methods.
+They need `build`, not `read`; a device without `build` gets `forbidden`.
+The server re-reads the build clients on every call, and revoking a client
+closes its connections and cancels its builds.
+
+- `build.offer` takes `repo` (the client's name for its repository: letters,
+  digits, `.`, `_` and `-`, at most 80) and an optional `lockfile` sha256. It
+  returns `toolchain` (`stimBuild`, a digest of the bundled Stim's built code;
+  `arch`; `xcode`; `simulatorSdk`; `macosSdk` (from
+  `xcrun --sdk macosx --show-sdk-version`); `cocoapods`; `runtimes`, the simulator
+  runtimes with an iPhone simulator to build for; `jdk`, the major version of
+  the JDK in `JAVA_HOME` or the macOS default; and `androidSdk`, the `ndk`,
+  `buildTools` and `platforms` directories of the SDK in `ANDROID_HOME` or
+  `~/Library/Android/sdk`, null without one), `capacity` and `warm`
+  (`checkout`, `dependencies` when the last install used that lockfile, and
+  `build` once a build ran there, including a non-empty repository `macos/`
+  scratch directory) for that repository. `capacity` holds
+  `running` and `max` offloaded builds, `diskFreeBytes` of the worker root's
+  volume and `minDiskFreeBytes`, `cpus`, `loadPerCore` (the 5-minute load
+  average per CPU), `builds` (this Mac's own Stim runs in prebuild, pods or
+  compile that it did not offload, plus the offloaded builds it runs), `maxBuilds` (its
+  `concurrency.maxBuilds`, 0 when unlimited), `maxLoadPerCore` (its
+  `offload.maxLoadPerCore`, default 2), and `declined`: why it would refuse a
+  build now, or null. It declines while it runs its limit of offloaded builds,
+  while the worker root's volume has less than 10 GiB free, while `builds`
+  reaches a non-zero `maxBuilds`, or while `loadPerCore` is at or above
+  `maxLoadPerCore`. The toolchain is read at most once a minute; capacity on
+  every offer.
+- `build.sync` takes `repo`, `files` and `done`. `files` is one page of the
+  manifest, each `{ "path", "kind": "file"|"exec"|"link", "size", "sha256" }`,
+  a link's blob being its target. Pages accumulate until `done`; the next
+  `build.sync` starts a new manifest. A path is relative, with no `.`, `..`,
+  empty or `.git` component (in any case). The result's `missing` lists the digests of the
+  page this Mac lacks. The client then sends each as binary frames: 32 bytes of
+  the sha256, then the next bytes of that blob, one blob after another. A frame
+  for a blob that was not asked for, one that overruns its size, or bytes that
+  do not match the digest close the connection with 4400. Blobs are kept per
+  client and shared by all its repositories.
+- `build.start` takes `repo`, `project` (the app directory in the repository),
+  `platform` (`ios`, `android` or `macos`), `configuration`, `scheme`, `runtime` (a
+  simulator runtime identifier, required for `ios`, null for `android`),
+  `fingerprint`, `packageName`, `isExpo`, `optimizations`, `android` (for
+  `android`: `variant`, `abi`, `gradleBuildCache`, `pch` and `compilerCache`,
+  `ccache` or `none`) and `stimBuild`, after the whole manifest of `repo` was
+  synced on this connection. It returns `{ "job" }`. It fails with
+  `build-busy` while the offer would be declined, naming the reason, or while
+  another build of the same client and repository runs, or while every one
+  of this Mac's `concurrency.maxBuilds` slots is held, and with
+  `build-refused` when `stimBuild` differs. The build runs `offload-worker.mjs` of the bundled Stim with
+  `STIM_HOME` set to the repository's area. It makes the area's checkout
+  hold exactly the manifest (a file git lists as untracked and not ignored,
+  and not in the manifest, is deleted; ignored dependencies and generated
+  projects stay), installs JavaScript dependencies when the lockfile changed,
+  runs prebuild and `pod install` when needed, refuses unless the fingerprint
+  equals `fingerprint`, and runs `xcodebuild` for one of this Mac's iPhone
+  simulators on `runtime`, which it never boots, or Gradle's
+  `assemble<variant>` for `abi` with ccache under the area's Stim home. A
+  Gradle daemon leaves the build's process group, so no claim or slot tracks
+  it. An Android build keeps the client's daemon warm, with Gradle's idle
+  timeout set to `offload.gradleDaemonIdleMinutes` (default 30; 0 stops it
+  when the build ends), and stops it when the build gets SIGTERM. Gradle
+  fixes a daemon's idle timeout when the daemon starts, so a new value
+  applies to the next daemon. Once no build of that client runs, stim-server
+  sends SIGTERM to each daemon whose command line runs from the client's
+  Gradle home when a build of the client was cancelled, when the client
+  loses `build`, and, for every client, while this Mac has less than 2 GB of
+  available memory (total memory minus Activity Monitor's Memory Used). It
+  checks every minute and on each change under its server directory. A daemon
+  whose Gradle home is deleted stops itself within seconds, because Gradle
+  expires a daemon whose registry file is gone.
+  A macOS request supplies `macos: { product, infoPlist, bundleId }` and
+  optionally `resources` (up to 256 destination-to-source entries) and
+  `assetCatalog` (a string or null), omitting runtime, configuration, scheme, packageName, isExpo, optimizations and android.
+  Product matches `^[A-Za-z0-9_.-]{1,100}$`; infoPlist is a valid relative build
+  path within the project; bundleId matches `^[A-Za-z0-9][A-Za-z0-9.-]{0,199}$`.
+  Each `resources` destination must be a contained path under
+  `Contents/Resources` (no empty, `.` or `..` segments, no backslash, at most
+  1024 characters) and each source, like `assetCatalog`, a valid build path
+  relative to the repository root, not the project. Missing or malformed
+  options get `bad-request`. Its fingerprint is sha256 of
+  every manifest entry sorted by path, encoded as `path NUL kind NUL sha256 LF`.
+  The worker recomputes it before building and refuses a mismatch. It skips
+  JavaScript installation, prebuild, pods and project fingerprinting. It runs
+  `swift build -c debug --product <product> --scratch-path <scratch> --cache-path <cache>`,
+  then `swift build -c debug --scratch-path <scratch> --cache-path <cache> --show-bin-path`,
+  without a jobs limit. Scratch is `repos/<repo>/macos/<project with / replaced by _>`,
+  or `root` for an empty project. The job JSON includes `swiftpmCache` alongside
+  `blobs`, pointing at the client's `cache/swiftpm`. Swift stays in the job's
+  process group so cancellation stops it. A failed Swift command reports
+  `swift-failed` with the first error or last three output lines. The worker
+  stages the executable, frameworks and resource bundles in
+  `out/<job>/<Product>.app`, copies each declared resource from its checkout
+  (refusing a source whose realpath leaves it), compiles `assetCatalog` with
+  `xcrun actool`, stamps the requested bundle ID and signs ad hoc. A bad
+  resource entry also reports `swift-failed`, before Swift runs.
+  It returns that app as a tar archive, its manifest fingerprint, timings and
+  `compilationCache: {}`. The client verifies the digest, identity, executable
+  and signature before promotion and launches locally. Every offload failure
+  falls back locally; macOS artifacts are not cached. Matching Xcode and macOS
+  SDK are required, and the worker needs network access for the first SwiftPM
+  dependency fetch; the dependency cache is shared only within that client.
+- `build.progress` events `{ "event": "build.progress", "job", ... }` carry a
+  `phase` and `msg`, a build-log `record`, and last the `outcome`: `ok`, and
+  on success `artifact` (`name`, `size`, `sha256` of a tar of the `.app` or
+  `.apk`),
+  `fingerprint`, `compilationCache` and `timings`, otherwise `code` and
+  `message`.
+- `build.cancel` takes `job` and stops it. Closing the connection with a
+  close frame cancels its jobs too. The build's process group gets SIGTERM,
+  then SIGKILL 5 seconds later. A connection that ends without a close frame
+  (1006, for example when the network drops) leaves its jobs running for 5
+  minutes; a job no connection takes back by then is cancelled, and so is one
+  whose client is revoked meanwhile. A job whose `build.start` answer was lost
+  with the connection is only reclaimed this way.
+- `build.attach` takes the `job` of this client that another connection
+  holds or held, such as one whose connection dropped or stalled, and moves it
+  to this connection: its later `build.progress` events come here, and
+  `build.cancel` and `build.artifact` take it. It answers `{ "outcome" }`,
+  the job's outcome when it already ended, else null. Progress sent while no
+  connection held the job is not replayed. A job that is gone, or belongs to
+  another client, gets `bad-request`.
+- `build.artifact` takes the `job` of a successful build and sends the archive
+  as binary frames, each 32 bytes of its sha256 and then the next bytes, then
+  answers `{ "name", "size", "sha256" }`, and deletes it here. For an iOS simulator or macOS
+  job the answer also carries `handoff`, a single-use token, and the staged
+  `.app` stays for 10 minutes so a hosted session on this Mac can take it with
+  `device-host.app.handoff`. A client keeps at most one such bundle; its next
+  fetched iOS or macOS build or a revoked approval deletes it. An archive nobody fetched is deleted when its job
+  is cancelled; one left by a server that crashed stays under
+  `repos/<repo>/out/` until you delete it.
+
+The worker root is `offload.workerRoot` in this Mac's Stim settings, or
+`$STIM_HOME/build-worker`. Each client gets `<root>/<device id>/`, with its
+blobs, caches (`CP_HOME_DIR`, `CP_CACHE_DIR`, the pnpm store and
+`GRADLE_USER_HOME` and SwiftPM) and one area
+per repository under `repos/<repo>/`: the checkout, its own Stim home with
+DerivedData, the compilation cache and ccache, and the output. A build never reads or
+writes this Mac's own Stim home. An ownership claim at
+`repos/<repo>.claims`, whose child is the build's process group, guards each
+area; it is released only once that group is gone, and a claim whose server
+and build are both gone is recovered by the next build. With a non-zero
+`concurrency.maxBuilds`, the build also holds one of this Mac's build slots
+(`$STIM_HOME/build-slots/`), the same claims local Stim builds take, with the
+same child, so a local build waits for it and `builds` counts it. Each finished build
+appends a `build` record to the [action log](#actions) with the repository as
+`workspace`. The worker root keeps growing with each repository; delete a
+client's directory to reclaim it.
 
 ## Protocol
 
@@ -124,40 +1209,152 @@ answered by `{ "id", "result" }` or `{ "id", "error": { "code", "message" } }`.
 Events are `{ "event", "subscription", ... }`.
 
 - `hello` must come first. Params: `protocol` (1), `client` (`name`,
-  `version`), and `auth`, either `{ "pairingToken", "deviceName" }` or
-  `{ "deviceToken" }`. The result carries the server name and versions, the
-  device's `capabilities` (see [Scopes](#scopes)), the `actions` it may run
+  `version`), and `auth`, one of `{ "pairingToken", "deviceName" }`,
+  `{ "deviceToken" }`, or `{ "request": "build", "deviceName" }` (see
+  [Build access](#build-access)). The result carries the server name and versions, the
+  device's `capabilities` (see [Scopes](#scopes)), the server's `features`
+  (`physical-ios` and `physical-android` when it serves `physical: true` for
+  that platform: see `frames.subscribe` below for an iPhone and
+  [Physical Android devices](#physical-android-devices), and `notifications`
+  for `notifications.list` and the `notification` event),
+  the `actions` it may run
   (none without `control`), the paired device, and the new `deviceToken` when
   the hello paired. `server.home` is the home folder
   of the user the server runs as, so clients can show paths under it as
   `~/...`.
 - `status.subscribe` returns a subscription id. Each `status` event carries a
-  full payload as `stim status --watch --json` prints it. All subscribers share
+  full payload as `stim status --watch --json` prints it, including each
+  environment's `physicalDevices`, the phones it leases, and its `agents`, the
+  Claude Code and Codex sessions working in it. Those carry the session id,
+  working directory, the short session name the tool keeps, and times, never
+  prompts or conversation. `openUrl` there is a `claude://` or `codex://` link
+  that only the Mac can open; the server has no action that opens it. `webUrl`
+  is a Claude Code session's `https://claude.ai/code/` link while Remote Control
+  is connected, which a phone opens in the Claude app or a browser.
+  `endedAgents` lists the sessions that stopped running there in the last 3
+  days, with the same fields as last found, no `pid`, and `endedAt`. The server
+  drops `CLAUDE_CODE_SESSION_ID` and `CODEX_THREAD_ID` from the environment of
+  the `stim` commands it runs, so a phone's reload is not recorded as the work
+  of the agent session that started the server. All subscribers share
   one `stim status --watch --json` child, which stops with the last
-  subscriber.
+  subscriber. While any status subscription is open, the server keeps a CPU
+  and memory history from each payload's `machine.owners`, and every `status`
+  event carries it beside the payload as `usage`, once it holds a reading:
+  `{ "intervalMs", "endAt", "environments", "devices" }`. It covers the last 10
+  minutes in 15-second slots, the cadence at which `status --watch` rereads
+  machine usage, oldest first, at most 40 points: point `i` of `n`
+  is at `endAt - (n - 1 - i) * intervalMs`, and a slot no payload fell in is
+  `null`. Each `environments` entry is `{ "workspace", "cpuPercent",
+"memoryMb" }` and sums every machine owner of that environment path; each
+  `devices` entry is `{ "kind", "id", "workspace", "slot"?, "cpuPercent",
+"memoryMb" }` for a simulator (`id` its UDID) or emulator (`id` its AVD name).
+  `cpuPercent` is ps %CPU, where 100 is one core. The history lives in the
+  server's memory only. While the server holds `stim device lock` leases for
+  phones that control a device, every `status` event also carries their
+  `grantedAt` times as `ownLeases`, so a client can tell a person controlling a
+  device from an agent driving it: an `activity.driver` of `stim device lock`
+  whose `since` is in `ownLeases` is a phone.
 - `logs.query` returns `{ "records" }`, and `logs.subscribe` sends `logs`
   events: first the last `tail` matching records, then new ones in batches.
-  Both take the Stim Desktop log viewer's filters: `workspace` (required),
-  `sources` (`metro`, `client`, `device`, `build`, `agent`), `slot`, `level` (the
+  Both take the Stim Desktop log viewer's filters: exactly one of `workspace`
+  (an environment path) or `archive` (an `archived[].id` from status),
+  `sources` (`metro`, `client`, `device`, `build`, `agent`, `maintenance`), `slot`, `level` (the
   minimum), `grep` (a regular expression), `errors`, and `tail` (1 to 5000,
   5000 by default). Without `sources`, `errors` keeps the CLI's default error
   scope. They run `stim logs --json` and `stim logs --json --follow` in the
   workspace. Subscribers with the same workspace and filters share one
-  `--follow` child, which stops with the last of them.
-- `stats.get` and `settings.get` return the payload of `stim stats --json` and
+  `--follow` child, which stops with the last of them. Archive requests read
+  retained logs and agent-device session actions locally through core, with the same JSON filters, ordering,
+  markers and error context. Archive reads are synchronous and queued per
+  connection, yielding to the event loop between requests. Pending archive
+  reads share the four-request limit with commands. Archived session actions
+  retain available platform and device attribution; device ids and Stim slot
+  assignments absent from retained files are unavailable after removal. They never follow files or use a hosted relay.
+  An archive subscription sends its records in the same batches and limits,
+  then `{ "event": "logs-ended", "subscription": "s3" }` and releases the
+  subscription, including when no records match. These reads need `read`.
+  `archive` requires an updated server: omit `workspace` so older servers
+  refuse with `bad-request` instead of reading a live replacement at that path.
+  Both or neither selector is `bad-request`; traversal ids are `bad-request`,
+  and unknown, invalid or symlinked archive directories are `unknown-workspace`
+  with a message naming the archive id.
+- `stats.get` returns the same payload as `stim stats --json`, using the shared
+  core reader in a bounded, cancellable server child. The stats part of
+  `machine.details` uses the same reader. `settings.get` runs
   `stim settings --json`, which masks sensitive values. Without `workspace`,
-  they run in the home directory and cover the machine only.
-- `frames.subscribe` takes `workspace`, `platform` (`ios` or `android`),
+  these reads use the home directory as their project context.
+- `frames.subscribe` takes `workspace`, `platform` (`ios`, `android`, `web` or `macos`),
   `slot` (`default` when absent), `fps` (1 to 30, 5 by default) and `maxEdge`
   (240 to 2048 pixels, 1280 by default), and sends `frame` events: a JPEG,
   base64 in `data`, with `width`, `height` and `capturedAt`, at most `fps` a
   second and only when the screen changed. It serves only a booted simulator
-  or a running emulator that `stim status` lists as owned by that workspace;
+  or a running emulator that `stim status` lists as owned by that workspace,
+  or with `web` the page of the workspace's running Stim-owned Chrome from
+  `stim web` (default slot only), or with `physical: true` the physical
+  iPhone (see below) or Android phone (see
+  [Physical Android devices](#physical-android-devices)) the workspace leases
+  in that slot;
   any other device ends the subscription with a `frames-failed` `error`
   event, and so does a device that stops or changes owner. A client whose
   socket has more than two frames unsent skips frames and gets the newest
   once it catches up.
 
+  A server advertising `device-frames` accepts `deviceFrame: true` for live
+  ordinary iOS simulators and Android emulators. The existing read permission
+  and registered-workspace/owned-device checks apply. `device-frame` events
+  carry `artwork` (or null): PNG `background` and `foreground` layers, outer
+  `width` and `height`, screen `aperture` (`x`, `y`, `width`, `height`),
+  `cornerRadius`, and clockwise `quarterTurns`. Pixels come from installed
+  DeviceKit or Android skins at runtime; no artwork is bundled and no local
+  file paths are exposed. Layers are sent only to opt-in subscriptions and
+  cleared on replay or device changes. The screen bytes stay unchanged.
+  JPEG `artworkTurns` and live H.264 flag bit 5 with quarter-turns in bits 3-4
+  bind housing to its capture, including same-size rotations. A client shows
+  housing only when that rotation and aperture aspect match its screen.
+  Missing, oversized or unsupported artwork falls back to the existing screen:
+  Duo, Android foldables/circular displays, web and physical devices have no
+  housing in this path. Artwork notices stay within the helper's 16 MiB message
+  limit; the combined PNG layers are limited to 10 MiB before base64 encoding.
+
+  With `macos`, it serves the front standard window of the workspace's verified
+  running native app, in the default slot, when hello advertises `macos-window`.
+  The helper verifies the recorded PID, process start time, executable, bundle
+  identifier and bundle path before starting and while capturing. ScreenCaptureKit
+  captures only that app's windows, never the desktop or another process. The
+  helper follows the app's main standard window (else its focused, else its
+  frontmost), with any attached sheet, by matching Accessibility windows to the
+  process's on-screen windows; it moves the stream when the app opens, switches,
+  closes or resizes windows. Without Device Control and Data Access permission it
+  serves only an app whose one window contains the others. A subscription fails
+  when the app has no open window at start; after the app closes its last window
+  the subscription gets `frame-delayed` until another opens. When hello
+  advertises `macos-windows`, the subscription also gets
+  `{ event: "macos-windows", subscription, current, windows, pinned }` after it
+  starts and whenever the windows or the pin change: `current` is the captured
+  window or null, `pinned` says whether `input.window` holds the view on it, and
+  `windows` lists the app's on-screen standard windows front to back, each
+  `{ id, title, frame: { x, y, width, height } }` in points with a top-left global
+  origin. A hosted app's relay forwards the event with the local subscription. It requires existing Screen & System Audio Recording permission (Screen Recording on macOS 14) and
+  never requests or resets grants. The local health payload sets `nativeViewerOpened` after a verified native view attaches, allowing the Desktop host to present its first-use Screen & System Audio Recording and Device Control and Data Access (Accessibility on macOS 26 and earlier) setup. Only explicit buttons in that host invoke normal OS requests. Capture refusal names setup and System Settings guidance; status and logs remain available. Native windows need the
+  helper, have no screenshot fallback, recording or replay, and consume
+  only the paired device's `read` capability.
+
+  A server advertising `duo-frames` also accepts `duoFrame: true` for a live local
+  owned iPhone Duo. The helper composes the installed DeviceKit V68 model with
+  both display surfaces and a current `devicectl` hinge-angle reading. It sends
+  JPEG `frame` events with `duo: { revision, screenID, angle, orientation }` bound
+  to the image. This path does not offer H.264 or replay; other live subscriptions
+  and raw recordings keep their existing capture. Missing model or angle data
+  falls back to the raw screen. The hinge reader runs only while composition is
+  requested and stops on helper stdin EOF or parent exit.
+
+  Clients acknowledge actual image display locally before accepting input and
+  keep the image stable during a drag. `input.touch` takes the matching
+  `duoRevision` instead of `display`; the helper raycasts against the original
+  posed screen, refuses unknown revisions and ignores bezel or hinge touch-down.
+  Move and up stay bound to that pose. Ending Control releases any held touch,
+  even when read subscribers keep the helper alive.
+
   Frames come from the `stim-frames` helper. When it starts, the server
   compiles it with `xcrun swiftc` from the Swift sources shipped in
   `dist/stim-frames/` (its own `main.swift` and the frame and input code it
@@ -191,8 +1388,8 @@ Events are `{ "event", "subscription", ... }`.
   the encoder, and the next access unit is a keyframe with the new SPS and
   PPS. The helper encodes with VideoToolbox in real time: Main
   profile, a keyframe at least every 2 seconds, straight from the
-  simulator's IOSurface or from the emulator's RGBA frames, only when the
-  screen changed. A subscriber starts at a keyframe, and `frames.keyframe`
+  simulator's IOSurface, from the emulator's RGBA frames, or from the page's
+  screencast JPEGs, only when the screen changed. A subscriber starts at a keyframe, and `frames.keyframe`
   with its `subscription` asks for another one, such as after its decoder
   lost state; a device sends at most one requested keyframe every 250 ms.
   A subscriber whose socket holds more than 256 KB unsent drops frames
@@ -224,8 +1421,136 @@ Events are `{ "event", "subscription", ... }`.
   second while it changes, backing off to one capture per second while it
   does not, with capturing taking at most half of each device's time, and at
   most two captures run at once. An emulator Stim booted before it passed
-  `-grpc` has no endpoint on either path.
+  `-grpc` has no endpoint on either path. A web page is captured with
+  `Page.captureScreenshot`.
+
+  A web page's frames and input go through the owned Chrome's DevTools
+  endpoint, `web.cdpEndpoint` in `stim status`. Both the helper and the
+  screenshot path connect only when `SystemInfo.getProcessInfo` names the
+  Chrome pid status reports, then attach to the page's `targetId`. The
+  helper runs `Page.startScreencast` sized to `maxEdge` and acks every
+  frame; JPEG subscribers get Chrome's JPEG as is, and video decodes it for
+  the encoder. Chrome draws a frame only when the page changes, so a
+  keyframe request re-encodes the last one.
+
+  With `physical: true` and `platform: "ios"`, frames come from the
+  physical iPhone whose unexpired lease `stim status` lists under
+  `deviceLeases` for the workspace and slot. `stim ios --device` holds that
+  lease only while it runs, so `stim device lock ios <udid>` keeps the
+  iPhone watchable between runs. A lease on the workspace's own simulator
+  is skipped. The iPhone must be cabled over USB and trust the Mac; over
+  Wi-Fi it has no screen to capture. The helper, run as
+  `stim-frames iphone <udid> <name>` with the lease's device name, sets
+  CoreMediaIO's `kCMIOHardwarePropertyAllowScreenCaptureDevices`, which
+  makes macOS list cabled iPhones as capture devices, the ones QuickTime
+  Player's New Movie Recording shows. Such a device's unique ID is a
+  random UUID that names neither the UDID nor the USB device, so the
+  helper first checks that an iOS device on USB has the UDID, without
+  dashes, as its serial number. It then opens the iOS capture device
+  named like the lease's device name, or the only one when the lease
+  records no name and one iPhone is cabled. With several iPhones cabled,
+  it waits until each shows a screen and refuses when none or several
+  carry the name. It
+  captures only while a subscriber asks for frames. macOS lets several
+  processes capture the iPhone at once. Frames and video go through the
+  same JPEG and H.264 paths as a simulator. A physical iPhone has no
+  screenshot fallback: a subscription without the helper, or whose helper
+  fails, ends with `frames-failed`, such as when the iPhone is not cabled
+  or is unplugged. While macOS is asking for Camera access, or frames
+  stop, such as while the iPhone is locked, the subscription gets
+  `frame-delayed` with `delayed: true` and a `reason`, keeps its last
+  frame, and gets `delayed: false` once frames can arrive again.
+
+  macOS treats the iPhone's screen as a camera and attributes the helper's
+  request to the app that started stim-server. Stim asks for it with its
+  own Camera usage description and entitlement, so the first capture
+  shows the Camera prompt for Stim. An app without them, such as `node`
+  started from a shell, is denied without a prompt, and the subscription
+  ends with a `frames-failed` that names the Camera pane of System
+  Settings. A physical iPhone is view only: `control.begin` with
+  `physical: true` refuses with `action-failed`. It is never recorded, so
+  `at` and `frames.seek` on it fail with `no-recording`, and it counts
+  toward no idle check.
+
+- **Replay.** `replay.range` takes exactly one of `workspace` or `archive`, plus `platform` and `slot`
+  (`default` when absent), like `frames.subscribe`, and returns what can be
+  replayed of that device slot's [recording](#recording):
+  - `enabled`: the workspace's `recording.enabled`, as the last status showed
+    it.
+  - `recording`: true while the server records the device now.
+  - `spans`: the recorded time ranges `{ start, end }`, in epoch milliseconds on
+    the Mac's clock, oldest first. Segments less than 1.5 seconds apart form
+    one span; the gaps between spans are time nothing was recorded, such as
+    after `stim stop`.
+  - `markers`: `{ at, kind, command?, label }` from the start of the first span
+    on, oldest first: the newest 400 actions and 100 errors. They come from `stim logs --json` in the
+    workspace. `action` markers are the agent's actions on that device, failed
+    ones included, from agent-device's session log and the owned Chrome page's
+    agent input, with their `command`, such as `press`, `fill`, `open` or
+    `click`. An agent-device action is placed when the command started, since
+    it logs it when it finished, after any `--settle` wait. `error` and
+    `crash` markers are error and fatal records of the workspace. Metro,
+    client and build errors name no device, so they appear on every device of
+    the workspace. `label` is the record's first line.
 
+  It needs only `read`. A device with no recording gets empty `spans` and
+  `markers`, and runs no `stim` command.
+
+  Archive replay reads only closed segments under the archive's recordings
+  directory. Its `enabled` and `recording` are false; spans and markers come
+  from those segments, archived logs and agent-device session actions. It never requires the former checkout
+  or reads a live replacement at that path, and never uses a hosted relay.
+  `frames.subscribe` with `archive` requires `at` and `video: ["h264"]`,
+  rejects physical targets, and supports `frames.seek` on that subscription.
+  `frames.live` refuses with `frames-failed`: an archive cannot go live.
+  Empty archives return empty ranges and `no-recording` for keyframes or frames.
+  These reads need the same `read` capability as workspace replay.
+
+  `replay.keyframe` takes the same `workspace` or `archive`, `platform` and `slot`, and
+  `at` (epoch milliseconds), and returns one still frame for a scrubber
+  preview without touching any subscription. The recording is stored in
+  segments of about 5 seconds that each start at a keyframe; the server picks
+  the segment `frames.seek` would show `at` from (the first one that ends at
+  or after `at`, or the newest one) and reads only its first record. The
+  result has the segment's `start` and `end`, the keyframe's capture time
+  `at`, `width`, `height`, `posture` on an iPhone Duo, and `data`, the
+  base64 Annex-B H.264 access unit with its SPS and PPS, so a client decodes
+  it on its own; the server decodes nothing. The frame is the segment's first,
+  so it can be up to about 5 seconds before `at`. It needs only `read`. It
+  fails with `no-recording` when the device has no footage or that segment's
+  first record is not a whole keyframe yet, as while it is being written. A
+  connection can have 8 of these reads in flight; more fail with
+  `limit-exceeded`.
+
+  A video subscription can replay the recording instead of the live screen.
+  `frames.seek` takes the `subscription`, `at` (epoch milliseconds) and `rate`
+  (0, 1 or 2). The server sends the access units from the keyframe at or
+  before `at` through the frame at `at`, or the newest frame when `at` is past
+  it, as binary video messages right away, then plays on at `rate` times real
+  time; 0 stays paused. The result's `at`
+  is the capture time of the frame shown. Playback skips time nothing was
+  recorded, and at the newest recorded frame it sends a `replay-ended` event
+  with `subscription` and `at` and stays paused there. `frames.live` returns
+  the subscription to the live screen, starting at a keyframe, or fails with
+  `frames-failed` when the device is not running. While a subscription
+  replays, the server sends no live frames on it, and `frames.keyframe`
+  resends the frame shown from its keyframe. A seek on a device with no
+  recording fails with `no-recording` and leaves the subscription live, and a
+  JPEG subscription cannot seek.
+
+  `frames.subscribe` with `at`, and optionally `rate`, starts the subscription
+  replaying, and needs `video: ["h264"]`. It needs no running device, so the
+  footage of a stopped workspace can be replayed; it fails with
+  `no-recording` when nothing was recorded, and sends `replay-ended` at once
+  when that footage holds no frame to show. Clients that never send these
+  messages see no change.
+
+- `recording.set` takes `enabled` and runs
+  `stim settings set recording.enabled <enabled> --scope machine --json` in
+  the home directory. It needs `control`, is logged like an
+  [action](#actions) with `action` `recording.set`, and returns `enabled` and
+  `recordingsDeleted`, the workspaces whose recordings turning recording off
+  deleted.
 - `build.plan` takes `workspace`, `platform` (`ios` or `android`) and `slot`
   (`default` when absent), and returns the payload of
   `stim <platform> --plan --json` run in the workspace: the fingerprint, the
@@ -239,6 +1564,33 @@ Events are `{ "event", "subscription", ... }`.
   computed is a `stim-failed` error. One plan runs per workspace at a time,
   across all connections; later requests wait their turn, and the 150
   seconds start when the plan starts.
+- `workspace.files` takes `{ "workspace", "group": "changed" | "untracked" }`
+  and returns `{ "files", "truncated" }`; each file has a repo-relative `path`,
+  `status`, and `staged`, `unstaged`, `untracked` flags. It needs `read` and the
+  `workspace-diff` feature. The registered app project resolves to its canonical
+  Git worktree, including changes elsewhere in that worktree. At most 200 files
+  and 256 KiB are returned; raw Git status exceeding 1 MiB refuses.
+  Changed lists include submodules only when their recorded commit differs;
+  uncommitted edits inside submodules are not listed. Each Git call has a
+  5-second deadline; a request runs several calls in sequence, with no overall
+  deadline. Closing the connection stops a running request.
+- `workspace.diff` takes `{ "workspace", "path" }` for a current changed file
+  and returns `{ "path", "patches" }`. Each patch has a `section` (`staged`,
+  `unstaged`, `untracked`), `kind` (`text`, `binary`, `too-large`, `unavailable`)
+  and `text`. Text previews total at most 256 KiB. New files must be regular
+  UTF-8 files within the worktree; symlinks, submodules and conflicts report
+  unavailable. Each Git call has a 5-second deadline; a request runs several
+  calls in sequence, with no overall deadline. Raw status output is capped
+  at 1 MiB and patches at 256 KiB. Closing the connection stops a running request.
+  Git reads disable color, external diff, text conversion, fsmonitor
+  commands and lazy fetches, use literal paths and never edit or stage files.
+  Partial clones require Git 2.45 or later so lazy-fetch protection applies
+  across subprocesses; an older or unparseable Git version refuses these reads.
+  Tracked files attributed to configured clean or process filters refuse before
+  status or diff. Unused filters are allowed within the preflight limits: each
+  request checks filter attributes for all tracked paths. The internal path
+  list has a 64 MiB cap; each Git call keeps its 5-second deadline.
+  Git LFS previews are unavailable in this version.
 - `machine.get` returns cheap machine usage, read in the server process
   without running `stim`: `volumes`, one per volume that holds a Stim
   workspace, Stim home, or the simulators, with `mount`, `holds`, `freeBytes`
@@ -255,13 +1607,55 @@ Events are `{ "event", "subscription", ... }`.
   sample), `memoryUsedBytes`, `memoryPressure` (0 normal, 1 warning, 2
   critical) and `diskFreeBytes` of the startup volume; a field is null when it
   cannot be read. `sinceMs` returns only the samples taken after it.
+- `machine.details` returns `{ "gc", "stats", "measuredAt" }`: the payloads of
+  `stim gc --json` and `stim stats --json`, both run in the home directory, so
+  a phone can show what Stim Desktop's Machine page shows about disk: every
+  simulator, AVD, iOS runtime and system image, shared caches, recordings,
+  workspace build outputs and logs, and what `stim gc --delete` would free. The
+  `gc` run is always the dry run with no other flag; the server never deletes
+  anything for this request. A part is null when its command failed, and
+  `gcError` or `statsError` says why. It needs only `read`. The server keeps
+  one result for 60 seconds, shared by every connection: a request while the
+  commands run waits for them, and `measuredAt` says when they started. The
+  commands fail after 150 seconds. Servers that predate it answer
+  `unknown-method`. It also carries `buildMachines`, the `buildMachines` list
+  of `stim doctor --json --platform ios` (never with `--fix`), so a phone can
+  show whether each build machine takes builds. The server runs doctor only
+  when `offload.machines` names a machine, else the list is empty; it runs it
+  in the registered workspace that ran doctor for iOS most recently, because
+  doctor judges a machine against an app. Like a doctor run from a terminal,
+  that records the run for the workspace. `buildMachines` is null with
+  `buildMachinesError` when doctor failed, the config could not be read, or no
+  registered workspace exists. The reply never waits for doctor, whose offer
+  to an unreachable machine can take about 13 seconds: it carries the last
+  settled `buildMachines`/`buildMachinesError` (with `buildMachinesAt`, when
+  they settled) while doctor refreshes them in the background, at most one run
+  at a time, and sets `buildMachinesPending` while that background run has not
+  settled a result yet, or the settled one is 60 seconds old or older. A client
+  that wants the refreshed result asks `machine.details` again. It also
+  carries `buildClients`, the builds this Mac ran as a build machine, one entry
+  per client Mac read from the `build` records of the audit log, with `id`,
+  `name`, `builds`, `failed`, `buildMs`, `lastAt` and the same three counts
+  for `today`, most recent client first, with `today` on this Mac's local
+  calendar day. Servers that predate it leave it out.
 - `unsubscribe` ends a subscription.
 - `push.register` takes `token`, an Expo push token, `events`, one or more
-  [push notifications](#push-notifications) the phone wants (`build-failed`,
-  `log-errors`, `disk`, `app-stopped`, `slow-build`), an optional
-  `agentOnly`, and `ref`, an opaque string of up to 128 characters that every
-  push carries back as `data.ref`. It needs only `read`. Registering again
-  replaces the device's registration; `push.unregister` removes it.
+  [push notifications](#push-notifications) the phone wants (`started`,
+  `stuck`, `looping`, `finished`, `machine`, `control`, `attention`), `ref`, an opaque
+  string of up to 128 characters that every push carries back as `data.ref`,
+  and optionally `stuckMinutes` (1 to 240, default 15), `quietHours`
+  (`{ "start", "end", "timeZone" }`, minutes after midnight in an IANA time
+  zone) and `levels`, each event's [delivery level](#delivery-levels) (for
+  example `{ "stuck": "silent", "machine": "alert" }`). It needs only `read`. Registering again replaces the device's
+  registration; `push.unregister` removes it. Phones from before these events
+  may still send `build-failed`, `log-errors`, `disk`, `app-stopped`,
+  `slow-build` and `agentOnly`: `disk` counts as `machine`, and the rest are
+  accepted and ignored.
+- `notifications.list` returns the [notification history](#notification-history)
+  as `{ "log", "cursor", "notifications" }`, newest first. `since` (a `cursor`
+  from an earlier list) returns only the entries after it. From then on, the
+  connection gets a `notification` event, `{ "event": "notification", "log",
+"notification" }`, for each entry the server logs. It needs only `read`.
 - `action` runs an [action](#actions) and returns
   `{ "action", "workspace", "output" }`.
 - An `error` event ends a subscription whose source failed, or whose client
@@ -270,61 +1664,211 @@ Events are `{ "event", "subscription", ... }`.
 `workspace` is an environment `path` from a status payload. Any other path is
 refused with `unknown-workspace` and runs nothing. A connection holds at most
 32 subscriptions and runs at most 4 `logs.query`, `stats.get`,
-`settings.get` and `build.plan` requests at a time. Those requests fail after
-60 seconds, `build.plan` after 150, or at 32 MiB of output, and closing the
-connection stops them. When the command refuses with Stim's error contract on
-stdout, the `stim-failed` message is its code, message and remedy; otherwise
-it is the exit status and the end of stderr. A `stim` child that
+`settings.get`, `build.plan`, `workspace.files` and `workspace.diff` requests at
+a time. `logs.query`, `stats.get` and `settings.get` fail after 60 seconds,
+`build.plan` after 150; these four fail at 32 MiB of output. Closing the
+connection stops running requests. When the command refuses with Stim's error
+contract on stdout, the `stim-failed` message is its code, message and remedy;
+otherwise it is the exit status and the end of stderr. A `stim` child that
 ignores SIGTERM gets SIGKILL a second later. A log subscriber whose socket has more than
 4 MiB unsent gets no more batches until it catches up; past 20,000
 waiting records the server ends that subscription with `slow-client`.
 
+## Recording
+
+The server records owned simulators, emulators and the Stim-owned Chrome page
+so clients can replay what happened while nobody watched. It records a device
+while `stim status` shows an automation tool driving it (`activity.state` is
+`driven`), or while a client has a `frames.subscribe` subscription to it. It
+records nothing else, holds no device awake and changes no device setting. To
+see drivers, the server keeps one `stim status --watch --json` child running
+for as long as it runs, shared with status subscribers.
+
+Recording goes through the device's `stim-frames` helper, shared with live
+subscribers. The helper runs a second H.264 encoder for it, at 720 pixels on
+the long edge, 1 Mbps and at most 10 frames a second, so live video keeps its
+own bitrate. Live frames are captured at no less than 720 pixels and 10 frames
+a second while the device is recorded. A device on screenshots, without the
+helper, is not recorded, and a helper that fails is started again after 5
+seconds, doubling up to 5 minutes. One stim-server records and prunes a Stim
+home at a time, under an exclusive ownership claim at
+`$STIM_HOME/server/recorder`; a second one serves replays and records once the
+claim frees.
+
+Footage is stored under `$STIM_HOME/workspaces/<id>/recordings/<platform>-<slot>/`
+as segments of about 5 seconds, each starting at a keyframe; the server asks
+the helper for a keyframe once a segment is 5 seconds old, so a screen that
+does not change still gets new segments, and a keyframe request also restarts
+the recording stream at a keyframe. The segment being
+written is `<start>.part`, and a closed segment is `<start>-<end>.seg`, in epoch
+milliseconds. A segment is a sequence of records: a u32 big-endian length of
+the rest, u8 flags (bit 0 keyframe, bit 1 folded, bit 2 unfolded, as in a video
+packet), f64 capture time in milliseconds since the epoch, u16 width, u16
+height, then one Annex-B access unit. The server creates a segment only while
+the workspace directory has its `workspace.json`, so it never fills a directory
+that `stim worktree remove` or `stim gc` emptied.
+
+Every 30 seconds it keeps the last 15 minutes of footage of each device,
+counting only recorded time, and at most 1 GiB of footage across every
+workspace, deleting the oldest segments first. It closes, at their last write,
+the `.part` segments of a server that stopped. When a status payload shows
+`recording.enabled` false for a workspace (the `recording.enabled` setting, or
+`STIM_RECORDING` in the server's environment), it stops recording that
+workspace within seconds and deletes its recordings. `stim stop` ends recording
+and keeps the footage; `stim worktree remove` and `stim gc` delete it. A gc that
+deletes the segment being written loses the rest of that segment; the next one
+is written as usual. Recordings stay on the Mac and are served only to paired
+clients.
+
 ## Push notifications
 
-A paired phone that sends `push.register` gets attention notifications while
-its app is in the background or closed. The server keeps the registration
-with the pairing in `devices.json`, so revoking the device drops it. A token
-belongs to one pairing: registering it from a new pairing of the same phone
-removes it from the old one.
-
-While at least one device is registered, the server keeps its own
-`stim status --watch --json` child running, even with no client connected,
-and reads the free space of Stim's volumes every minute. It pushes, per
-device and only for the events the device chose:
-
-- `build-failed`: a workspace's last iOS or Android build failed, in an
-  active workspace or within the last day;
-- `log-errors`: new errors in an active workspace's logs, once the count has
-  held for 10 seconds (at most a minute after the first), then at most every
-  5 minutes;
-- `disk`: a volume holding Stim state has less than 5 GB free;
-- `app-stopped`: the app is not running on a booted device of a live
-  workspace;
-- `slow-build`: a build has run more than twice its usual duration.
-
-These are the rules of the phone app's home attention strip
-(`apps/mobile/src/lib/attention.ts`), copied into `src/attention.ts`. Each problem pushes once; a later failed build or a
-problem that clears for two minutes and returns pushes again. What is already
-wrong when the server starts or a device registers does not push. With
-`agentOnly`, workspace events push only while a device of the workspace is
-driven by an agent, so a workspace whose devices are gone, such as after a
-failed first build, does not push.
-
-A device gets at most 20 pushes an hour. More than three at once become one
-summary push that opens the phone's home screen.
+A paired phone that sends `push.register` gets notifications while its app is
+in the background or closed. The server keeps the registration with the
+pairing in `devices.json`, so revoking the device drops it. A token belongs to
+one pairing: registering it from a new pairing of the same phone removes it
+from the old one.
+
+A notification means that your attention changes the outcome, or that work you
+wait on started or finished. A failed build, new log errors, a stopped app or a
+slow build on their own are normal agent iteration and do not push; the phone
+shows them in its attention strip. The server pushes, per device and only for
+the events the device chose:
+
+- `started`: a workspace began warming (`phase` `warming`), or an agent first
+  drove one of its devices. It is grouped per Mac, and opens the workspace, or the device viewer
+  once an agent drives it. An agent driving the workspace updates the warming
+  notification in place.
+- `stuck`: an agent drove the workspace, its devices are still up, and nothing
+  happened for `stuckMinutes`: no agent action, build, Stim run, Metro bundle
+  request or new log error. App log records do not count, because an idle app keeps
+  logging: an idle Stim app writes about 200 UIKit info records a minute. The
+  owned Chrome page counts as a device: an attached tool's input there is an
+  agent action, and while an agent drives it its page log also counts, since an
+  agent's navigations and scripts are not agent actions. It opens the device viewer.
+- `looping`: the newest three or more iOS or Android builds failed the same
+  way, at the same first compiler diagnostic `file:line`, or with the same
+  error code when there is none, such as three failed launches
+  (`STIM_LAUNCH_FAILED`, which includes an app that exits at launch). It says,
+  for example, `Same Swift error 3x at AppDelegate.swift:71` and opens the
+  build details.
+- `finished`: the agent stopped driving after a green build and nothing
+  happened for 5 minutes, or stopped the workspace after a green build; the
+  workspace's pull
+  request became ready for review, or merged, which opens the pull request; or,
+  when GitHub cannot be asked, git finds the branch merged into the default
+  branch.
+- `machine`: a volume holding Stim state has less than 5 GB free (the episode
+  ends once 6 GB are free again), or memory pressure stayed critical for a
+  minute. It opens the machine sheet.
+- `control`: another client took over a device this phone controls, or an
+  agent started driving it. It opens the device viewer.
+- `attention`: something only a person can fix, from the needs-attention rule
+  (`needsAttention` in `@stim-cli/core/oversight`): a port held by another app, a
+  supervisor or owned Chrome Stim cannot verify, an owned AVD it could not
+  check, a failed run with a signing or provisioning error code, a physical
+  device lease that expired, or an EAS session running for 30 minutes with no
+  agent driving the workspace. It opens the workspace, or the build for a
+  signing failure. A stuck agent, a loop and a full disk notify through their
+  own categories.
+
+Stuck and finished are read from device activity, so two cases blur them. An
+agent that finishes without closing its agent-device session still holds the
+device, so it gets `stuck`, whose text then names the green build it stopped
+after. With a `stim` whose status has no `activity.recent`, every app log
+record counts as activity, so an app that keeps logging never looks stuck or
+finished.
+
+Each workspace notifies once per episode: a stuck agent notifies again only
+after new activity and a new quiet stretch, a loop only after a success or a
+different failure. A push carries a collapse id for its workspace and
+category, so a later one replaces the earlier notification on the phone
+instead of stacking. What is already true when the server starts or a device
+registers does not push. During the phone's quiet hours nothing pushes: a
+problem that still holds when they end pushes then, and what started or
+finished during them does not.
+
+While at least one device is paired, the server keeps its own
+`stim status --watch --json` child running, even with no client connected, and
+reads the free space of Stim's volumes and the memory pressure every minute.
+While a device wants `finished`, it looks up the pull requests of worktree
+branches that have an upstream every 5 minutes, with one `gh api graphql` call
+per repository, the lookup `stim gc` uses. Without `gh`, or when it is signed
+out or does not answer, that round relies on git, and the next round asks
+again.
+
+A device gets at most 20 alerting pushes an hour; silent pushes do not
+count. More than three at once become one summary push that opens the
+phone's home screen.
 
 Pushes go to the Expo push service, `https://exp.host/--/api/v2/push/send`,
-which forwards them to Apple. No APNs key or other secret lives on the Mac.
-A workspace push carries the workspace title, a short reason such as `iOS
-build failed (STIM_BUILD_FAILED)` and the Mac's name as the subtitle; a disk
-or summary push has the Mac's name as its title. In `data` it carries the
-`ref`, the screen to open (`home`, `machine`, `workspace` or `logs`) and, for
-a workspace, its absolute path, which the phone needs to open that workspace
-before it has reconnected. It carries no logs and no other paths. The
-server checks the push receipts 15 minutes later and drops a token that Expo
-reports as `DeviceNotRegistered`, and prints any other refusal, such as
-missing APNs credentials, on stderr. Pushes are not retried, and nothing is
-pushed while the server is not running.
+which forwards them to Apple. No APNs key or other secret lives on the Mac. A
+workspace push carries the workspace title, a one-line cause and the Mac's name
+as the subtitle; a machine or summary push has the Mac's name as its title. In
+`data` it carries the `ref`, the screen to open (`home`, `machine`,
+`workspace`, `device`, `build` or `url`), and the workspace's absolute path,
+with the platform and slot for a device, the platform for build details and
+the pull request's URL for `url`. The phone needs the path to open a workspace
+before it has reconnected. It carries no logs. The server checks the push
+receipts 15 minutes later and drops a token that Expo reports as
+`DeviceNotRegistered`, and prints any other refusal, such as missing APNs
+credentials, on stderr. Pushes are not retried, and nothing is pushed while
+the server is not running.
+
+### Delivery levels
+
+Each event the device registers is delivered at one of two levels; an event it
+leaves out of `events` is off and never pushes.
+
+- `alert`: a banner and sound. The push has `sound: "default"`,
+  `interruptionLevel: "active"` and `channelId: "attention"`, the phone's
+  high-importance Android channel.
+- `silent`: no banner or sound, only the notification list.
+  The push has no sound, `interruptionLevel: "passive"` and
+  `channelId: "updates"`, the phone's low-importance Android channel.
+
+`levels` in `push.register` sets each event's level. An event it leaves out,
+and every event of a phone that sends no `levels`, is silent. A summary push is
+silent only when every notification it sums up is. An older server ignores
+`levels` and alerts for every event but `started`.
+
+The server and phone import the same pure rules from `@stim-cli/core/oversight`.
+The phone formats home attention messages locally from the facts the shared rule selects.
+`__tests__/oversight-agreement.test.ts` checks their categories, workspace names
+and needs-attention vectors. Notification delivery remains local to each.
+
+## Notification history
+
+The server logs the notifications the rules produce for the Mac, whether or not
+a phone was pushed, so a phone can list what it missed. While any device is
+paired, it runs the rules once more for the Mac itself, with every category, no
+quiet hours and the lowest `stuckMinutes` a registered device asked for (15
+without one). Each notification it produces is an entry; a `control` conflict is
+an entry too, listed only to the phone that lost the device. Pull request
+entries need the GitHub lookup, which runs only while a device wants
+`finished`.
+
+An entry is `{ "seq", "at", "id", "category", "title", "body", "quiet",
+"target", "suppressed"? }`. `seq` grows by one per entry. `id` names the
+workspace or machine and category, the key a push's collapse id is made from,
+so a later episode of the same problem shares it. `target` is the screen the
+push opens, as `{ "kind", ... }` with the fields of the push's `data`.
+`quiet` is the event's default delivery, always silent; a device's
+[levels](#delivery-levels) decide how its push was actually delivered.
+`suppressed` says why no registered device got the notification when it was
+logged: `muted` when none wants its category, `quiet-hours` when those that do
+were in quiet hours. A problem that still holds when quiet hours end is pushed
+then, so a `quiet-hours` entry may still have reached the phone. Without
+`suppressed`, a registered device was due to get it, or none is registered; a
+device's hourly budget or a summary push can still stand in for the push
+itself. A push for a logged notification carries the entry's `seq` as `data.notification`, so the
+phone can mark it read.
+
+The log keeps the last 200 entries, none older than 7 days, in
+`$STIM_HOME/server/notifications.json`, which only the server writes, under
+`notifications.json.lock`. `log` in `notifications.list` is a random id made
+with the file: a new one means the history started over, so a cursor or read
+state kept for the old one no longer applies. What is already true when the
+server starts is not logged, as it is not pushed.
 
 ## Actions
 
@@ -365,10 +1909,12 @@ replaced by `?`.
 ## Control
 
 A device with `control` can drive a simulator or emulator that `stim status`
-lists as owned by a workspace. Nothing it sends reaches any other device.
+lists as owned by a workspace, or a physical Android phone the workspace
+leases (see [Physical Android devices](#physical-android-devices)). Nothing it
+sends reaches any other device.
 
 - `control.begin` takes `workspace`, `platform`, `slot` (`default` when
-  absent) and `takeOver`, and returns `{ "session", "platform", "lease",
+  absent), `physical` and `takeOver`, and returns `{ "session", "platform", "lease",
 "postures" }`. `postures` lists what `input.posture` takes for the device:
   `folded` and `unfolded` for an iPhone Duo, `folded`, `half-open` and
   `unfolded` for an emulator with a hinge, such as a `pixel_fold` AVD, and
@@ -390,15 +1936,88 @@ lists as owned by a workspace. Nothing it sends reaches any other device.
   it.
 - `input.touch` takes `session`, `phase` (`down`, `move`, `up`), `x` and `y`
   as fractions of the upright screen, and `display` (0, the main display).
+  Without `display`, a touch on an iPhone Duo goes to the panel its latest
+  frame showed, and before any frame to the cover.
   `input.text` takes up to 256 printable ASCII characters, where `\n` presses
   Return, `\t` Tab and `\b` Delete. `input.button` takes `home` or `lock`,
   and on Android also `back` or `app-switch`. `input.rotate` takes
-  `direction` (`left` or `right`) and turns the device a quarter turn.
-  `input.posture` takes one of the session's `postures`. Each answers `{}` once the input
+  `direction` (`left` or `right`) and turns the device a quarter turn. An
+  iPhone Duo rotates through its Virtualization provider in folded, half-open
+  and unfolded postures. Apps keep their supported orientations, and its home
+  screen stays portrait, as on other iPhones.
+  `input.posture` takes one of the session's `postures`. A web page takes
+  only `back`, its history back, and refuses rotation and posture. Each answers `{}` once the input
   is handed to the device: when it goes through the helper, that is when the
-  helper receives it, so a failure there shows only in the server's log. A connection may send 120 inputs a second and type 40
+  helper receives it, so native macOS input failures end Control with the reason while its view stays available; other helper failures are logged. A connection may send 120 inputs a second and type 40
   characters a second, with a burst of 256, and rotate or change posture twice a
   second; more fail with `limit-exceeded`.
+- When hello advertises `macos-window-control`, `control.begin` accepts
+  `platform: "macos"` for the verified native app in the default slot. It needs
+  `control` and takes one exclusive server session per app, with the same
+  takeover, disconnect, revocation and five-minute idle rules; `lease` is null
+  because CLI device locks do not cover macOS apps. Existing Device Control and
+  Data Access permission (Accessibility on macOS 26 and earlier) is required, without permission requests or resets. Before each
+  action the helper verifies PID/start time/executable/bundle and that the
+  captured window ID and size are still the app's front standard window, or the
+  window `input.window` pinned. The app's
+  other windows are allowed. A modal dialog window and changed ownership refuse
+  input. Input that arrives while capture moves to another window is dropped with a
+  logged reason and Control continues. A sheet attached to the captured window
+  takes focus and pointer input. A sheet larger than the captured window is not
+  supported. Events are
+  posted only to that PID; the desktop and other apps receive no input.
+  `input.touch` maps normalized captured-window coordinates to mouse events.
+  `input.scroll` takes normalized `x`, `y` and `deltaX`, `deltaY` in pixels,
+  each from -1000 to 1000. When hello advertises `macos-window-select`,
+  `input.window` takes `window`, an id from the `macos-windows` event, to pin the
+  view and input to that window of the app: the helper verifies it is one of the
+  app's on-screen standard windows, makes it the app's main window and raises it
+  among the app's windows without activating the app, and capture stays on it
+  while another window comes to the front.
+  `window: null` follows the front window again. A pin also ends when its window
+  closes or leaves the screen, or when the Control session that set it ends,
+  including takeover, disconnect and the idle timeout. A window that is gone by
+  then, or a modal dialog in the app, drops the input with a logged reason
+  without ending Control. The hosted relay forwards it as `device-host.input.window`.
+  `input.key` accepts Escape, Tab, Return, Backspace,
+  arrows or `a-z` and `0-9`, with unique optional `command/shift/option/control`
+  modifiers. Hello advertises `macos-keyboard-extended` for the expanded keys;
+  older servers accept only `a/c/v/x/z/s/f` plus navigation. Shortcuts for `a-z` and `0-9`
+  use the key that types the character in the Mac's current keyboard layout,
+  using the Command layer when Command is held. Dvorak and Dvorak-QWERTY Command
+  are supported. On Russian and similar layouts (Cyrillic, Greek, Hebrew, Arabic),
+  Latin-letter shortcuts work with Command; Control-only or Option-only letter
+  shortcuts are refused. With Control, the layout's Control table must also yield
+  the requested character or, for letters, its C0 control character; otherwise
+  the shortcut is refused. The Mac's selected input source is read on each key,
+  so switching layouts takes effect on the next key.
+  Letters and digits available only with Shift or Option, or through a dead key
+  (for example digits on AZERTY), are refused with a reason naming the layout,
+  and Control ends. Stim posts the requested modifiers unchanged; it does not
+  add modifiers to reach those characters. Ordinary typing and navigation do
+  not depend on the layout. Symbols such as comma remain unsupported key names.
+  The helper posts input to the owned process without activating it or raising its window,
+  except that `input.window` raises the window it pins among the app's windows.
+  Only when the captured window is not the app's key window does it activate the app (waiting up to one
+  second for focus) and send a `controlActivated` notice, which stim-server logs. Clicks on views that
+  reject the first mouse, such as custom views and SwiftUI `onTapGesture` regions, do not land while the app
+  is in the background. `input.text` retains the printable ASCII contract,
+  and navigation keys do not depend on that host layout. Native windows
+  reject simulator buttons, rotation and posture. The helper dynamically resolves
+  private CoreGraphics `CGEventSetWindowLocation` to annotate PID-targeted pointer
+  events. This is a macOS compatibility limit outside the phone and Mac App Store
+  binaries: a missing symbol refuses Control while read-only capture remains
+  available. An input refusal sends
+  `control-ended` with its reason without ending read-only capture.
+- On an owned iOS simulator, `control.begin` also reports optional `simulator`
+  capabilities: `canShake` and `slowAnimations` (a boolean, or `null` when
+  unavailable). `input.simulator` takes the session and `action: "shake"`,
+  `action: "read"`, or `action: "slow-animations"` with an explicit boolean
+  `enabled`. It returns the confirmed capabilities and state. Unavailable
+  controls are refused. The native operation times out after 8 seconds and
+  stops when its control session ends; only one option changes per simulator
+  at a time. These controls use the same CoreSimulator guest notifications as
+  Stim Desktop, without opening Device Hub.
 - `control.end` ends a session. The server also ends it with a
   `control-ended` event `{ "session", "reason", "message" }` after 5 minutes
   without input (`idle`), when another client takes the device over
@@ -417,6 +2036,13 @@ streams its frames:
   Hub does, and from then until the simulator reboots it ignores tools that
   still use SimulatorKit's legacy HID client. Text is typed key by key on a US
   layout. `lock` is the side button.
+- A web page takes DevTools input on the page's `targetId`: touches as
+  `Input.dispatchTouchEvent` (a drag scrolls, on a desktop page too), text as
+  key events, `\n`, `\t` and `\b` as Enter, Tab and Backspace. A web
+  session holds no lease, since `stim device lock` covers devices; a
+  DevTools client other than Stim's attached to the browser (`web.activity`
+  in status, such as Playwright MCP) makes `control.begin` answer
+  `device-busy` unless it takes over.
 - Emulators take touches through the emulator's gRPC `sendTouch`. Text and
   buttons go through gRPC `sendKey` when the emulator reports a hardware
   keyboard, which AVDs Stim creates have. An emulator without one drops key
@@ -437,7 +2063,62 @@ appends a line to the action log, with `action` set to `control.begin`,
 ended or whom it took the device from. Inputs are not logged.
 
 The error codes `unauthorized`, `pairing-expired`, and `protocol-unsupported`
-refuse the client until it pairs again or updates; clients retry the others.
+refuse the client until it pairs again or updates; `approval-pending` refuses
+a build client until the Mac approves it; clients retry the others.
 
 The package exports the message types, and the build writes their JSON Schema
 to `dist/protocol.schema.json`, exported as `@stim-cli/server/protocol.schema.json`.
+The wire types are shared through `@stim-cli/core/protocol`. The phone derives
+its receiving types from that contract and checks JSON results against the
+pending method, and known events before dispatch. Its validators are compiled
+during development, not on app startup. Compatible additional fields and
+unknown future events remain supported; malformed known data closes the socket
+and enters the normal reconnect flow without logging the payload.
+
+## Physical Android devices
+
+A phone reached with `stim android --device <serial>` (or held with
+`stim device lock android <serial>`) is used, not owned. With `physical: true`,
+`frames.subscribe` and `control.begin` pick the phone the workspace holds an
+unexpired lease on in `slot`, as `deviceLeases` in `stim status` reports it,
+instead of the Stim-owned emulator. A workspace without that lease gets
+`frames-failed` or `action-failed`, and so does a slot whose leased device is
+an emulator. Watching needs `read`, as for an emulator. Control needs
+`control` and that lease: the session never takes, renews or releases a
+phone's lease, and `takeOver` cannot move one between workspaces. When the
+lease is released or expires, the control session ends with `device-gone` and
+frame subscriptions end with `frames-failed`. Both follow `stim status
+--watch`: a release reaches the server when status next reports it, usually
+within seconds and at most about 30 seconds plus one refresh. Input after an
+expiry is refused at once. A physical Android device is not recorded, so `at`
+and `frames.seek` answer `no-recording`, and a watched phone is not listed as
+viewed for Stim's idle checks.
+
+The `stim-frames` helper reaches the phone over adb only, with the scrcpy
+server 4.1 (Apache-2.0), shipped in `dist/scrcpy/` with its `LICENSE` and a
+`NOTICE`. Before every push, the helper checks the jar's sha256 against the one
+pinned in its source. It then pushes the jar to
+`/data/local/tmp/stim-scrcpy-<id>.jar`, starts it with `app_process` as the
+shell user, and connects through an `adb forward` port. The server's cleanup
+process deletes the jar as soon as it runs; when the helper stops, it removes
+the forward and deletes the jar again. It installs nothing, and it asks
+scrcpy for no settings change: no `show_touches`, no `stay_awake` and no
+screen power change (`power_on=false`), with clipboard sync off. The phone
+encodes H.264 of its screen as it is oriented, scaled to fit 2048 pixels;
+the helper decodes it with VideoToolbox and feeds the same encoder, JPEG path,
+keyframe requests and bitrate adaptation as a simulator or emulator. The
+stream has no time limit and restarts only with the helper.
+
+Input goes over scrcpy's control socket: touches as finger events in the
+current frame's pixels, text as injected text, and `\n`, `\t`, `\b`,
+`home`, `back`, `app-switch` and `lock` as key events. `input.rotate` and
+`input.posture` fail with `bad-request`, because a phone turns only in hand.
+
+Some Android 15 and 16 devices send no frame until their screen changes
+(scrcpy #6500, #6546), so a tile can stay blank until then. With its screen
+off, a phone streams what its display shows, such as a Samsung always-on
+display, or black; the stream never wakes it.
+
+For testing without a phone, `STIM_SERVER_TEST_ADB_EMULATORS=1` in the
+server's environment lets a `physical: true` target resolve to an emulator the
+workspace leases, which then streams and takes input over adb the same way.