@stim-cli/server 1.16.0 → 1.17.1

package/README.md

@@ -16,7 +16,7 @@ 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
@@ -57,7 +57,7 @@ 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
+Desktop's Remote Macs 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.
 
@@ -91,7 +91,7 @@ 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]
+  [--env KEY=VALUE]... [--path-prepend <dir>]... [--yes] [--json] [--verbose]
 ```
 
 If the server is not installed globally, use `npx --yes --package @stim-cli/server@<version> stim-server`
@@ -144,8 +144,17 @@ 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`,
+In a terminal, setup prints a banner, then one line per step with a green check,
+a yellow arrow while a step runs, or a red cross; `NO_COLOR`, `TERM=dumb` and a
+non-terminal give plain `[ok]`, `[failed]` and `[pending]` marks, no colors and no
+in-place line. The y/N questions stay, one line each. The run ends with a
+headline such as "janics-mac-mini is ready to build for Janic's MacBook Pro", one
+line per approved capability, a `Fix` line for each skipped permission or missing
+tool, and one `To undo` line. `--verbose` prints every step with its detail, the
+install, service and route notes, and the long summary with the undo commands, as
+earlier releases did. Plain progress goes to stdout; errors use
+`stim-server: <message>` on stderr (when stdout is a terminal, the refusal appears on stdout only).
+`--json` sends the long (verbose) progress to stderr, without the banner, 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`,
@@ -172,7 +181,7 @@ 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:
+The `To undo` line (or the `--verbose` summary) lists the undo commands:
 
 ```bash
 stim-server devices revoke <build-request-id>
@@ -284,7 +293,7 @@ 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. Under Stim Host, an approved
 `hello` also carries the same `host` grants as `/health`, which `stim doctor`
-reports for hosting machines.
+reports for remote Macs.
 
 Every method other than `hello` needs `read`. A device with only `build`
 gets `forbidden` for all of them.
@@ -331,16 +340,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 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 settings set remote.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
@@ -365,6 +373,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:
@@ -572,7 +605,7 @@ session before starting another transfer. Manifest, file and partial blobs are s
 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
+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
@@ -583,7 +616,10 @@ 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.
+`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`.
@@ -619,11 +655,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
 
@@ -672,12 +728,12 @@ 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.
@@ -686,9 +742,19 @@ session stops, is revoked or the server closes.
 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,
+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 iOS window in epoch milliseconds. `log show` reads persisted entries;
+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
@@ -713,8 +779,9 @@ byte offset after the last complete line read; pass the previous result's cursor
 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`;
+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`.
 
@@ -731,10 +798,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
@@ -756,18 +831,23 @@ 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).
+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 `server.maxLoadPerCore`. Otherwise
+they rank compatible offers from `remote.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 viewer relay
 
-The client's stim-server relays a hosted workspace's iOS simulator or 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` and `ios-hosted` features advertise these relays.
-iOS resolves `ios.host` by the requested slot; macOS retains its default slot.
+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 control audit records. H.264 packets retain their flags and payload and
+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`.
@@ -783,14 +863,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 macOS frames and control require the default slot; hosted iOS supports named slots.
+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
@@ -810,7 +890,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
@@ -820,13 +900,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>"}`.
@@ -847,14 +941,13 @@ 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
 
 `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
+macOS, so a remote Mac or a phone-serving Mac keeps it running without a
 terminal:
 
 ```bash
@@ -995,18 +1088,18 @@ and uninstall of one label run one at a time.
 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
+To set up a remote Mac: 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
+`server.workerRoot` there, and on each client run
+`stim settings set remote.machines '["<mac>"]'` and `stim doctor --fix`.
+Approve the request on the remote Mac 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
+connection, so the remote Mac 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`:
@@ -1042,8 +1135,8 @@ 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
+`machines.update.start` takes `{ "machine" }`, an approved `remote.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
@@ -1076,7 +1169,7 @@ closes its connections and cancels its builds.
   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
+  `server.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
@@ -1113,7 +1206,7 @@ closes its connections and cancels its builds.
   `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
+  timeout set to `server.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
@@ -1177,15 +1270,15 @@ 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 an iOS simulator or 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 iOS or 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.
 
-The worker root is `offload.workerRoot` in this Mac's Stim settings, or
+The worker root is `server.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
@@ -1472,6 +1565,16 @@ Events are `{ "event", "subscription", ... }`.
   `at` and `frames.seek` on it fail with `no-recording`, and it counts
   toward no idle check.
 
+- **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):
@@ -1618,10 +1721,10 @@ Events are `{ "event", "subscription", ... }`.
   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
+  `unknown-method`. It also carries `buildMachines`, the `remoteMachines` 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
+  show whether each remote Mac takes builds. The server runs doctor only
+  when `remote.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
@@ -1633,7 +1736,7 @@ Events are `{ "event", "subscription", ... }`.
   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
+  carries `buildClients`, the builds this Mac ran for other Macs, 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