@stim-cli/server 1.15.0 → 1.17.0

package/README.md

@@ -16,12 +16,14 @@ 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, approved clients and access requests
+stim-server devices [list]        # list pairings, approvals, requests and hosted sessions
 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
 ```
@@ -59,11 +61,133 @@ 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
@@ -185,7 +309,8 @@ 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 and
+`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
@@ -206,16 +331,15 @@ tokens.
 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, client view/control relays and
-Android Metro and viewing remain in [#2266](https://github.com/appandflow/stim/issues/2266).
+bundle, Android APK or prebuilt macOS app, stream the iOS simulator, Android emulator or macOS app and control it. Hosted
+iOS and Android apps connect back to Metro on the client Mac. Automatic placement remains 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.
+approval request. Use `stim ios --remote <machine>` or `stim android --remote <machine>` for explicit placement.
 
 A client on the tailnet sends `hello` with
 `auth: { "request": "device-host", "deviceName": "Laptop" }`. As with a build
@@ -226,7 +350,8 @@ 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`, or use **Allow**
+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
@@ -239,6 +364,31 @@ from phone pairings and build clients. A hosting token grants no `read`,
 read, control and build tokens cannot gain hosting through `devices grant`.
 Loopback requests and `pair --device-host` are refused.
 
+### Hosted here
+
+`stim-server devices` adds a **Hosted here** block after pairings and approvals,
+with the client name, platform, device label, installed app bundle id (or `-`),
+state and start time. `--json` adds `hostedSessions` next to `devices`, including
+an empty array when there are none. Rows are newest first; plain stopped
+sessions are omitted, while parked and unresolved sessions stay visible.
+A parked row uses its parking time. A removed client's name falls back to its id.
+The command reads the host journal directly and needs no server connection.
+
+`device-host.sessions` takes no params (or `{}`) and returns `{ sessions }`.
+Each row has `id`, `client: { id, name }`, `platform`, nullable `device` and `app`,
+`state`, `parked`, `since` (ISO time), and `workspace`.
+`device-host.sessions.stop` takes `{ "session": "<id>" }` and returns
+`{ "id": "<id>", "state": "stopping" | "stopped" }`. It stops any client's
+session through the existing stop path, closing Metro, view, agent and logs
+before owned-device teardown. Repeating a stopped session returns `stopped`;
+an absent id gets `unknown-session`.
+Both requests require an authenticated loopback Desktop connection with local
+identity and control access. Local read-only connections, paired phones and
+remote hosting clients get `forbidden`. A session whose active owner is not
+attached to this server reads as `unknown`; stop reconciles it through the same
+ownership checks. The approved-client `device-host.stop` remains limited to
+that client's own sessions.
+
 ### Hosted availability offers
 
 Before reserving, an approved hosting client can send:
@@ -347,14 +497,15 @@ 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>"}` shuts down only its recorded,
+`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 device records remain for
-ownership and reconciliation; stop does not delete the simulator.
+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 shutdown outcome retains the slot
+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.
@@ -403,8 +554,9 @@ A ready Android `device` has `avdName`, `serial`, `consolePort`, `systemImage`,
 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 shut down and retain its AVD data and record; unknown native outcomes
-retain the reservation and require explicit reconciliation. Android Metro
+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.
 
@@ -440,9 +592,11 @@ 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.
+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.
 
-A macOS session can take its content from a build this Mac ran instead: after
+An iOS simulator, Android emulator 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
@@ -452,7 +606,11 @@ 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`.
+is still missing; an older server answers `unknown-method`. For iOS, check the
+`hosted-ios-data` hello feature before requesting handoff; for Android check
+`hosted-android-data`. Without the feature, upload. Android takes only a regular
+APK file matching the single `App.apk` manifest entry. Handoff failure falls back
+to upload. Reused APK blobs skip transfer, while every new attempt still installs.
 
 After every digest is verified, call `device-host.app.launch` with
 `{session, attempt}`. Poll `device-host.app.attach` for `installed` or `unknown`.
@@ -488,11 +646,31 @@ 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
+Development launch remains `unverified` until the client Metro bridge provides
+bundle evidence. 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).
+retain the same reconciliation rules as iOS.
+
+With `hosting.agentDriver: agent-device`, each installed Android session gets
+its own daemon and child-aware claim under `device-host/sessions/<session>/agent-device.claims`.
+Both Macs need agent-device 0.21.22 or later. The host verifies the serial policy
+digest and `android-instance` backend and advertises `hosted-android-agent`.
+`device-host.app.attach` and session attach carry a session grant with
+`android:mobile:<serial>` and the same token and client-node checks as iOS.
+The client writes a 0600 remote config under `hosted-android/<slot>/` and reports
+it as `android.host.agent`. Use `agent-device <command> --remote-config <file>`.
+Missing or unsupported agent-device reports `driver: none` with its reason.
+
+The policy pins the ledger-owned serial and filters `devices` to that emulator.
+Inspection and interaction commands match iOS. Installs, reinstall, uninstall,
+boot/shutdown, `close --shutdown`, record, logs, uploads, other serials (including
+nested batches and leases), and host paths are refused. Ambient fields are
+stripped and replaced with host-owned platform, serial and lease scope.
+Stim installs apps. Android snapshots use one-shot helpers without adb forwards;
+after daemon exit the host stops and verifies only the two fixed agent-device
+helper packages on that serial. Their APKs leave with emulator deletion.
+Reinstall, stop, revocation and close await agent teardown before native work;
+unresolved agent claims refuse replacement and deletion after restart too.
 
 ### Hosted macOS app sessions
 
