@stim-cli/server 1.15.0 → 1.16.0

package/README.md

@@ -22,6 +22,8 @@ stim-server devices grant <id> --control|--read|--build|--device-host
                                   # --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
@@ -207,7 +332,7 @@ 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
+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
@@ -226,7 +351,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
@@ -347,14 +473,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 +530,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 +568,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 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 +582,8 @@ 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; 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`.
@@ -551,19 +682,44 @@ 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. 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 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 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. 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
 
@@ -589,7 +745,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
@@ -601,15 +757,21 @@ 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).
+Android Metro/viewing remains in [#2266](https://github.com/appandflow/stim/issues/2266).
 
-### 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 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` 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
@@ -621,9 +783,8 @@ 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 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
@@ -1016,11 +1177,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 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 macOS build or a revoked approval deletes it. An archive nobody fetched is deleted when its job
+  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.
 
@@ -1095,13 +1256,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 +1472,7 @@ 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`
+- **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 +1496,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

package/dist/{protocol-MBMvJpvV.mjs → protocol-BHSl7bQ_.mjs}

@@ -187,6 +187,13 @@ function protocolJsonSchema() {
 									"deviceKey"
 								],
 								additionalProperties: false,
+								oneOf: [{
+									required: ["backend"],
+									properties: { deviceKey: { pattern: "^ios:mobile:[a-fA-F0-9-]{36}$" } }
+								}, {
+									not: { required: ["backend"] },
+									properties: { deviceKey: { pattern: "^[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)+@[1-9][0-9]{0,9}$" } }
+								}],
 								properties: {
 									tenant: {
 										type: "string",
@@ -200,10 +207,8 @@ function protocolJsonSchema() {
 										type: "string",
 										pattern: "^[A-Za-z0-9._-]{1,128}$"
 									},
-									deviceKey: {
-										type: "string",
-										pattern: "^[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)+@[1-9][0-9]{0,9}$"
-									}
+									backend: { const: "ios-instance" },
+									deviceKey: { type: "string" }
 								}
 							}
 						}
@@ -720,6 +725,12 @@ function protocolJsonSchema() {
 								deviceName: {
 									type: "string",
 									minLength: 1
+								},
+								setupTicket: {
+									type: "string",
+									minLength: 43,
+									maxLength: 43,
+									pattern: "^[A-Za-z0-9_-]{43}$"
 								}
 							}
 						}
@@ -819,13 +830,19 @@ function protocolJsonSchema() {
 			},
 			LogFilter: {
 				type: "object",
-				required: ["workspace"],
+				oneOf: [{ required: ["workspace"] }, { required: ["archive"] }],
 				additionalProperties: false,
 				properties: {
 					workspace: {
 						type: "string",
 						description: "An environment path from a status payload."
 					},
+					archive: {
+						type: "string",
+						minLength: 1,
+						pattern: "^(?!.*\\.\\.)[^/\\\\\\u0000]+$",
+						description: "An archived[].id from a status payload; omit workspace."
+					},
 					sources: {
 						type: "array",
 						minItems: 1,
@@ -958,13 +975,27 @@ function protocolJsonSchema() {
 			},
 			FrameTarget: {
 				type: "object",
-				required: ["workspace", "platform"],
+				required: ["platform"],
+				oneOf: [{
+					required: ["workspace"],
+					not: { required: ["archive"] }
+				}, {
+					required: ["archive", "at"],
+					not: { required: ["workspace"] },
+					properties: { physical: { const: false } }
+				}],
 				additionalProperties: false,
 				properties: {
 					workspace: {
 						type: "string",
 						description: "An environment path from a status payload."
 					},
+					archive: {
+						type: "string",
+						minLength: 1,
+						pattern: "^(?!.*\\.\\.)[^/\\\\\\u0000]+$",
+						description: "An archived[].id from a status payload; omit workspace."
+					},
 					platform: { enum: [...PLATFORMS] },
 					slot: {
 						type: "string",
@@ -1678,7 +1709,8 @@ function protocolJsonSchema() {
 					video: {
 						type: "array",
 						items: { type: "string" }
-					}
+					},
+					deviceFrame: { type: "boolean" }
 				})),
 				request("device-host.frames.keyframe", {
 					type: "object",
@@ -1816,10 +1848,16 @@ function protocolJsonSchema() {
 				}),
 				request("replay.range", {
 					type: "object",
-					required: ["workspace", "platform"],
+					required: ["platform"],
+					oneOf: [{ required: ["workspace"] }, { required: ["archive"] }],
 					additionalProperties: false,
 					properties: {
 						workspace: { type: "string" },
+						archive: {
+							type: "string",
+							minLength: 1,
+							pattern: "^(?!.*\\.\\.)[^/\\\\\\u0000]+$"
+						},
 						platform: { enum: [...RELOAD_PLATFORMS] },
 						slot: {
 							type: "string",
@@ -1829,14 +1867,16 @@ function protocolJsonSchema() {
 				}),
 				request("replay.keyframe", {
 					type: "object",
-					required: [
-						"workspace",
-						"platform",
-						"at"
-					],
+					required: ["platform", "at"],
+					oneOf: [{ required: ["workspace"] }, { required: ["archive"] }],
 					additionalProperties: false,
 					properties: {
 						workspace: { type: "string" },
+						archive: {
+							type: "string",
+							minLength: 1,
+							pattern: "^(?!.*\\.\\.)[^/\\\\\\u0000]+$"
+						},
 						platform: { enum: [...RELOAD_PLATFORMS] },
 						slot: {
 							type: "string",
@@ -2500,6 +2540,8 @@ function protocolJsonSchema() {
 					additionalProperties: false,
 					properties: {
 						event: { const: "device-frame" },
+						platform: { enum: [...PLATFORMS] },
+						slot: { type: "string" },
 						subscription: { type: "string" },
 						artwork: { oneOf: [{ type: "null" }, { $ref: "#/$defs/DeviceFrameArtwork" }] }
 					}
@@ -2574,6 +2616,15 @@ function protocolJsonSchema() {
 						}
 					}
 				},
+				{
+					type: "object",
+					required: ["event", "subscription"],
+					additionalProperties: false,
+					properties: {
+						event: { const: "logs-ended" },
+						subscription: { type: "string" }
+					}
+				},
 				{
 					type: "object",
 					required: [
@@ -2653,6 +2704,8 @@ function protocolJsonSchema() {
 					additionalProperties: false,
 					properties: {
 						event: { const: "frame-delayed" },
+						platform: { enum: [...PLATFORMS] },
+						slot: { type: "string" },
 						subscription: { type: "string" },
 						delayed: { type: "boolean" },
 						reason: { type: "string" }
@@ -2683,6 +2736,8 @@ function protocolJsonSchema() {
 					additionalProperties: false,
 					properties: {
 						event: { const: "control-ended" },
+						platform: { enum: [...PLATFORMS] },
+						slot: { type: "string" },
 						session: { type: "string" },
 						reason: { enum: [...CONTROL_END_REASONS] },
 						message: { type: "string" }
@@ -2698,6 +2753,8 @@ function protocolJsonSchema() {
 					additionalProperties: false,
 					properties: {
 						event: { const: "error" },
+						platform: { enum: [...PLATFORMS] },
+						slot: { type: "string" },
 						subscription: { type: "string" },
 						error: { $ref: "#/$defs/ProtocolError" }
 					}

package/dist/protocol.mjs

@@ -1,3 +1,3 @@
-import { t as protocolJsonSchema } from "./protocol-MBMvJpvV.mjs";
+import { t as protocolJsonSchema } from "./protocol-BHSl7bQ_.mjs";
 export * from "@stim-cli/core/protocol";
 export { protocolJsonSchema };