@@ -541,29 +719,65 @@ 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
+Once a hosted 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
+before installation and after stop. 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}`:
+`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). `cursor` maps each log file name to the
+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. Android sessions use
+`logcat -d -v epoch -T <epoch> --pid <pid>` on the exact ledger-owned serial after
+re-verifying its AVD name. Each collection resolves `pidof <package>` and also
+queries the last observed PID of that app attempt, to drain a crash or restart.
+Without any observed PID, logs cannot be attributed to the app. PID-based logcat
+cannot distinguish historical reuse of an exited PID. Output is bounded
+by the executor's 64 MiB limit per command and the collection's ten-second budget;
+an oversized query retries the recent tail and emits a `device` warning naming
+the dropped interval. Logcat entries already evicted from its finite buffer are
+unavailable. Both native collectors use the same checkpoint and NDJSON writer.
+Windows adapt to the backlog,
+overlap by five seconds and de-duplicate event identities. `checkpoint` is the last
+completed native 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 macOS sessions, and also after the session stopped,
-because stop keeps logs. Servers that predate it answer `forbidden` or
+session's own client only, for iOS, Android and macOS sessions, and also after the session stopped,
+because stop keeps captured logs. iOS clients check hello feature `hosted-ios-data`
+and Android clients check `hosted-android-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. CLI placement and client view/control relays remain follow-ups in [#2403](https://github.com/appandflow/stim/issues/2403).
+app is running. Automatic CLI placement remains a follow-up in [#2403](https://github.com/appandflow/stim/issues/2403).
 
 ### Private hosted Metro
 
@@ -575,10 +789,18 @@ 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
+Call `device-host.metro.open` with `{session, gatewayPort, secret, clientMetroPort?}` 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,
+endpoint. `clientMetroPort` is required for Android and validated as an integer
+from 1 through 65535. The session records it alongside the bridge port. Android
+development installation reverses `tcp:<clientMetroPort>` to `tcp:<port>` on
+the exact ledger-owned serial and sets `debug_http_host` to
+`localhost:<clientMetroPort>`. Reopening an installed development session runs
+a fixed reverse worker under its child-aware claim, serialized with install
+and stop, so a client reload restores the mapping after a host adb server
+restart. The worker never restarts the shared adb server. iOS development
+installation uses the bridge 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
@@ -589,7 +811,7 @@ 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 shutdown. After a server owner
+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
@@ -600,16 +822,27 @@ 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,
-client iOS view/control relays and Android Metro/viewing remain in [#2266](https://github.com/appandflow/stim/issues/2266).
+Approved clients use `stim ios|android --remote auto` for automatic device placement.
+They stay local while there is a free slot, no queued device run, normal memory
+pressure, no budget refusal and load below `offload.maxLoadPerCore`. Otherwise
+they rank compatible offers from `hosting.machines` and select a host, or wait
+locally if none admits. A reserve refusal after an offer fails with
+`STIM_HOSTING_REFUSED` and asks to retry; it does not re-place the built app.
+Automatic native macOS placement remains separate work.
 
-### Hosted macOS relay
+### Hosted viewer relay
 
-The client's stim-server relays a hosted workspace's macOS view and input to
+The client's stim-server relays a hosted workspace's iOS simulator, Android emulator 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` feature advertises this relay. All of the client's
-relayed subscriptions and control sessions for one host share one connection,
+server. The `macos-hosted`, `ios-hosted` and `android-hosted` features advertise these relays.
+iOS resolves `ios.host` and Android resolves `android.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/Android 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
@@ -621,15 +854,14 @@ 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 frames and control reject `physical`, a non-default slot, and replay
-(`at`/`rate`).
-`control.begin` still needs the local `control` grant. Screen Recording for
+Hosted macOS frames and control require the default slot; hosted iOS and Android support 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
+### Hosted iOS, Android 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
+iOS simulator, Android emulator or running macOS app without access to the worker's registered
 workspaces:
 
 ```json
@@ -649,7 +881,7 @@ subscription ID as `params.subscription`. `device-host.frames.congested`
 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
+replay or screenshot fallback. iOS supports device artwork. 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
@@ -659,13 +891,27 @@ 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.
 
+Android capture uses the same `android-device <serial> <adb> <scrcpy-server>`
+helper transport as physical Android, addressed only to the session's exact
+`emulator-<port>` serial. It bypasses workspace target resolution and device
+leases. The server rechecks the private home's created-device ledger, recorded
+serial and system image, the running AVD identity and ABI. Unknown state refuses
+capture and input. The helper uses the host SDK from `ANDROID_HOME`,
+`ANDROID_SDK_ROOT` or `$HOME/Library/Android/sdk`, including under the LaunchAgent.
+It pushes the built scrcpy jar to `/data/local/tmp` and removes both that jar
+and its adb forward when capture stops. One viewer pool serves each session;
+the lifetime claim tracks the helper as its child. Android capture requires no
+macOS screen-recording permission.
+
 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
+iOS also supports `device-host.input.button|rotate|posture`. Android supports
+`device-host.input.button` through scrcpy; rotation and posture are unavailable
+on this path, as for physical Android devices. 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>"}`.
@@ -686,8 +932,7 @@ 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
+before replacement. Automatic placement remains in
 [#2266](https://github.com/appandflow/stim/issues/2266).
 
 ## Run as a service
@@ -1016,11 +1261,11 @@ closes its connections and cancels its builds.
   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 a macOS
+  answers `{ "name", "size", "sha256" }`, and deletes it here. For an iOS simulator, Android emulator 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
+  `.app` or APK 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 macOS build or a revoked approval deletes it. An archive nobody fetched is deleted when its job
+  fetched native 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.
 
@@ -1095,13 +1340,28 @@ Events are `{ "event", "subscription", ... }`.
   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.
+  `--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
@@ -1296,7 +1556,17 @@ Events are `{ "event", "subscription", ... }`.
   `at` and `frames.seek` on it fail with `no-recording`, and it counts
   toward no idle check.
 
-- **Replay.** `replay.range` takes `workspace`, `platform` and `slot`
+- **Archive detail.** `archive.detail` takes `{ archive: archived[].id }` and needs
+  `read`. It returns `{ builds, recordings }`: the archive's own iOS and Android
+  build history in the live environment's `builds` shape, and every retained
+  recording slot as `{ platform, slot, spans }`. Spans use the same ranges as
+  `replay.range`; devices without spans are omitted. Missing or unreadable state
+  yields `builds: {}`, and no recordings yields `recordings: []`. Reads share the
+  archive request queue, refuse unknown archives with `unknown-workspace`, and
+  skip symlinks. Older servers refuse it with `unknown-method`.
+  `status` keeps only the archive's build summary.
+
+- **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
@@ -1320,7 +1590,17 @@ Events are `{ "event", "subscription", ... }`.
   It needs only `read`. A device with no recording gets empty `spans` and
   `markers`, and runs no `stim` command.
 
-  `replay.keyframe` takes the same `workspace`, `platform` and `slot`, and
+  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