stim 1.14.0 → 1.16.0

package/dist/{guide-6R0VNFqI.mjs → guide-B_uyKTxW.mjs}

@@ -1,8 +1,8 @@
-import { a as findProjectRoot } from "./project-CWlvEaeN.mjs";
-import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-D61iNOsB.mjs";
-import { t as RECENT_LAUNCH_MS } from "./status-BgAuxESg.mjs";
-import { t as guideStatus } from "./guide-status-BZrFPIA_.mjs";
-import { SETTINGS_SCHEMA_URL } from "@stim-cli/core/state";
+import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-oTSkkNrM.mjs";
+import { o as findProjectRoot$1 } from "./project-Du91Ilvc.mjs";
+import { t as RECENT_LAUNCH_MS } from "./status-BuvBFeII.mjs";
+import { t as guideStatus } from "./guide-status-CjEZMAD4.mjs";
+import { SETTINGS, SETTINGS_SCHEMA_URL } from "@stim-cli/core/state";
 import chalk from "chalk";
 //#endregion
 //#region src/guide/index.ts
@@ -18,6 +18,10 @@ parse a stable payload.
 
 TWO WORKFLOWS
 
+WORKTREE is the default. Take SINGLE CHECKOUT only when the user asks to work in
+place, or the task depends on the user's uncommitted changes in the current
+checkout; say why.
+
 SINGLE CHECKOUT: work in place, on whatever branch the task needs, in one
 directory. start, ios, android, logs, stop, and never a linked worktree. That
 directory is your workspace, and no rule below about keeping the source checkout
@@ -39,14 +43,28 @@ reach multiple devices. A launch counts a bundle delivery only when it can
 attribute it to its own device; read guide lifecycle options for the rule.
 Use stop --slot <name> for one slot, or plain stop for the whole workspace.
 
+HOSTED IOS
+
+For ios --remote <machine>, read guide lifecycle hosted-ios. Stop before switching
+between a local simulator and a hosting Mac. Hosted Debug requires the local
+Metro supervisor; restart a missing or older one with stim stop; stim start.
+It never falls back here; stop reconciles the recorded host before changing placement.
+For hosted iOS, use agent-device <command> --remote-config <file> from ios.host.agent
+in stim status --json. Open the installed app first; never use the host UDID locally.
+See guide lifecycle hosted-ios for the agent policy and setup.
+
+When driving a device yourself with agent-device, set AGENT_DEVICE_STATE_DIR
+from agentDevice.stateDir in stim ios|android|macos --json or status --json.
+Its sessions and logs are then cleaned with the workspace. Do not set
+AGENT_DEVICE_IOS_RUNNER_DERIVED_PATH or AGENT_DEVICE_CLAIMS_DIR; the runner
+build cache and device claims stay shared. Read stim guide logs for examples.
+
 NORMAL WORKFLOW
 
-Work in the current checkout by default. When the task needs another branch or
-an isolated environment, take the worktree workflow: create a linked worktree
-with Git and warm its ignored state. If a harness already created this linked
-worktree, run stim worktree warm here instead of creating another one. It
-copies missing ignored paths from the source checkout, including eligible .env
-and local configuration files. It preserves the branch, tracked files, and
+Create a linked worktree with Git and warm its ignored state. If a harness
+already created this linked worktree, run stim worktree warm here instead of
+creating another one. It copies missing ignored paths from the source checkout,
+including eligible .env and local configuration files. It preserves the branch, tracked files, and
 every existing destination entry; existing ignored directories are skipped
 whole, not filled in. Add --refresh to fast-forward the source checkout and
 install what moved there before the copy; it refuses a source checkout with local
@@ -76,7 +94,8 @@ other apps or other workspaces' devices.
 
   stim doctor --platform ios          # or: --platform android
 
-  # Skip Git creation if the harness already created this linked worktree.
+  # Worktree workflow. Skip Git creation if the harness already created this
+  # linked worktree.
   git worktree add -b <branch> <worktree-path> HEAD
   cd <worktree-path>
   stim worktree warm
@@ -84,6 +103,12 @@ other apps or other workspaces' devices.
   stim start
   stim ios                             # or: stim android, or: stim web
 
+When Stim Desktop is installed, worktree warm, start, ios, android and web
+print "Open in Stim Desktop: <link>" on stderr (links.desktop in JSON). The
+first time one prints it in a workspace, tell the user once: "You can watch
+this workspace in Stim Desktop: <link>". Do not repeat it after later
+commands. When no command prints it, do not mention Stim Desktop.
+
 For the web target, stim web opens the page in a Stim-owned headless Chrome
 and captures its console and errors in stim logs. It never starts a web
 server: start the dev server first, then run stim web. For Expo web the dev
@@ -105,6 +130,12 @@ To learn whether the next build is a cache hit and how long it should take,
 without building, run stim ios --plan (or stim android --plan); see stim guide
 lifecycle builds.
 
+Agents never set STIM_ACCESS_TICKET, run stim-server setup, edit offload.*
+or hosting.* for the user, or approve requests. Read stim guide settings for
+Desktop access tickets and person-owned approval.
+Read stim guide settings to select a build machine. Keep a requested named
+placement when recovering STIM_OFFLOAD_REFUSED: report its reason and remedy.
+
 Read stim guide lifecycle concurrency when a build waits on another workspace
 or a build call times out. A native build can outlive a shell timeout; if the
 tool call timed out, retry the same command and follow its printed remedy if
@@ -128,6 +159,8 @@ waiting times out.
 
 RULES DURING THE LOOP
 
+- Agents never run stim-server setup and never approve access requests.
+  A person on the worker approves builds and device hosting (guide settings).
 - Run Stim from the app directory: the one whose package.json depends on
   react-native or expo. Anywhere else -- a monorepo root, a tools package --
   start, ios and android refuse with STIM_NO_PROJECT naming that package.json,
@@ -197,10 +230,11 @@ the stim-<label> (<model> <runtime>) name. Never point Stim at a user-created
 emulator or simulator.
 
 worktree remove parks the workspace's simulator or emulator for later adoption.
-Before owned-device teardown, Stim best-effort closes local agent-device sessions
+During owned-device teardown, Stim best-effort closes local agent-device sessions
 on that exact device; failures warn and teardown continues (guide cleanup).
-A parked device is Stim-owned: never delete one by hand. gc --delete clears verified
-entries and keeps failures; see guide lifecycle pool. First launch on a
+A parked device is Stim-owned: never delete or erase one by hand. gc --delete clears
+verified entries and keeps failures; gc --cache parked --delete erases them and keeps
+them parked; see guide lifecycle pool. First launch on a
 physical iPhone can need the one-time taps named by the remedy.
 
 stim android --device [serial] and stim ios --device [udid] install on a
@@ -298,8 +332,11 @@ Read the matching guide before acting in these situations:
 | Parallel iOS, simulator stall, or memory pressure     | stim guide lifecycle simslim     |
 | Android boot timeout                                  | stim guide errors STIM_NO_DEVICE |
 | gc or orphaned resources                              | stim guide cleanup gc            |
+| watchman or Gradle daemon memory                      | stim guide cleanup memory        |
 | worktree remove refusal or --force                    | stim guide errors remove         |
 | Cleanup failure or unverified cleanup ownership       | stim guide errors teardown       |
+| Swift Package macOS development                        | stim guide macos                 |
+| macOS app on another Mac (stim macos --remote)        | stim guide macos                 |
 | Unfamiliar state or JSON field                        | stim guide facts payloads        |
 | Refusal without a code                                | stim guide errors                |
 
@@ -328,12 +365,14 @@ FULL TOPIC LIST
   stim guide lifecycle release    # Release configurations and ...Release variants
   stim guide facts                # the --json payloads
   stim guide facts devmenu        # the Expo dev menu or Tools button over the app
+  stim guide macos                # Swift Package Debug apps, logs, local preview, --remote on another Mac
   stim guide web                  # stim web: owned Chrome, page logs, launched, teardown
   stim guide ports                # named ports for web and API servers
   stim guide metro                # supervisor, custom Metro, tunnels, and remote devices
   stim guide logs                 # filters, record shape, and capture limits
   stim guide cleanup              # what reclaims a device, and what deletes
   stim guide cleanup collector    # an unproven collector pid; why the app on a phone closed
+  stim guide cleanup memory       # watchman and Gradle daemon memory; gc --cache watchman
   stim guide settings             # configuration files and supported keys`
 	},
 	facts: {
@@ -352,6 +391,15 @@ stdout for \`--json\`. Every other line goes to stderr, so it is always safe
 to pipe. \`logs --json\` is the one exception: it is NDJSON, one record per
 line by design (see \`guide logs\`), not this single-payload contract.
 
+status adds archived (newest first, bounded by archive.maxCount) and
+archivedUsage { count, bytes, byKind: { logs, recordings, agentActions, record } }.
+Each archive carries id, projectRoot, project, workspace, worktree facts,
+removedAt, removedBy, lastUsedAt, builds, agents, bytes, expires and version.
+replacedBy is the live environment path when its canonical root matches.
+Older producers may omit both fields.
+Plain status prints Archived: <count> workspace(s), <size> when count is positive;
+status --watch reuses archive reads until archive changes and emits no duplicates.
+
 status's unprovisionedWorktrees lists the linked worktrees with no Stim
 environment in every repository with a registered environment, plus the
 repository status runs from. A worktree counts as having an
@@ -360,9 +408,13 @@ environment when one is registered at it or inside it. Each entry is
 directory of a bare repository. status lists worktrees from git's own worktree
 records, and on macOS runs no git in a worktree with no environment under a
 protected folder such as ~/Documents, so listing it raises no privacy prompt.
-\`worktree warm\` does not create an environment; \`start\`, \`ios\`,
-\`android\` and \`doctor\` register it. An environment's worktree is the
-linked worktree it is registered at or inside.
+\`worktree warm\` registers the app it prepares, before it copies: the
+nearest React Native or Expo app above where it runs when that is below the
+worktree root; else the one app the source checkout has registered, at the
+same path in this worktree; else the worktree root when it is the app. A warm
+that finds none registers nothing and says so on stderr, and \`start\`, \`ios\`,
+\`android\` and \`doctor\` register the app later. An environment's worktree is the linked worktree it is
+registered at or inside.
 
 Each worktree entry, in unprovisionedWorktrees and in an environment's
 worktree, carries git:
@@ -392,6 +444,46 @@ change, and for at most 60 s, so a file edit, creation or deletion that is
 not staged can take up to a minute to show. Plain status prints "git: 2 changed, 1 untracked, ahead 3" under
 each environment, and the same after each worktree with no environment.
 
+The paired phone's Work sheet can open changed and untracked files when the
+server advertises workspace-diff. File lists and selected patches load on
+demand, not through status. The read-only preview is capped at 200 files per
+list and 256 KiB per patch response; binary and unavailable files are labeled. Active Git clean/process filters
+(including Git LFS) refuse without running those commands.
+
+A worktree entry also carries pullRequest, the GitHub pull request of its
+branch and HEAD, once \`status --watch\` has looked it up:
+
+  pullRequest     { number, url, title, state, checks, reviewDecision,
+                  checkedAt }, null when GitHub has none for the branch and
+                  HEAD, absent when never looked up: gh missing or signed
+                  out, no GitHub remote, or status could not read the
+                  worktree's git. A later gh failure keeps the last answer.
+  state           "open", "draft", "merged" or "closed"
+  checks          { passing, failing, pending } counts of the head commit's
+                  check runs and commit statuses, or null when it has none
+  reviewDecision  "approved", "changes-requested", "review-required" or null
+  checkedAt       when Stim last asked GitHub
+
+A worktree entry with git also carries gitChip, the git chip Stim Desktop and
+the phone app show for it:
+
+  gitChip   { parts, ci }
+  parts     in order: { kind: "arrows", ahead, behind } when either is above
+            0; { kind: "changed", count } of changed plus untracked entries;
+            { kind: "merged", into } when mergedInto is set and the pull
+            request is not merged; { kind: "no-upstream" } when the branch is
+            not merged and upstream is null
+  ci        "failing" when a check fails, else "pending" when one is pending,
+            else "passing" when one passes; null without a pull request or
+            checks
+
+\`status --watch\` asks GitHub off its refresh path, through the same gh api
+graphql lookup gc uses, one call per repository, for a worktree whose lookup
+is over 5 minutes old or whose branch or HEAD moved. It runs git in the
+repository, never in the worktree. It caches each answer
+under $STIM_HOME/pull-requests, which one-shot status only reads, and never
+warns when gh is unavailable.
+
 status's remoteDevices lists each environment's recorded EAS Simulator
 session. The session is billable while it runs, and it makes the environment
 live. status reads only local records; it does not ask EAS whether the session
@@ -409,10 +501,37 @@ is still running.
                   Stim created the session, or null
 
 Plain status prints one "remote <platform>: EAS session <id> billable" line
-per session, with the preview URL.`,
+per session, with the preview URL.
+
+status's physicalDevices lists each physical phone or tablet the environment
+holds an unexpired lease on, from \`ios --device\`, \`android --device\` or
+\`device lock\`, in every slot. A run lease ends with its run, so a phone
+stays listed after the run only while \`device lock\` holds it. A
+simulator or emulator lease is not listed. The field is absent when the
+workspace leases no physical device.
+
+  physicalDevices  [{ platform, slot, id, name, model, owned, physical,
+                   connection, lease }]
+  id               the UDID or adb serial
+  name             the device's own name, else the name the lease recorded
+  model            devicectl's marketing name ("iPhone 12 Pro"), null when
+                   unread, or the Android model the lease recorded
+  owned            always false: Stim uses a physical device, never owns it
+  physical         always true
+  connection       "connected"     devicectl can reach the phone, or adb lists
+                                   the serial as device
+                   "disconnected"  the tool answered without it
+                   "unknown"       the tool could not be read in time
+                   status reuses one devicectl or adb listing for 30 s
+                   under \`status --watch\`
+  lease            { holder, kind, grantedAt, expiresAt }: holder is the
+                   workspace path, kind "declared" (device lock) or "run"
+
+Plain status prints "ios: Old iPhone (physical, iPhone 12 Pro) connected --
+leased until <time>" for each one.`,
 		sections: {
 			payloads: {
-				summary: "every field of the start, ios, android, web and reload payloads, the error contract, the device rules",
+				summary: "every field of the start, ios, android, macos, web and reload payloads, the error contract, the device rules",
 				body: () => `  stim start --json
 
   port            the Metro port RESERVED for this workspace
@@ -420,7 +539,21 @@ per session, with the preview URL.`,
                   already answering that Stim did not start
   mode            "bare-inproc" | "expo-child" | null (see \`guide metro\`)
   logsDir         where the NDJSON timeline is written
+  agentDevice     { stateDir }: absolute workspace agent-device state path;
+                  set AGENT_DEVICE_STATE_DIR to it (see guide logs)
   alreadyRunning  true when nothing needed starting
+  links           { desktop }: a stim-desktop://workspace?path=<workspace>
+                  link that shows this workspace in Stim Desktop. Absent when
+                  no app on this Mac opens stim-desktop links. Plain output
+                  prints it on stderr as "Open in Stim Desktop: <link>"; so
+                  does worktree warm, which has no JSON payload
+
+  stim macos --json
+
+  platform        "macos"
+  product, launchId, build, host?  the launch record (see guide macos)
+  agentDevice     { stateDir }: absolute workspace agent-device state path
+                  for local or hosted launches with a local workspace
 
   stim ios --json
 
@@ -471,7 +604,12 @@ per session, with the preview URL.`,
   scheme          the explicit shared Xcode scheme selected by --scheme;
                   absent for automatic selection; not the app URL scheme
   cacheKey        the shared-build-cache key derived from it (the
-                  configuration is part of it: -release-sim vs -debug-sim)
+                  configuration is part of it: -release-sim vs
+                  -debug-sim-arm64). A single-architecture simulator build
+                  ends in its architecture (-arm64 or -x86-64): a local Debug
+                  build compiles this Mac's, a --remote build the remote
+                  host's. A local non-Debug simulator build compiles every
+                  architecture the project lists and has no suffix
   With --eas-profile, fingerprint is computed by EAS CLI using the selected
   profile/environment, and cacheKey identifies the EAS project and build ID
   separately from local native builds. cacheHit is "remote" for the EAS
@@ -490,6 +628,15 @@ per session, with the preview URL.`,
                   the device; it is a page, not a deep link.
   cacheSkipped    true only when --no-build-cache was passed: "nothing was
                   looked up", which is a different fact from "nothing was found"
+  buildMachine    selected auto, local or machine name, including cache hits
+  builtOn         here or machine name when a build ran; absent otherwise
+  offloadedTo     only on an app a build machine compiled: its
+                  offload.machines entry (see \`guide settings\`). cacheHit is
+                  false for it. The Android payload carries it too
+  offloadFallback only on an app compiled here after the run considered
+                  offloading it: why it built here -- one reason per
+                  machine when none took the build, or why the offload
+                  stopped. The Android payload carries it too
   compilationCache
                   Xcode compilation-cache activity for a compiled iOS app:
                     { status: "reported", hits, cacheableTasks, hitRatePercent }
@@ -561,6 +708,7 @@ per session, with the preview URL.`,
                   launch with no process id is "unverified", and
                   \`stim logs --errors\` has the device log that says why
   logs            { dir }
+  agentDevice     { stateDir }: absolute workspace agent-device state path
   durationMs      wall time for the whole run
 
   stim android --json
@@ -588,7 +736,8 @@ per session, with the preview URL.`,
                   hw.device.name. Null where systemImage is null, and on an
                   AVD of the old generic profile, which has no hw.device.name
   fingerprint / cacheKey / cacheHit / cacheSkipped / waitedForBuild /
-  appPath / installSkipped / launched
+  appPath / installSkipped / launched / buildMachine / builtOn /
+  offloadedTo / offloadFallback
                   as above -- cacheKey keys on the VARIANT here
                   (<fingerprint>-productionrelease-sim). A Debug artifact for
                   a proven target ABI also ends in that ABI
@@ -630,8 +779,10 @@ per session, with the preview URL.`,
                   through ccache -- ccache absent from PATH, a project that
                   sets its own CMake compiler launcher, or a Gradle run whose
                   native work was all up to date. None of the three is an
-                  error, and this field is separate from cacheHit
+                  error, and this field is separate from cacheHit. On an
+                  offloaded APK it is the build machine's ccache
   logs            the workspace log directory
+  agentDevice     { stateDir }: absolute workspace agent-device state path
   durationMs      wall time for the whole run
   reclaimed       present only when the run was over its disk or memory
                   budget and reclaimed first (\`start\`, \`ios\` and
@@ -647,6 +798,8 @@ per session, with the preview URL.`,
                     { started: true, reason }
                   reason is "not running" or "stopped (idle)" when the
                   supervisor had stopped it after metro.idleStopMinutes
+  links           as in start, with &platform= and, for a named slot, &slot=,
+                  so Stim Desktop can focus that device
 
   stim reload [ios|android|web] --json
 
@@ -659,7 +812,8 @@ per session, with the preview URL.`,
   deviceId        the exact owned simulator UDID or emulator serial targeted;
                   for web, the owned Chrome's DevTools endpoint
   deviceName      the owned simulator or AVD name; for web, the Chrome version
-  appId           the live bundle id or Android package; for web, the page URL
+  appId           the live bundle id or Android package; for web, the URL the
+                  owned page was on when Stim sent the reload
   metroPort       the workspace's verified Metro port; for web, the reserved
                   Metro port or null
   strategy        how the reload was addressed.
@@ -677,6 +831,9 @@ per session, with the preview URL.`,
                   broadcast. Greater than 1 means several devices are running
                   this app on that Metro and the request addressed all of
                   them, not only deviceId. Completion is not observed
+  reverseRestored the Android serials whose adb reverse for metroPort was
+                  missing and that Stim re-applied before reloading; [] when
+                  none was, and always [] for iOS and web
 
   stim web --json
 
@@ -692,6 +849,8 @@ per session, with the preview URL.`,
   profile         the Stim-owned Chrome user data directory
   cdpEndpoint     http://127.0.0.1:<port>, the reserved DevTools endpoint, or
                   null when not running
+  targetId        the DevTools target id of the owned page, or null when not
+                  running
   reused          true when the running Chrome navigated again instead of
                   starting: same --headed, viewport and certificate options
   launched        true | "bundling" | "unverified" (see \`guide web\`)
@@ -699,6 +858,7 @@ per session, with the preview URL.`,
                   that does not use {port:metro}
   logs            { dir }: web.ndjson holds the page records
   durationMs      wall time of the run
+  links           as in start, with &platform=web
 
   stim doctor --json
 
@@ -719,8 +879,42 @@ per session, with the preview URL.`,
                   null when off; plan lists what the next start, ios or
                   android would reclaim, in the \`reclaimed\` shape without
                   freedMb, and is empty while under budget
+  deviceHosts     one { machine, state, dnsName?, deviceId?, requestedAt?, host? }
+                  per hosting.machines entry. state is "approved", "pending",
+                  "not-asked", "revoked", "node-changed", "not-on-tailnet",
+                  "tailscale-off", "unreachable", "invalid",
+                  "credentials-unavailable" or "busy". Tokens stay private.
+                  Only --fix asks for access or forgets removed names.
+                  An approved hosting machine does not imply build approval
+                  or change ios/android placement; see \`guide settings\`.
+                  host is { name, screenRecording, accessibility }, present
+                  only for approved machines whose worker reports it.
+  buildMachines   one { machine, state, dnsName?, deviceId?, requestedAt?,
+                  offloadable?, reasons?, problems?, capacity?, host? } per
+                  offload.machines entry; state is "approved", "pending", "not-asked",
+                  "revoked" (revoked, or the request lapsed), "node-changed",
+                  "not-on-tailnet", "tailscale-off", "unreachable" or
+                  "invalid". host has the same shape and presence rule as in
+                  deviceHosts. An approved machine also carries offloadable,
+                  true when it would take this app's builds now (iOS
+                  simulator unless --platform android, Android emulator when
+                  --platform android or the app has android/ or uses Expo,
+                  plus macOS SwiftPM when Package.swift exists and no platform
+                  is selected on a Mac), and reasons, each reason it would not,
+                  prefixed "iOS: ", "Android: " or "macOS: " when only one platform
+                  has it, with a finding
+                  per reason (code build-machine-<reason>: unreachable,
+                  checkout, stim-build, arch, xcode, simulator-sdk, macos-sdk,
+                  cocoapods, bundler, runtime, jdk, android-sdk, ndk,
+                  build-tools, compile-sdk, disk or busy). problems lists the same
+                  reasons as { code, reason } with that code. capacity
+                  is the machine's offer: { running, max, diskFreeBytes,
+                  minDiskFreeBytes, cpus?, loadPerCore?, builds?, maxBuilds?,
+                  maxLoadPerCore?, declined? }; an older stim-server omits the
+                  optional fields
   findings        the diagnostic findings; a lower resolved Stim is a
                   costs-time finding with a PATH or installation remedy
+                  offload-candidate is a note after 3+ successful local cold builds in 7 days average over 3 min, with no offload.machines and an online tailnet Mac; open Stim Desktop Settings > Build machines > Add
 
 ON FAILURE
   \`start\`, \`ios\`, \`android\` and \`web\` all print the error contract instead,
@@ -741,7 +935,8 @@ ON FAILURE
   lease, Ctrl-C with no build tool running) exits 130 with no payload.
 
   \`stop --json\` prints { root, ok, supervisor, collectors, metro, device,
-  port, metroTunnel, releasedLeases }. When it cannot end the \`ios\` or
+  port, metroTunnel, releasedLeases, macos? }. macos is { status: stopped | failed,
+  reason? } when a macOS app is recorded. When it cannot end the \`ios\` or
   \`android\` run holding the workspace, it prints the error contract with
   root and ok: false instead, plus device.remote when it ended a recorded EAS
   session first, and exits 1:
@@ -787,16 +982,50 @@ RULES
   that is the URL the launcher hands to the check; on the
   outer deep link it does nothing there. Android reads it on
   either.
-  ON A SIMULATOR, before a local dev-client openurl, Stim
-  preapproves CoreSimulatorBridge for exactly the installed
-  bundle id and discovered scheme on its owned simulator. That
-  suppresses iOS's first-launch confirmation;
-  unrelated schemes remain unapproved. It also writes
+  ON AN OWNED SIMULATOR, Stim preapproves CoreSimulatorBridge
+  for the installed bundle id and every URL scheme its Info.plist
+  declares, except system and third-party SDK schemes, also for
+  apps without expo-dev-client. The "Open in <App>?" alert can
+  still appear for an unapproved scheme, on a physical device or
+  user-created simulator, or from another opener such as Safari.
+  After \`simctl openurl\` or \`agent-device open <url>\`, expect
+  it for such schemes; take a snapshot and tap Open.
+  Approvals persist until erasure; Stim records them and writes
+  only missing ones. Parking drops the record, so adoption
+  rewrites them once.
+  THE DEV MENU AND ITS BUTTON stay off a simulator two ways,
+  which the onboarding flag does NOT cover. Stim's own
+  \`simctl launch --initialUrl\` ends in
+  \`-EXDevMenuShowsAtLaunch 0 -EXDevMenuShowFloatingActionButton 0\`
+  as trailing argv, the same mechanism the phone launch uses:
+  NSUserDefaults reads the argument domain ahead of the
+  persisted one, so Stim's own launch comes up on the app, not
+  the menu, without writing to the simulator. Stim also writes
   EXDevMenuShowsAtLaunch=false and
-  EXDevMenuShowFloatingActionButton=false, which the flag does
-  NOT cover, and those together are what keep the menu and its
-  button off a simulator entirely, so device automation opens
-  on the app. The
+  EXDevMenuShowFloatingActionButton=false to the app's
+  persisted defaults, but only on a real install -- one that
+  is not skipped as byte-identical -- or when its own launch
+  falls back to \`simctl openurl\` (no console capture in flight),
+  which carries no launch arguments at all and so writes them
+  itself before opening the URL. Adoption clears the app's
+  data by replacing its defaults with those two keys (one
+  \`defaults import\`), so an install that adoption then skips
+  as byte-identical keeps them too. Those persisted values
+  cover launches Stim did not make: a home-screen tap, an
+  agent relaunch, or a crash restart. The \`__expo_\` deep-link
+  params below last one process and do not persist.
+  When the project's installed expo-dev-launcher (found
+  through expo-dev-client, no network) is 58.0.0 or later
+  (expo/expo#49651), Stim's own deep link also carries
+  \`disableFab=1&disableAutoLaunch=1\` on the outer link and
+  on the project url, plus
+  \`__expo_disable_fab=1&__expo_disable_auto_launch=1\` on the
+  project url, which is the only url \`simctl launch
+  --initialUrl\` hands the launcher and the one 58.0.7 reads
+  the \`__expo_\` spellings from, for that launch only. So
+  device automation opens on the app.
+  The \`install     dev client prepared (...)\` line appears
+  only when one of those simulator writes ran. The
   unverified warning therefore leads with the picker, then
   prints the openurl
   retry. ON LOCAL ANDROID the same deep link also carries the
@@ -808,8 +1037,8 @@ RULES
   Remote Android opens only the URL, so that intent-extra
   suppression does not apply there.
   Every Stim deep link also carries an outer \`disableFab=1\`
-  query parameter. Versions with expo/expo#49651 use that as a
-  session-only override; earlier versions ignore it. Stim does
+  query parameter. Versions with expo/expo#49651 read it and
+  hide the button; earlier versions ignore it. Stim does
   not rewrite expo-dev-menu's private SharedPreferences XML:
   that internal file is not a supported API, and changing it
   would persist over the user's own Tools-button setting. The
@@ -856,7 +1085,7 @@ RULES
   writes and the Local Network grant both survive an
   UPGRADE install. Android's intent extra prevents the menu's
   automatic launch; versions with expo/expo#49651 also honor
-  the session-only FAB flag in Stim's deep link.
+  the outer FAB flag in Stim's deep link.
   The phone's unverified remedy is also ROUTED, not a fixed
   list. When this launch's device records carry the Local
   Network path reason, the remedy leads with that evidence and
@@ -871,7 +1100,7 @@ RULES
 			},
 			gc: {
 				summary: "the gc report payload: mode, sections, reasons, failures, results, inventory, and the gc refusals",
-				body: () => `  stim gc [--delete] [--older-than <days>] [--cache <name|all|workspaces>]
+				body: () => `  stim gc [--delete] [--older-than <days>] [--cache <name|all|workspaces|recordings|parked>]
           [--worktrees] [--idle <duration>] --json
 
   The report the text prints, as one payload. Show the user its sections
@@ -884,7 +1113,8 @@ RULES
   idle            the --idle duration in milliseconds, or null
   cacheScope      the --cache name, or null. When set, devices, project
                   entries and locks were not inspected and their sections
-                  are empty
+                  are empty, except that --cache parked fills
+                  parkedSimulators and parkedEmulators
   olderThan       the --older-than days, or null
   worktreeSweep   null without --worktrees; otherwise { olderThan, defaulted }:
                   the idle days a linked worktree needs, and whether that is
@@ -898,10 +1128,13 @@ RULES
                   run. status is "done", "kept" (left alone, detail says
                   why) or "failed" (detail says why and what to retry).
                   kind: device, parkedDevice, idleDevice, deviceRecord,
-                  workspaceOutputs, workspaceDirectory, project, buildLock,
-                  buildSlot, deviceLease, easSession, worktree, cache.
+                  workspaceOutputs, recording, workspaceDirectory, project,
+                  buildLock, buildSlot, deviceLease, easSession, worktree,
+                  cache.
                   label is a device, path or cache name; id is the UDID,
-                  AVD name or path behind it, or null
+                  AVD name or path behind it, or null. Under --cache
+                  parked, a "done" parkedDevice was erased and stays
+                  parked; otherwise it was deleted
   inventory       null except on a dry run without --cache or --idle. Report
                   only: gc never acts on it, even under --delete.
                   { devices, runtimes, systemImages, notices }
@@ -933,6 +1166,10 @@ RULES
                     timing out or an AVD or system image folder Stim
                     cannot read. A macOS privacy denial (EPERM) names the
                     Privacy & Security setting to grant
+  maintenance     top-level { mode, pressure, actions, blocked,
+                  skips, note, invalid? }, the next report-only maintenance plan
+                  from live pressure and cached sizes. note says when no
+                  pass has run yet. No du runs for this preview.
   sections        one array per report section, in the text order. Every key
                   is present, empty when there is nothing to report:
     deadProjects            { path }
@@ -955,10 +1192,12 @@ RULES
                               recent-activity worktree becomes removable,
                               else null. Without --worktrees, the source
                               checkout and roots outside git are left out
-    parkedSimulators        { udid, name, model, runtime, parkedAt, bytes,
-                              listed }  with --older-than, only those parked
-                              at least that long
-    parkedEmulators         { name, systemImage, deviceProfile, parkedAt, bytes, listed }
+    parkedSimulators        { udid, name, model, runtime, parkedAt, app,
+                              bytes, listed }  app is the bundle id recorded
+                              at park, else null; with --older-than, only
+                              those parked at least that long
+    parkedEmulators         { name, systemImage, deviceProfile, parkedAt, app,
+                              bytes, listed }  app is the package name;
                               likewise
     orphanedDevices         { kind, id, name, bytes, directory }
     unverifiedDevices       { kind, id, name, command }  stim-* devices this
@@ -976,6 +1215,10 @@ RULES
                               root, and browser profile paths whose
                               directory is gone; --delete forgets the
                               ledger entry only
+    staleStatusCaches       { kind: "disk-usage" | "pull-request", path,
+                              file, bytes }  entries of $STIM_HOME/disk-usage
+                              and pull-requests whose path is gone from a
+                              mounted volume; --delete removes the file
     idleDevices             { kind, id, name, project, slot, lastActivityAt,
                               idleForMs, buildInProgress }  booted owned
                               devices whose status activity is "idle";
@@ -999,14 +1242,52 @@ RULES
                               Metro, client and device logs over twice the
                               8 MiB cap; willTrim marks the ones it would
                               trim
+    recordings              { dir, projectRoot, bytes, deleteBytes,
+                              willDelete, withWorkspace, reason, detail }
+                              recordings/ of each workspace; deleteBytes is
+                              what --delete would remove; withWorkspace
+                              marks those of a gone workspace, removed with
+                              its workspace directory
     workspaceBuildOutputs   { dir, projectRoot, bytes, idleDays, willClear,
                               reason, detail }  derived-data, gradle-build,
-                              android-cas and cache-provider of each
+                              android-cas, cache-provider, macos/build,
+                              macos/<Product>.app and macos/staging-* of each
                               workspace; willClear marks the ones --delete
-                              would clear
+                              would clear; --cache workspaces omits the
+                              directories that --delete removes whole (dead
+                              projects and orphanedWorkspaces), and --cache
+                              all does not
+    agentDevice             <AgentDeviceUsage|null>  report-only; workspace state
+                              goes only with its workspace;
+                              null with any --cache scope
+    swiftpmCache            <SwiftpmCacheUsage|null> report-only, never deleted;
+                              null with any --cache scope
     caches                  { name, dir, source, bytes, note, willEmpty,
-                              emptySkipped }  alive, not garbage; willEmpty
-                              marks the ones --delete would empty
+                              emptySkipped, scopedEmpty }  alive, not
+                              garbage; willEmpty marks the ones --delete
+                              would empty. scopedEmpty is { willEmpty,
+                              emptySkipped } and says what \`--delete
+                              --cache <selector>\` without --older-than
+                              would do to the cache; it is present without
+                              --cache and null with it, where willEmpty
+                              already says so. Caches that share a name
+                              carry their directory's last component, as
+                              "Metro transform cache: <store>"
+    memory                  { kind: "watchman" | "gradleDaemon" |
+                              "kotlinDaemon", cacheKind: "watchman" |
+                              "gradle-daemons", pid, startedAt, bytes,
+                              measure: "footprint" | "rss", version,
+                              gradleHome, offloadClient, state: "idle" |
+                              "busy" | "unknown", reclaimable, reason,
+                              detail }  without --cache, or with --cache
+                              watchman or gradle-daemons; reclaimable marks
+                              the ones gc --delete --cache <cacheKind>
+                              would stop (\`guide cleanup memory\`)
+    watchmanRoots           { path, stale: "missing" | "pruned-worktree" |
+                              null, subscriptions, triggers, removable,
+                              detail }  removable marks the stale roots
+                              --cache watchman would watch-del
+    memoryNotices           { message }  why the memory sweep was skipped
   bytes is null when the size is unknown: not measured, or the measurement
   failed. idleDays is null when the last use is unknown. listed is false for
   a parked device that is no longer on this machine, and null when its
@@ -1018,6 +1299,9 @@ RULES
     workspaceBuildOutputs   unresolved | in-use | last-use-unknown |
                             recently-used
     workspaceLogs           unresolved | in-use | collector
+    recordings              unresolved | retained | recently-recorded
+    memory                  in-use | busy | unknown | build-running |
+                            stim-server
     linkedWorktrees         not-a-worktree | bare-repository |
                             source-checkout-unknown | source-checkout |
                             locked | in-use | status-unreadable | dirty |
@@ -1032,26 +1316,110 @@ RULES
 
   - a --cache name that no shared cache carries; the remedy names the
     caches on this machine
-  - --cache together with --worktrees or --idle`
+  - --cache together with --worktrees or --idle
+  - --cache watchman or gradle-daemons together with --older-than`
 			},
 			status: {
-				summary: "the status payload's issues and their codes, build and device activity fields: a running build, its estimate, each platform's last build, who drives each device, whether the app runs on it, and what uses CPU and memory now",
+				summary: "the status payload's lifecycle phase and stage, issues and their codes, build and device activity fields: a running build, its estimate, each platform's last build, who drives each device, whether the app runs on it, and what uses CPU and memory now",
 				body: () => `  stim status --json
 
+  logs        { dir, errorsSinceMarker }, or null without a log directory
+  agentDevice { stateDir }: absolute workspace agent-device state path on
+              every environment, shared by its slots. Reporting it creates
+              no directory; agent-device creates it when used.
+
+  Each environment carries phase, where the workspace is in its lifecycle:
+
+  phase       "warming"  stim worktree warm runs in it now
+              "ready"    its last warm succeeded and nothing has run there
+                         since: no start, ios, android, web or reload, for
+                         at most 2 hours
+              "live"     live is true: Metro, a device, Chrome or a remote
+                         session of it runs
+              "idle"     none of these
+  phaseSince  when the warm started ("warming") or finished ("ready"); null
+              for "live" and "idle"
+  warmStep    "refresh" or "copy", the step a warming workspace is in;
+              absent in other phases
+  platforms   ordered supported app platforms: ios, android, macos, web;
+              always present, [] when none are detected. Expo uses its
+              explicit platforms list, otherwise ios and android plus web
+              with react-native-web. Bare apps use ios/*.xcodeproj or
+              *.xcworkspace and android/ Gradle project files. web.url adds
+              web to any app and overrides an Expo list; a bare app has no
+              other route to web. macOS needs Package.swift, macos.product
+              and macos.infoPlist. Detection reads config literals and
+              files, never runs project scripts.
+  recording   { enabled }: whether stim-server may record the workspace's
+              device screens for replay, from recording.enabled
+
+  Each environment also carries stage, where the workspace is as Stim
+  Desktop and the phone app show it: { kind, since, platform, closedApps }.
+  The first kind that applies wins:
+
+  kind        "building"      a build runs; platform names it
+              "warming"       phase is "warming" and nothing is live
+              "ready"         phase is "ready" and nothing is live
+              "build-failed"  the newest run of either platform failed;
+                              platform names it
+              "running"       live is true or a remote session runs
+              "stopped"       none of these
+  since       when it began: the build's start, phaseSince, the failed
+              run's finishedAt (else startedAt), the supervisor's start or
+              metro.lastStop.at; null when unknown
+  platform    "ios" or "android" for "building" and "build-failed", else null
+  closedApps  for "running", [{ platform, slot }] of the devices whose
+              appPresence is "closed", the default slot first, then each
+              slot in order, iOS before Android; empty otherwise
+
+  A warm records warming under its own ownership claim, so a warm that was
+  killed or failed reads as idle, never as warming. Plain \`stim status\`
+  marks the workspace [warming: <step>], [ready] or [idle].
+
   Each environment carries issues, the things in that workspace that need
-  the user, and warnings, the same issues as text ("<slot>: " when not the
-  default slot, then "<message>; run \`<remedy>\`"):
+  the user, and warnings, its error and warning issues as text ("<slot>: "
+  when not the default slot, then "<message>; run \`<remedy>\`"):
 
   issues   [{ code, severity, message, remedy, workspace, slot? }]
 
-  code       port-not-ours          something other than this workspace's
-                                    Metro answers its reserved port
-             sim-missing            the recorded simulator no longer exists
+  severity   "error"    Stim cannot verify or safely act on something; a
+                        person resolves it (stim guide errors teardown)
+             "warning"  something is broken now and needs someone to act:
+                        an app cannot reach Metro, a port is held, an
+                        expected device vanished
+             "info"     a fact the next normal stim command handles by
+                        itself, so it needs no action
+             The apps show error and warning and hide info; plain stim
+             status prints info as a dim note with no remedy; warnings
+             excludes info. The info codes: sim-missing, sim-without-metro,
+             avd-missing, and port-not-ours while no supervisor runs.
+
+  code       port-not-ours          another process answers Metro on this
+                                    workspace's reserved port. "info" with
+                                    remedy stim start when no supervisor
+                                    runs: start reserves a free port.
+                                    "warning" when this workspace's
+                                    supervisor runs and cannot serve there
+                                    (remedy stim stop), or its supervisor is
+                                    unverified. The message names the holder:
+                                    "Metro for workspace <name>" when it runs
+                                    inside another workspace, else "a dev
+                                    server in <last dirs>"; metro.heldBy
+                                    carries its pid and cwd
+             sim-missing            the recorded simulator no longer exists;
+                                    always "info", stim ios creates a new one
              sim-without-metro      the simulator is booted and no Metro
-                                    serves the workspace
+                                    serves the workspace; always "info"
              avd-serial-changed     the owned emulator came back on another
                                     serial, so Metro forwarding is lost
-             avd-missing            the recorded AVD no longer exists
+             avd-missing            the recorded AVD no longer exists; always
+                                    "info", stim android creates a new one
+             android-reverse-missing the owned emulator runs this
+                                    workspace's debug app against its live
+                                    Metro, but the adb reverse for that Metro
+                                    port is gone, so the app cannot reach
+                                    Metro; the remedy stim reload android
+                                    restores it
              avd-not-detected       adb does not see the owned emulator while
                                     the workspace expects it: it holds an
                                     unexpired lease on its serial, or it
@@ -1071,8 +1439,8 @@ RULES
              browser-orphaned       the owned Chrome runs but its supervisor
                                     exited, so page logs are not captured;
                                     stim stop closes it
-  severity   "error" when stop or start refuses until it is resolved, else
-             "warning"
+  severity   the rule above; "error" is also what makes stop or start
+             refuse until it is resolved
   remedy     a command to run from workspace, such as "stim android --slot
              fold"
   slot       absent for the default slot
@@ -1085,20 +1453,45 @@ RULES
   An environment where \`stim web\` ran carries web, its Stim-owned Chrome:
 
   web  { browser, version, running, pid, supervisorPid, url, headless,
-         viewport, profile, cdpEndpoint }
+         viewport, profile, cdpEndpoint, targetId, page?, activity? }
 
   running        the browser supervisor and Chrome are both verified live;
-                 pid, supervisorPid and cdpEndpoint are null when false
+                 pid, supervisorPid, cdpEndpoint and targetId are null when
+                 false, and page and activity are absent
+  url            the page stim web opened; page.url is the document the page
+                 loaded last, and page.route the URL an in-app route change
+                 (history API or fragment) moved it to since
   cdpEndpoint    http://127.0.0.1:<port>, the reserved loopback DevTools
                  endpoint of that Chrome. Attach Playwright MCP
                  (--cdp-endpoint) or agent-browser (--cdp <port>) to it; it
                  reaches only the Stim profile, never your own browser
+  targetId       the DevTools target id of the owned page, the one Stim
+                 Desktop and the phone stream; other tabs are not the page
   profile        the Stim-owned user data directory under STIM_HOME
+  page           { url, state, error?, route? }: the page's latest load, from
+                 the newest page-load marker in web.ndjson; null before the
+                 first. route is absent until an in-app route change after
+                 that load
+                 "loading"  the document was requested; no load event yet
+                 "loaded"   the load event fired
+                 "failed"   the document failed (connection refused, HTTP
+                            error, certificate) or the page crashed; error
+                            is the log message
+  activity       like a device's activity below. driver.tool names a
+                 DevTools client connected to cdpEndpoint (agent-browser,
+                 agent-device, argent, playwright, puppeteer,
+                 chrome-devtools-mcp, or the executable's name); Stim's own
+                 connections (the browser supervisor, stim-server, Stim
+                 Desktop, the stim CLI) are not drivers. basis: cdp-client
+                 (one lsof of the DevTools port); agent-action (the newest
+                 agent input the browser supervisor recorded in web.ndjson)
+                 and page-log (the newest other
+                 web.ndjson record) for recency
 
   Each booted simulator and detected emulator in environments (and in
   slots) carries activity; a shut-down or physical device has none:
 
-  activity  { state, driver?, lastActivityAt?, basis }
+  activity  { state, driver?, lastActivityAt?, recent?, basis }
 
   state            "driven"   a live claim or driver holds the device now
                    "active"   no driver, but activity in the last 10 minutes
@@ -1106,25 +1499,46 @@ RULES
                    "unknown"  a claim or driver check could not be read;
                               never treated as idle
   driver           { tool, pid, since } for "driven": agent-device, stim device
-                   lock, xcodebuild, idb, maestro, appium, simctl,
+                   lock, argent, xcodebuild, idb, maestro, appium, simctl,
                    uiautomator or instrumentation; pid and since are null when
                    the claim does not record them
   lastActivityAt   the newest of this device's app log records, this
-                   platform's Metro bundle requests and the workspace's last
-                   Stim run, rounded down to the minute; absent when none is
+                   platform's Metro bundle requests, the workspace's last
+                   Stim run, while agent-device drives it the agent's last
+                   recorded action, and now while a stim-server client views
+                   it, rounded down to the minute; absent when none is
                    recorded
+  recent           the newest time of each kind of evidence behind
+                   lastActivityAt: agent-action, device-log, metro-bundle,
+                   workspace-use, supervisor-start, page-log or viewer, each
+                   rounded down to the minute. viewer is now while a
+                   stim-server client streams the device's frames
   basis            the evidence behind state, strongest first:
                    agent-device-claim, agent-device-lease  agent-device state,
                      read only; live only when every recorded process is alive
-                     with its recorded start time, so a reused pid is dead
+                     with its recorded start time, so a reused pid is dead.
+                     A runner lease that declares agent-device's device
+                     claims is never a driver: without a claim, the runner
+                     is one agent-device kept warm after close or handed
+                     off when its daemon exited
                    device-lock          an unexpired \`stim device lock\` lease
-                   driver-process       a host process naming the UDID or serial
-                   instrumentation      an on-device uiautomator or androidx.test
-                                        process (one adb shell ps per emulator)
-                   device-log, metro-bundle, workspace-use   recency
+                   driver-process       a host process naming the UDID or
+                                        serial, other than such a runner
+                   instrumentation      an on-device uiautomator, androidx.test or
+                                        argent helper process (one adb shell ps
+                                        per emulator)
+                   device-log, metro-bundle, workspace-use, agent-action,
+                   viewer               recency
 
   Plain \`stim status\` appends it to each device line: "driven by
   agent-device for 12m", "active", "idle 3h", or "activity unknown (...)".
+
+  An owned device that is not booted after its supervisor shut it down for
+  devices.idleShutdownMinutes carries idleShutdown, and plain \`status\`
+  appends "shut down after 30m idle at <at>" to its line; the next \`ios\` or
+  \`android\` run for that slot clears it (\`guide lifecycle budget\`):
+
+  idleShutdown  { at, idleMinutes }
   \`gc --idle <duration>\` shuts down owned devices idle that long
   (\`guide cleanup gc\`).
 
@@ -1143,6 +1557,16 @@ RULES
   app is absent when the device is not owned or no app id is known: the
   process was not checked.
 
+  Each ios and android device record, in every slot, also carries
+  appPresence, whether the device lacks the app:
+
+  appPresence  "none"    the device runs, its platform's latest run failed
+                         and builds carries the platform with no
+                         succeeded run
+               "closed"  the device runs and app.state is "stopped"
+               null      otherwise, including a device that is not running
+                         and a physical device
+
   This is current process state, read from one host ps (simulator apps are
   host processes) and the same adb shell ps as activity, so a status --watch
   refresh notices an exit within its 30-second fallback. It is not launch
@@ -1151,6 +1575,11 @@ RULES
   status appends "<id> running", "<id> not running" or "<id> process
   unknown" to the device line.
 
+  An environment's metro carries tunnel { provider, url } for a recorded
+  managed tunnel on its reserved port: ngrok, cloudflared or tailscale.
+  Plain status prints the provider and URL, with "tailnet-only" for tailscale.
+  This describes the record, not a reachability check (\`guide metro\`).
+
   An environment's metro carries idleStop { reason: "idle", at, idleMinutes }
   when its supervisor stopped the dev server for idleness and nothing serves
   the port since; plain \`status\` prints "stopped (idle)" (\`guide metro\`).
@@ -1163,12 +1592,32 @@ RULES
     { reason: "vanished", pid, startedAt }   the recorded supervisor is gone
                                              and recorded no cause
   (\`guide metro\`, WHY IT STOPPED).
+  When another process answers Metro on the port, metro carries
+  heldBy { pid, cwd }, cwd null when its directory could not be read.
+
+  metro also carries bundle, from the bundle requests Stim's middleware
+  records in the workspace's metro log: an app's, and Stim's own prefetch
+  before a launch. It is absent when the log's tail holds none.
+
+  bundle     { bundling, platform?, startedAt?, percent?, last? }
+  bundling   true while a request is in flight: Metro runs, and the request
+             started under the current dev server less than 10 minutes ago
+  platform   with bundling, the in-flight request's "ios" or "android";
+  startedAt  when it started
+  percent    0-100, only when Metro reported progress for that request,
+             which it does for clients that accept multipart responses
+  last       { platform, status, durationMs, finishedAt }: the newest
+             finished request, status "ok" or "failed", durationMs from the
+             request to the end of the response
 
   Each entry of environments also carries build: null, or the ios or android
   run that holds this workspace's native-run.lock:
 
   build   { platform, slot, state, phase, startedAt, phaseStartedAt,
-            outcome, expectedMs, expectedPhaseMs, basis }
+            outcome, outcomeKnown, cacheLookupOutcome?, expectedMs, expectedPhaseMs,
+            completedPhaseMs?, basis,
+            plannedPhases, missReason?, missProvisional?, detail?, placement,
+            waitingOn? }
 
   state            "running" while the run's own native-run claim is live;
                    "stale" when that claim was released or its process is
@@ -1176,30 +1625,102 @@ RULES
                    record; "unknown" when the claim set cannot be resolved.
                    Never treat a stale record as a build in progress.
   phase            prepare | cache-lookup | wait | prebuild | pods |
-                   compile | install | launch. prepare covers settings,
-                   Metro and the owned device; wait is waiting on another
-                   workspace's build of the same fingerprint; install
-                   includes waiting for the device to boot.
+                   compile | device | install | launch. prepare covers
+                   settings and Metro; wait is waiting on another
+                   workspace's build of the same fingerprint. Creating,
+                   adopting or booting the owned simulator or emulator
+                   before the cache lookup is prepare time. device starts
+                   once the app is ready and covers waiting for the
+                   device: its boot, adoption cleanup, or a physical
+                   device's lease and connection check. A boot that
+                   finishes during the build adds no device time. An
+                   --eas-profile run has no cache lookup, so its outcome
+                   stays the project's most recent one until install.
   startedAt        when the run started; phaseStartedAt when its phase did
-  outcome          "cold" once the run reached prebuild, pods or compile,
-                   "hit" once it reached install without them. Before
-                   that, the outcome of this project's most recent run.
+  outcome          "cold" after the local/provider lookups resolve a miss;
+                   "hit" after a cached artifact is ready to reuse, including
+                   a shared-build hit or a recheck after prebuild or pods.
+                   A later recheck can replace the first lookup's outcome.
+                   Before resolution, the outcome of this project's most
+                   recent run.
+  outcomeKnown     true once outcome is this run's own, false while it is
+                   the project's most recent one
+  cacheLookupOutcome  "hit" or "miss" once an actual cache lookup resolves;
+                   absent before resolution and on runs that skip lookup,
+                   such as --eas-profile
   expectedMs       the median duration of this project's last successful
                    runs with that outcome on that platform, or null with
-                   no history
+                   no history. The run estimates twice: when it starts,
+                   from every run with the project's most recent outcome,
+                   and once when outcomeKnown turns true. From then on only
+                   runs that created, adopted or cold-booted their device
+                   the way this run did count; a run that reuses a booted
+                   device also counts runs recorded before Stim tagged them
+                   until 3 tagged ones exist. Runs that finish meanwhile do
+                   not change the estimate.
   expectedPhaseMs  the median duration of this phase in those runs, or null
-  basis            how many runs the medians come from (at most 10)
+                   when none of them entered it
+  completedPhaseMs  milliseconds spent in each phase the run already left,
+                   summing repeated visits. The current visit is excluded;
+                   its phase appears only if visited earlier. Absent before
+                   any phase completes and on older Stim versions
+  basis            how many runs the expectedMs median comes from (at most
+                   10 per kind: device-setup runs keep their own 10)
+  plannedPhases    [{ phase, expectedMs }] in phase order: the phases at
+                   least half of those runs entered, each with its median
+                   in them; null with no such run. The current phase can be
+                   one it does not list, such as wait. Draw a progress bar
+                   from it rather than from builds, which holds only this
+                   workspace's runs and includes offloaded ones
+  missReason       once the run knows its cache lookup missed, why, in the
+                   shape of lastBuilds missReason below
+  missProvisional  true while missReason is the first lookup's miss and the
+                   run will prebuild or install pods and look the key up
+                   again, because those can change the fingerprint. A hit on
+                   that second lookup removes missReason and sets outcome to
+                   hit; otherwise missReason is replaced with the final one,
+                   whose rekeyedBy lists what changed the key, and
+                   missProvisional goes away before compile
+  detail           during compile, once the build tool printed a line Stim
+                   reads: { step, unit, done, total, line, updatedAt }
+    step           the tool's step: configure, compile, link, resources,
+                   script, dex, package or sign; null before one is known
+    unit           "targets" for xcodebuild, "tasks" for Gradle
+    done           xcodebuild: targets it finished (a target counts once
+                   xcodebuild touches or signs its product, so an
+                   incremental build can end below total); Gradle: tasks
+                   it reported so far
+    total          xcodebuild: targets in its dependency graph; Gradle: null,
+                   since its plain output gives no total
+    line           the latest compile, link or task line, paths shortened
+                   to file names, at most 160 characters
+    updatedAt      when the build last wrote it; the run writes it at most
+                   every 2 seconds
+  placement        where the build runs: "local", or while it is offloaded
+                   { host, phase, startedAt, phaseStartedAt }. host is the
+                   offload.machines entry; phase is the step there: sync,
+                   deps, prebuild, pods, build (xcodebuild or Gradle) or fetch;
+                   startedAt is when the offload started and phaseStartedAt
+                   when that step did. Meanwhile phase above follows it as
+                   prebuild, pods or compile.
+  waitingOn        while phase is "wait" and the holder is known: { path },
+                   the workspace whose build of the same artifact this run
+                   waits for; absent otherwise. The lock is machine-wide, so
+                   path is usually an entry of environments but can name a
+                   workspace that is not listed.
 
   Plain \`stim status\` prints the same as one line per workspace:
 
     build: ios compile, 1m10s elapsed -- about 3 min left (median of 4 cold runs)
+    build: ios compile on janics-mac-mini (build, 2m10s), 3m05s elapsed
 
   An environment with a recorded run also carries lastBuilds, each
   platform's most recent ios or android run, finished or failed:
 
   lastBuilds   { ios?, android? }, each { platform, status, cacheHit,
                cacheSkipped, durationMs, fingerprint, startedAt, finishedAt,
-               errorCode?, missReason?, diagnostics? }
+               errorCode?, missReason?, buildMachine?, builtOn?, offloadedTo?, offloadFallback?,
+               diagnostics? }
 
   status       "ok" or "failed"
   cacheHit     "local" or "remote" for an app from that cache tier; false
@@ -1220,10 +1741,43 @@ RULES
   diagnostics  only on a failed run whose compiler reported errors: up to
                5 { file, line, column, message }, null where the compiler
                gave no position.
+  cause        only on a failed run: { key, file, line }, the first
+               diagnostic with a file and a line, keyed "<file>:<line>",
+               else the errorCode (or "failed") with null file and line.
+               Failed runs in a row with the same key failed the same way.
+  Invalid, unlisted or unpaired selections refuse during setup, before cache
+  lookup, and create no lastBuild record or failed-run stats.
+  buildMachine selected auto, local or configured machine entry; always on new build records
+  builtOn      here or machine name; absent when no build ran (cache/refusal)
+  offloadedTo  only on a run a build machine compiled: its name
+  offloadFallback
+               only on a run that considered offloading and built here: one
+               reason per machine when none took the build, or why the
+               offload stopped
 
   Plain status prints "last build: ios local cache in 12s, android compiled
   in 7m02s". To predict the next run instead, see \`guide facts plan\`.
 
+  Swift Package development carries macos, separate from simulator devices:
+    product, bundle, bundleId, executable, launchId, arguments
+    app?, supervisor?   { pid, processToken, startedAtMicros }
+    state               running | orphaned | stopped | unverified
+    build               { state: running | ok | failed, startedAt,
+                          finishedAt?, durationMs?, error?,
+                          buildMachine?, builtOn?, errorCode?, offloadedTo?, offloadFallback? }
+    host?               { machine, session, appSlot, appAttempt, bundleId,
+                          agent } when stim macos --remote placed the app on
+                          another Mac; it then has no local app or supervisor
+    hostLaunched?       true when that host reported a live app, false when
+                          stopped, "unverified" when it could not confirm one
+  A live app without its supervisor is orphaned. An identity the system cannot
+  verify is unverified. For hosted placements only, status asks the host for
+  the session state with about a 3 s timeout per connection and request and
+  a 10 s cache. It reports stopped when the host says the session stopped,
+  for example after a stim-server restart there, and unverified when the
+  host is unreachable or cannot confirm. The placement stays recorded.
+  See stim guide macos for local capture, hosting and cleanup.
+
   An environment with a recorded run also carries builds, each platform's
   last 10 runs, newest first. Its newest entry that is not "interrupted" is
   the run lastBuilds reports, once a run has recorded builds.
@@ -1243,23 +1797,121 @@ RULES
   cacheKey       the cache key the run looked up or stored under
   phases         milliseconds spent in each phase the run entered, among
                  prepare, cache-lookup, wait, prebuild, pods, compile,
-                 install and launch
+                 device, install and launch; runs recorded before device
+                 existed count their device time in prepare and install
 
   Only runs that record a last build are listed: a run that stops before
   looking up a build, such as a bad flag, is not. Estimates (expectedMs) come from run statistics, not builds.
 
-  There is no completion fraction: a compile's log volume depends on what
-  is already built, so it does not measure progress.
-
-  An environment's memoryMb is an estimate, not a measurement: a fixed amount
-  per booted simulator, detected emulator, running Metro and running Chrome.
-  capacity.committedMb sums it, and the memory budget uses the same estimate.
-  What is using CPU and memory now is the top-level machine section:
-
-  machine   null, or { owners: [{ kind, name, workspace, slot?, id, owned,
-            cpuPercent, residentMb, processes }] }
-
-  kind         simulator  a booted simulator's launchd_sim tree
+  done and total are counts, not a completion fraction: a target or task
+  can take a second or ten minutes, and cached work finishes instantly.
+
+  Each environment also carries disk, and each owned simulator and owned
+  emulator in ios, android and slots carries disk, once \`status --watch\` has
+  measured them:
+
+  disk (environment)  { worktreeBytes, nodeModulesBytes, buildBytes,
+                      measuredAt }
+    worktreeBytes     the linked worktree, or else the checkout holding the
+                      workspace, node_modules included
+    nodeModulesBytes  node_modules at that root and at the workspace path;
+                      part of worktreeBytes
+    buildBytes        Stim's folder for the workspace: Xcode derived data,
+                      Gradle outputs and logs
+    measuredAt        the oldest of the three measurements; a figure not
+                      measured yet is null
+  disk (device)       { bytes, measuredAt }: the simulator's data folder
+                      under CoreSimulator/Devices, or the AVD's .avd folder
+
+  \`status --watch\` runs one du at a time off its refresh path, and measures
+  a folder at most every 5 minutes while its environment is live and every
+  hour otherwise. It caches each size under $STIM_HOME/disk-usage, which
+  one-shot status only reads, so the fields appear once a watcher, such as
+  stim-server or Stim Desktop, has measured.
+
+  An environment carries agents when coding-agent sessions work in it, most
+  recently active first:
+
+  agents        [{ tool, sessionId, title?, cwd, startedAt?, lastActiveAt?,
+                pid?, openUrl?, webUrl? }]
+    tool        claude-code | codex
+    title       the short name the tool keeps for the session; never a
+                prompt or any conversation content
+    cwd         the session's working directory, canonical
+    lastActiveAt the tool's last update of the session, or the last Stim
+                command the session ran here when that is newer
+    openUrl     opens the session in the Claude desktop app
+                (claude://code/continue) or the Codex app
+                (codex://threads/<id>) when that app is installed on the
+                Mac; absent for a Claude Code session started in a terminal
+    webUrl      https://claude.ai/code/<id> for a Claude Code session with
+                Remote Control connected; it opens the session in a browser
+                or the Claude mobile app
+
+  A session works in an environment when its cwd is the environment's
+  path or inside it (the deepest environment wins), or is the environment's
+  git worktree root. \`status --watch\` looks for sessions at most every 15
+  seconds: Claude Code sessions in ~/.claude/sessions whose process runs,
+  and Codex threads in $CODEX_HOME (~/.codex) updated in the last 30
+  minutes. It caches them in $STIM_HOME/agent-sessions.json, which one-shot
+  status reads and ignores once it is 2 minutes old. Both sources are other
+  tools' internal files; a missing or changed one only drops its sessions.
+  \`start\`, \`ios\`, \`android\`, \`web\`, \`reload\` and \`worktree warm\`
+  also record the CLAUDE_CODE_SESSION_ID or CODEX_THREAD_ID of the shell
+  that ran them, so that session is listed for 30 minutes after the command
+  even when status cannot see it, and for as long as it runs.
+
+  When a watcher stops finding a session it found on its previous look, it
+  records the session in each environment it worked in, under
+  $STIM_HOME/workspaces/<id>/ended-agents.json, for 3 days:
+
+  endedAgents   [{ tool, sessionId, title?, cwd, startedAt?, lastActiveAt?,
+                openUrl?, webUrl?, endedAt }], most recently ended first
+    endedAt     the last time a watcher found the session running; a Codex
+                thread ends 30 minutes after its last update
+
+  The other fields are as the watcher last found them. A session that runs
+  again is listed in agents only.
+
+  memorySource says how a memory figure was obtained:
+
+  footprint  physical footprint, the figure Activity Monitor's Memory
+             column shows, read by a small helper Stim compiles with the
+             Xcode command line tools into $STIM_HOME/helpers on first use
+  rss        summed resident set size, for machine owners when the helper
+             cannot be built (no Xcode command line tools, Linux). It
+             overstates a simulator many times over.
+  estimate   a fixed amount per booted simulator, detected emulator,
+             running Metro and running Chrome
+
+  An environment's memoryMb is what its own processes use now, the sum of
+  memoryMb over the machine owners whose workspace is that environment,
+  builds included, when machine.memorySource is footprint. Otherwise it is
+  the estimate, with memorySource estimate.
+
+  capacity.committedMb sums memoryMb. The memory budget plans before a boot
+  and always uses the estimate. What is using CPU and memory now is the
+  top-level machine section:
+
+  maintenance { mode, lastChecks: { pressure, size }, pressure, sizes,
+                lastPass, running, recent, plan, invalid?, claim? }
+    Report-only observations; every plan action's kind starts with would-.
+    lastChecks are epoch milliseconds or null. running comes only from a
+    live maintenance/run.claims owner, never from a check stamp.
+    lastPass carries startedAt, durationMs, trigger, mode, freedBytes (0),
+    actions, stopped (0), blocked. recent holds the last 20 action, failure
+    and blocked NDJSON records from maintenance/maintenance.ndjson.
+    invalid names invalid settings; invalid cache caps use their defaults,
+    while invalid maintenance settings disable passes. claim contains an
+    unresolved claim's path and reason, plus removeCommand from the claim
+    protocol; inspect the holder before running that command.
+
+  machine   null, or { memorySource, owners: [{ kind, name, workspace,
+            slot?, id, owned, cpuPercent, residentMb, memoryMb,
+            processes }] }
+
+  kind         macos      the owned Swift Package app and supervisor
+               simulator  a booted simulator's launchd_sim tree
                emulator   an emulator's launcher and qemu tree, by its -avd
                metro      a workspace's supervisor and Metro trees
                build      a running ios or android run's process tree,
@@ -1281,14 +1933,19 @@ RULES
   residentMb   summed resident set size. Pages shared between processes
                count once per process, so a simulator reports well above
                its physical footprint.
+  memoryMb     summed physical footprint when machine.memorySource is
+               footprint; a process the helper cannot read, another user's
+               or one that just exited, counts its resident size. Equals
+               residentMb when memorySource is rss.
 
   Each process counts in exactly one owner, the one whose root process is
   its nearest ancestor, so the supervisor a build started counts as Metro,
   not as the build, and a Gradle or Kotlin daemon counts in the build that
   started it until that build exits, then as shared. Processes with no owner
   are left out. machine comes from one host ps, the one status reads for
-  device activity, and is null when no simulator is booted, no workspace is
-  live and no build runs: status then reads no process table. \`status --watch --json\` rereads it every 15 seconds while
+  device activity, and one run of the footprint helper. It is null when no
+  simulator is booted, no workspace is live and no build runs: status then
+  runs neither. \`status --watch --json\` rereads both every 15 seconds while
   machine is not null, with no other subprocess.`
 			},
 			plan: {
@@ -1311,7 +1968,9 @@ RULES
   outcome       "hit" or "cold"; null when the run would refuse
   expectedMs    the median wall time of this project's last successful runs
                 with that outcome on that platform, or null with none
-  basis         how many runs expectedMs comes from (at most 10)
+  basis         how many runs expectedMs comes from (at most 20: runs that
+                set up their device and runs that did not are not told apart
+                before the run)
   missReason    on a predicted cold build with cache reads on, why the
                 cache has no app, in the shape of lastBuilds.<platform>
                 .missReason (\`guide facts status\`), compared with the same
@@ -1338,14 +1997,61 @@ RULES
   { "version": 1,
     "project": { "key": "<path>", "ios": <bucket|null>,
                  "android": <bucket|null> } | null,
-    "machine": { "ios": <bucket|null>, "android": <bucket|null> } }
+    "machine": { "ios": <bucket|null>, "android": <bucket|null> },
+    "offload": { "today": { "here", "offloaded", "fellBack" },
+                 "machines": { "<machine>": { "today": <day>,
+                                              "total": <totals> } },
+                 "placements": [<placement>, ...] },
+    "agentDevice": <AgentDeviceUsage|null>,
+    "swiftpmCache": <SwiftpmCacheUsage|null> }
 
   \`project\` is null outside a project; a platform with no run yet is null.
   A bucket carries runs, failed, hits, misses, coldRuns, coldRunMs, hitRuns,
   hitRunMs, timeSavedMs, firstRunAt and lastRunAt, plus lastColdBuildMs and
-  lastPodsMs once the project has compiled or installed pods. Milliseconds are
+  lastPodsMs once the project has compiled or installed pods, and
+  offloadedRuns, offloadedRunMs and lastOffloadHost once a build machine
+  compiled one. An offloaded run is a miss but not a cold run, so the cold
+  average, time saved and build estimates stay local. Milliseconds are
   integers.
 
+AGENT-DEVICE DISK USAGE
+  agentDevice: { version: 1, measuredAt, bytes, complete, stateDir,
+                 runnerBuilds, workspaces, hosted }
+  bytes sums known state, separate runner builds, workspace and hosted bytes;
+  complete is false when a measurement fails. Individual unknown byte fields
+  are null. Absent directories have zero bytes and present: false.
+  stateDir defaults to ~/.agent-device. AGENT_DEVICE_STATE_DIR overrides it
+  only when it does not overlap a workspace agent-device dir or the hosted dir.
+  stateDir: { dir, present, bytes, sessions: { dir, bytes, count },
+              logs: { dir, bytes }, other: { bytes, largest: [{ name, bytes }] } }
+  runnerBuilds: { dir, present, bytes, sharedBytes, platforms: [
+    { platform, dir, bytes, entries: [{ name, dir, bytes, lastUsedAt,
+      packageVersion, xcodeBuildVersion, inUse, inUseReason }] }] }
+  inUseReason is lease, lock, unreadable or null. Lease means a live owner or
+  runner matched by start time; lock means a live or unknown lock owner.
+  Unreadable lock owners and unreadable or unknown leases use unreadable.
+  Dead lock owners and leases do not mark entries in use.
+  workspaces: [{ dir, projectRoot, bytes }]; hosted: { dir, bytes, sessions } | null.
+  $STIM_HOME/agent-device-usage.json caches the measurement and resolved roots
+  for 10 minutes. stats and unscoped gc measure; no other command measures this
+  state. Server stats.get reads only the cached value.
+  Stim never trims or deletes the shared runner builds, sessions, logs and other
+  state or the hosted driver dir; a workspace's own agent-device dir goes only with its workspace.
+
+SWIFTPM CACHE DISK USAGE
+  swiftpmCache: { version: 1, measuredAt, dir, present, bytes, complete } | null.
+  The user-level cache is ~/Library/Caches/org.swift.swiftpm on macOS and
+  org.swift.swiftpm under XDG_CACHE_HOME (default ~/.cache) elsewhere.
+  It is shared by every SwiftPM build on the machine; Stim never deletes it.
+  bytes is null and complete is false if du fails; absent directories have
+  present: false, bytes: 0 and complete: true. Plain output omits absent caches.
+  $STIM_HOME/swiftpm-cache-usage.json caches the measurement for 10 minutes,
+  keyed on the resolved dir. stats and unscoped gc alone run du -sk with a
+  20-second timeout. Server stats.get reads only the cached value. status,
+  start, ios, android and the budget gate never measure it. gc reports it as
+  sections.swiftpmCache, never in caches or actionable; --delete and
+  --older-than leave it untouched, and any --cache scope reports null.
+
 HOW A RUN IS COUNTED (\`stats\`)
   Every \`ios\` or \`android\` invocation that got as far as computing a
   cache key is one run, in this project's bucket and in the machine-wide one.
@@ -1365,7 +2071,8 @@ HOW A RUN IS COUNTED (\`stats\`)
   is therefore an ESTIMATE and is printed as one. The file is
   $STIM_HOME/stats.json (see \`guide lifecycle builds\`). Beside the
   aggregates it keeps the last 10 successful runs per project, platform and
-  outcome (hit or cold) that did not wait for another workspace's build: each
+  outcome (hit or cold), plus the last 10 that created, adopted or cold-booted
+  their device, that did not wait for another workspace's build: each
   one's duration and per-phase durations. \`stim status\` estimates a running
   build from them (see \`guide facts status\`); \`stats --json\` does not
   print them.
@@ -1386,7 +2093,30 @@ HOW A RUN IS COUNTED (\`stats\`)
   a hang. A project with no record yet gets \`(1m00s)\`, the elapsed alone,
   and a warm run has no long phase to size. That read takes no lock and
   ignores what it cannot read, so nothing about statistics can change a
-  run's outcome.`
+  run's outcome.
+
+BUILD PLACEMENT (\`offload\`)
+  Every run that compiles records where it built and why, in a placement: { at, project, platform,
+  decision, reason, machine?, buildMs?, slotWaitMs?, localEstimateMs?, failed? }.
+  slotWaitMs is whole milliseconds waiting for a build slot, present only when positive.
+  decision is "here", "offloaded", or "fell-back" (it tried a build machine
+  and built here). reason is why: the run's \`placement:\` reason, such as
+  "load 0.6/core, 1 of 3 build slots busy here" (auto keeps the build here
+  while this Mac has room) or "offload.mode is off" (which prints no line),
+  or for a fallback the cause, prefixed by the machine it concerns, such as
+  "mini: no less loaded (load 1.2/core there, 0.6/core here)". buildMs is the compile here, or the offloaded build's
+  total (offer, sync, build and fetch); localEstimateMs is this project's
+  last cold build here before the run. A run that hits the cache or waits
+  for another workspace's build compiles nothing and records none.
+  placements lists them newest first: the last 100 from the last 7 days.
+  Per machine, \`total\` keeps { offloaded, offloadedMs, savedMs, fallbacks,
+  lastOffloadAt?, lastFallbackAt? } for good and \`today\` counts { offloaded,
+  offloadedMs, savedMs, fallbacks } from the placements on this Mac's local
+  calendar day. savedMs sums localEstimateMs minus buildMs over offloaded
+  builds that had an estimate, so it is an ESTIMATE and is negative when the
+  machine was slower. \`offload.today\` counts the day's placements by
+  decision. A fallback counts against a machine only when the run knows
+  which one: the machine that failed, or the only one paired.`
 			}
 		}
 	},
@@ -1410,10 +2140,49 @@ another worktree's bundler.
                     --wait, it does not wait for a device lease.
   --remote          expose Metro for a remote device
 
-Plain \`stim start\` is local and does not create a public tunnel. Remote intent
-comes from \`start --remote\`, \`ios.remote\`, or \`android.remote\`. The
+Plain \`stim start\` is local and does not create a tunnel. Remote intent
+comes from \`start --remote\`, eas/proxy in \`ios.remote\`, or \`android.remote\`. The
 \`metro.tunnel\` setting selects the provider after remote intent exists.
 
+HOSTED IOS METRO
+  ios --remote <machine> keeps Metro local and needs no start --remote.
+  The supervisor watches private gateway requests in workspace state, binds
+  only this Mac's Tailscale address and accepts only the pinned hosting peer
+  with a per-session secret. The host's bridge is loopback-only. Port and secret
+  stay in 0600 workspace state and never appear in status, JSON or logs.
+  metro.tunnel and metro.publicUrl are ignored. Supervisor restart recreates
+  the recorded gateway; stop or a stopped hosted session closes it. A recorded
+  hosted session prevents Metro idle stop. Release runs skip the bridge.
+  Hosted Debug runs require the supervisor's private gateway support before
+  reservation. --no-metro-check refuses; restart a missing or older supervisor
+  with stim stop; stim start.
+  Native iOS logs are pulled from the host by stim logs, including --errors;
+  JavaScript logs still arrive through Metro. Stop pulls native logs before
+  deleting the simulator. Read guide lifecycle hosted-ios for placement and cleanup.
+
+TAILNET-ONLY METRO
+  Install Tailscale and sign in on this machine and the remote device or
+  agent-device daemon's host, then select the mode explicitly:
+
+    stim settings set metro.tunnel tailscale --scope workspace
+    stim start --remote
+
+  The device must be on the same tailnet, so the eas backend refuses it. "auto"
+  never selects tailscale.
+  Stim runs a foreground \`tailscale serve --https=<metro port>
+  http://127.0.0.1:<metro port>\` process, never Funnel. It prints
+  https://<tailnet-name>:<metro port> and \`status\` reports the recorded
+  provider and URL. Stim reads the URL from the child's pipes, without a log
+  file, and skips the public bundle probe for this recorded tunnel: this
+  machine may not reach its own tailnet name.
+
+  \`stop\` and \`worktree remove\` stop only the recorded process after
+  verifying its identity; ending that foreground session removes its route.
+  A route Stim did not create is never touched. If the port already has a
+  serve route, Tailscale refuses and Stim prints Tailscale's error message.
+  \`tailscale serve status --json\` shows foreground sessions under the
+  top-level Foreground key; plain \`tailscale serve status\` does not.
+
 BUNDLE WARMUP
   After verifying Metro, \`stim ios\` and \`stim android\` prefetch the
   platform's development bundle while native work continues. Expo supplies the
@@ -1441,7 +2210,7 @@ BUNDLE WARMUP
 REMOTE DEVICE BACKENDS
   Metro exposure and device selection are separate:
 
-    stim start --remote          prepare public Metro
+    stim start --remote          prepare remote Metro
     stim ios --remote proxy      use an agent-device daemon
     stim android --remote eas    create an EAS Simulator session
 
@@ -1452,6 +2221,12 @@ REMOTE DEVICE BACKENDS
   requires AGENT_DEVICE_DAEMON_BASE_URL and
   AGENT_DEVICE_DAEMON_AUTH_TOKEN. Stim creates no remote session for it.
 
+  An iOS remote build compiles one simulator architecture, since xcodebuild
+  cannot target the remote simulator itself: the proxy daemon's host
+  architecture from its /health hostArch, and arm64 when the daemon does not
+  report one, cannot be reached within 3 seconds, or runs on EAS, whose hosts
+  are Apple silicon. The cache key ends in that architecture.
+
   The EAS backend needs eas-cli 21.6.0 or later and an account with EAS
   Simulator access. An EAS session is billable. Stim prepares the app before
   it creates or reconnects the session, so a failed build starts no session
@@ -1466,7 +2241,17 @@ IDEMPOTENT
   A healthy dev server on the reserved port is a no-op: \`start\` prints the
   facts with alreadyRunning: true and starts nothing. A foreign process holding
   the reserved port moves the RESERVATION instead, so the project is never
-  stranded on a port it can never use.
+  stranded on a port it can never use. A port pinned with metro.port or
+  STIM_METRO_PORT never moves: \`start\` refuses with STIM_BAD_ARG and names
+  the holder before anything starts or the pin is reserved. This project's
+  own Metro already on the pin is attached to. Changing the pin while this
+  workspace's dev server runs refuses until stim stop; a supervisor that cannot
+  be verified also refuses, until you stop it with the tool that started it.
+  You can also unset or restore the pin. stim web follows
+  the same rules when its page uses Metro.
+  ios and android with --no-metro-check use the pin, then the recorded port,
+  then 8081, without probing, reserving or writing the registry. An invalid
+  pin still refuses with STIM_BAD_ARG. Release builds still skip Metro.
 
 WHAT THE SUPERVISOR IS
   One detached process per workspace. There is no machine-wide daemon, nothing
@@ -1517,7 +2302,10 @@ WHAT THE SUPERVISOR IS
   connected app alone does not keep the server. It records a
   supervisor_idle_stopped line in metro.ndjson and devServerStop in
   state.json, so \`status\` shows "stopped (idle)" rather than a crash.
-  Devices stay booted. The next \`stim start\` starts it again and clears the
+  Devices stay booted, unless devices.idleShutdownMinutes is set: then the
+  idle stop first shuts down the workspace's owned devices idle for the
+  shorter of the two (\`guide lifecycle budget\`). The next \`stim start\`
+  starts it again and clears the
   record, also when it reuses a dev server that another process started. A
   Debug \`ios\` or \`android\` run starts it the same way and reports
   devServer.reason "stopped (idle)". The setting
@@ -1547,6 +2335,23 @@ WHAT THE SUPERVISOR IS
   supervisor logs supervisor_vanished (level warn) for it, and until then
   \`status\` reports metro.lastStop.reason "vanished".
 
+  WATCHMAN ROOTS: a Metro that uses watchman registers a watch root in the
+  shared watchman daemon and never removes it. Bare React Native Metro uses
+  watchman whenever it is installed; Expo SDK 56 and later use it only when
+  metro.config.js sets resolver.useWatchman to true. When the supervisor stops
+  its dev server, it removes with \`watchman watch-del\` a root that appeared
+  after it started, contains the workspace and carried this Metro's
+  subscription, once no other client subscribes to it or has a trigger on it.
+  It logs watchman_root_removed, or watchman_root_kept with the reason, in
+  metro.ndjson. It never starts the daemon and leaves every other root alone,
+  including those jest registers.
+  A supervisor that dies without stopping leaves its root: remove it with
+  \`watchman watch-del <root>\`. Removing a root stops its recrawls; the
+  daemon's memory footprint shrinks only when the daemon restarts, which drops
+  the watches of every other client. \`stim gc --cache watchman\` reports the
+  daemon's footprint, roots and clients, and with --delete shuts it down only
+  when no client is connected (\`guide cleanup memory\`).
+
   ENVIRONMENT: the supervisor -- and through it the dev server, including a
   metro.config.js evaluated inside the expo child -- inherits the environment
   of the \`start\` call that SPAWNED it. A later \`start\` that finds a healthy
@@ -1607,7 +2412,14 @@ If Stim is not installed globally, replace stim with npx stim.
 get <label> allocates on first use and prints only the number to stdout.
 Repeated calls reuse it, even while a server is listening. Labels start with
 a letter and contain up to 64 letters, digits, underscores, or hyphens.
-metro is reserved; use stim start and stim stop for managed Metro.
+metro is reserved; use stim start and stim stop for managed Metro, and
+metro.port or STIM_METRO_PORT to choose its number (guide settings).
+Changing the pin while this workspace's dev server runs refuses until
+stim stop; an unverified supervisor also blocks the change until you stop it with the tool that started it. A foreign holder
+of the pin is refused before anything starts; this project's own Metro on
+it is attached to. stim web follows these rules when its page uses Metro.
+ios and android with --no-metro-check use the pin, then the recorded port,
+then 8081, without probing or reserving; an invalid pin still refuses.
 
 New allocations scan TCP ports 8900-8999. They skip registry reservations
 and existing listeners, announcing occupied ports and upward retries on
@@ -1659,6 +2471,34 @@ instead of allocating a separate label in every worktree.`
 		summary: "Querying the merged NDJSON timeline, and what --errors means",
 		body: () => `LOGS
 
+If Stim is not installed globally, replace stim with npx stim.
+
+AGENT-DEVICE WORKSPACE STATE
+
+When you drive a device yourself with agent-device, opt in to the workspace's
+state directory reported as agentDevice.stateDir in the stim ios, android and
+macos output and in status. Read it once from status, run from the app root:
+
+  STATE_DIR="$(stim status --json | jq -r '.environments[] | select(.path=="'"$(pwd -P)"'") | .agentDevice.stateDir')"
+
+Then prefix each agent-device command, so the choice survives shells that do
+not keep exports:
+
+  AGENT_DEVICE_STATE_DIR="$STATE_DIR" agent-device open <bundle id> --platform ios --session <name>
+  AGENT_DEVICE_STATE_DIR="$STATE_DIR" agent-device snapshot --session <name>
+
+The path is $STIM_HOME/workspaces/<name>/agent-device. agent-device creates it
+itself. Sessions (including events, runner logs and request text), logs,
+metro-sessions, allocations and daemon files move there. The apple-runner build
+cache and device claims stay shared; do not set
+AGENT_DEVICE_IOS_RUNNER_DERIVED_PATH or AGENT_DEVICE_CLAIMS_DIR.
+Each active workspace adds one agent-device daemon, which exits after five
+idle minutes with no open session. The variable is opt-in per command: forgetting it falls back to
+~/.agent-device.
+stim stop closes owned-device sessions there, stim logs --source agent reads
+them, and stim worktree remove stops the daemon and removes the directory.
+Hosted/stim-server sessions use their own state directory and need none of this.
+
   stim logs [filters]
 
 Reads every *.ndjson file in the global workspace logs directory, merges them into one timeline
@@ -1688,11 +2528,16 @@ The only exit-1 paths are a malformed query and no project.
 Device collectors and build records carry their named slot. Use --slot phone
 for that slot's timeline; its launch marker cannot hide a sibling's errors.
 Untagged legacy records belong to default. Metro/client records are shared and
-usually untagged: use an unfiltered workspace query to inspect those errors.
+usually untagged, so every --slot query includes them, windowed by that slot's
+own launch and by bundles of the platforms it launched. When another slot's
+relaunch hides a Metro error from the unfiltered query, --slot <name> for the
+slot that printed it still shows it.
 
 FLAGS
-  --slot <name>   only this slot's records (default includes untagged records)
-  --source <s...>  metro, client, device, build, agent (one or more), or all.
+  --slot <name>   only this slot's records plus, once it has launched, the
+                  shared untagged Metro and app client records (not the web
+                  page's); default also includes untagged legacy records
+  --source <s...>  metro, client, device, build, agent, maintenance (one or more), or all.
                    An unknown value is REJECTED rather than quietly matching
                    nothing.
   --level <l>      minimum level: debug, info, warn, error, fatal
@@ -1705,7 +2550,12 @@ FLAGS
                    owned Chrome's device errors (platform web: failed
                    requests, browser errors).
                    Capped at 20 printed records.
-  --follow         keep streaming until interrupted (Ctrl+C is exit 0)
+  --follow         keep streaming until interrupted (Ctrl+C is exit 0). Closing
+                   its stdout also ends it with exit 0; on Linux, so does the
+                   exit of the process that started it when stdout is a pipe.
+                   It notices within a few seconds even when nothing new
+                   arrives, except a closed stdout pipe on Linux whose starter
+                   is still running, which it notices at the next record.
   --json           the raw records, one per line, so stdout is valid NDJSON.
                    ZERO matches is ZERO bytes on stdout (an empty NDJSON
                    stream), exit 0 -- parse stdout line by line, never as one
@@ -1755,9 +2605,19 @@ FLAGS
       errors are reported -- and nothing else. A failed attempt's own summary
       and details land at or after its marker, so they stay reported.
     a LAUNCH marker (src build, written before \`ios\` / \`android\` attempts
-      launch) resets EVERYTHING except the web page's records. It precedes the
-      tool call so an immediate native crash is not hidden by a marker written
-      after the process died.
+      launch) resets EVERYTHING in its slot except the web page's records. It
+      precedes the tool call so an immediate native crash is not hidden by a
+      marker written after the process died. Metro and client output names no
+      device, so in the unfiltered query the newest launch of any slot resets
+      it, and the newest bundle of any platform resets Metro errors; with
+      --slot <name>, that slot's newest launch and the newest bundle of a
+      platform it launched do. Metro records that name their platform (bare
+      React Native bundle records; the "iOS Bundled" / "Android Bundled" /
+      "RSC(iOS) Bundled" tag Expo prints for bundle markers, so a "DOM
+      Bundled" line does not close a native slot's window) follow only that
+      platform, and a slot query leaves out iOS or Android ones when it never
+      launched that platform. A single slot that runs both iOS and Android still shares one
+      window for untagged Metro errors.
     a PAGE-LOAD marker (the web_navigation record \`stim web\` writes for each
       load of the page's top-level document) resets only the page's records,
       those with platform web. It is written when the load starts, so a
@@ -1800,9 +2660,12 @@ FLAGS
   In --follow mode the marker window is dropped -- every error arriving from
   then on is by definition after the last marker seen.
 
-  \`stim status\` reports the same count per workspace, as
-  logs.errorsSinceMarker: the same query, the same scope, so the two can never
-  disagree about whether this workspace is failing.
+  \`stim status\` reports the errors of the same query and scope per
+  workspace, as logs.errorsSinceMarker, so the two never disagree about
+  whether this workspace is failing. It counts failures as the Stim Desktop and
+  phone logs list them: a Metro bundle failure is one error, although it is a
+  marker line, the error line and a failed bundle response in the log, so the
+  count can be lower than the records this command prints.
 
 THE RECORD
   { ts, src, level, msg } always. ts is epoch milliseconds; src is one of
@@ -1822,7 +2685,14 @@ THE RECORD
              there are none. Stim adds it at query time; it is not in the
              log files.
 
+Maintenance records use src: maintenance and appear in the plain timeline.
+  stim logs --source maintenance
+Add --errors to --source maintenance to show only maintenance_failure events;
+failures before a later launch marker are hidden. Machine passes are reported in
+status and maintenance/maintenance.ndjson; this command reads workspace logs.
+
 WHAT WRITES WHAT
+  maintenance.ndjson   workspace maintenance actions, failures and explaining skips
   metro.ndjson         the bundler, in both supervisor modes
   client.ndjson        in-app console logs and redboxes -- BARE PROJECTS ONLY.
                        In expo-child mode everything Expo prints lands in
@@ -1960,13 +2830,18 @@ WHAT WRITES WHAT
   archive rather than a stream. Streaming with full fidelity needs
   libimobiledevice or pymobiledevice3, which are third-party installs Stim
   does not require. See appandflow/stim#179.
-  agent                no file. Each query reads agent-device's session
-                       records (~/.agent-device/sessions, or
-                       AGENT_DEVICE_STATE_DIR) for this workspace's owned
+  agent                agent input on the owned Chrome page is in
+                       web.ndjson (\`guide web\`). For simulators and
+                       emulators, no file: each query reads agent-device's
+                       session records (~/.agent-device/sessions, or
+                       AGENT_DEVICE_STATE_DIR, plus existing workspace
+                       agent-device directories) for this workspace's owned
                        simulators and emulators, read-only. An action is
                        info (msg is agent-device's summary, e.g. "Tapped
                        (201, 731)"; event agent_action with command, session,
-                       deviceId and details); a failed command is error
+                       deviceId and details, and startedAt when agent-device
+                       logged the command's start: ts is when it finished,
+                       after any --settle wait); a failed command is error
                        (event agent_failed). A plain query includes them;
                        --errors only with --source agent or all. iOS sessions
                        match a simulator through their runner.log, Android
@@ -1997,6 +2872,23 @@ WHAT WRITES WHAT
 Every refusal listed here carries a stable CODE, whichever command prints it.
 Branch on the code, never on the message.`,
 		sections: {
+			STIM_HOSTING_REFUSED: {
+				summary: "a named hosting Mac refused or could not confirm its iOS session; no local fallback",
+				body: () => `STIM_HOSTING_REFUSED
+  The message names the hosting Mac and its reason: unreachable or changed
+  tailnet node, no installed simulator choice, no capacity, elevated or unknown
+  memory pressure, or an unresolved reservation or delivery. Stim boots nothing
+  locally and never tries another Mac. Check stim-server and Tailscale there,
+  then run stim doctor. Correct --device-type / --runtime when the offer names
+  an unavailable choice. A session that exists stays recorded even if delivery
+  fails: retry stim ios --remote <machine>, or run stim stop to reconcile it.
+  An unreachable stop keeps the placement; rerun stim stop when the host answers.
+  A failed build handoff uses upload instead. If native log queries are unavailable,
+  logs prints a note on stderr and shows copied records. Update an older stim-server
+  on the host to enable iOS handoff and native logs (hello feature hosted-ios-data).
+  A name outside hosting.machines is STIM_BAD_ARG. Missing or pending hosting
+  approval keeps the doctor --fix and stim-server devices grant remedies.`
+			},
 			STIM_EAS_BUILD_MISSING: {
 				summary: "no completed EAS development build matches; build only with session authorization",
 				separator: "--- EAS BUILD CODES (`ios --eas-profile` / `android --eas-profile`) ---",
@@ -2163,8 +3055,12 @@ Branch on the code, never on the message.`,
   On a release cache hit Stim regenerates this workspace's JS bundle into a
   COPY of the cached artifact before installing it -- \`ios --configuration
   Release\` into a copy of the .app, \`android --variant ...Release\` into a
-  copy of the APK. When any step of that swap fails (the bundle command,
-  hermesc, the re-sign, zipalign, apksigner), the run does NOT install the
+  copy of the APK. An iOS app that sets React Native's RCTUseAssetCatalog
+  Info.plist key also gets its RNAssets.bundle image catalog recompiled with
+  actool from the new bundle. When any step of that swap fails (reading the
+  app's Info.plist, the bundle command, hermesc, actool, the expo-updates
+  manifest refresh, the re-sign, zipalign, apksigner), the run does NOT
+  install the
   cached artifact -- its baked-in JS is the builder's, not yours -- and does
   NOT fail: it prints a \`swap        failed at <step>: ... --
   building fresh instead\` note on stderr and falls back to a full build. If
@@ -2278,6 +3174,39 @@ Branch on the code, never on the message.`,
   Legacy inline \`deletionClaim\` fields in config.json have no process
   identity and require separate manual inspection; \`stim guide lifecycle pool\`
   describes their field-only recovery.`
+			},
+			STIM_MACOS_OWNER_UNVERIFIED: {
+				summary: "the macOS app owner cannot be verified; no signal is sent",
+				body: () => `STIM_MACOS_OWNER_UNVERIFIED
+  The recorded macOS process identity is unavailable or its workspace record
+  is malformed. Stim sends no signal to an owner it cannot verify. Inspect the
+  named process and workspace record before repairing it; do not replace a PID
+  or token with another running app. Retry stim stop once identity inspection
+  works. See stim guide macos.`
+			},
+			STIM_OFFLOAD_REFUSED: {
+				summary: "the selected build machine cannot build this app",
+				body: () => `STIM_OFFLOAD_REFUSED
+
+A named --build-machine selection is strict. The message names the machine
+and why it cannot take or finish the build: not configured or paired, approval
+pending or denied, unreachable or changed pinned identity, incompatible
+toolchain/runtime/CPU, low disk, busy, sync/build failure, artifact failure,
+or a checkout that changed while it built. Unsupported build kinds also refuse.
+No local xcodebuild, Gradle or SwiftPM compile or alternate machine follows a
+refusal. Prebuild and pod install still run on this Mac before a named offload.
+Unlisted or unpaired names refuse at setup before consulting the cache, without
+a build record or failed-run stats. A listed paired name with a cache hit needs
+no build and does not contact the selected machine.
+
+Run stim doctor --fix to ask for build access if not paired. Check
+stim settings get offload.machines. A person on the worker finds the id with
+stim-server devices and approves this Mac with stim-server devices grant <id> --build,
+or runs stim-server setup on the worker with its node, ticket and expiry
+(guide settings). Agents never run setup or approve requests.
+Rerun with --build-machine auto for normal placement and local fallback, or
+--build-machine local to keep the build here.
+`
 			},
 			STIM_CLAIM_UNAVAILABLE: {
 				summary: "a process identity or warm claim store is unavailable, so the protected operation refuses",
@@ -2755,6 +3684,18 @@ so a Debug run on one is wired to a LAN origin instead of localhost.`,
   holds one remote session, and Stim will not end the recorded one to make
   room -- it may be mid-run for whoever started it. Run \`stim stop\` for this
   workspace, then re-run with the platform you want. Nothing was created here.`
+			},
+			STIM_REMOTE_DEVICE_MISMATCH: {
+				summary: "the recorded EAS session runs another model than --device-type asks for; stop, then rerun",
+				body: () => `STIM_REMOTE_DEVICE_MISMATCH
+  \`stim ios --remote eas --device-type <name>\` found this workspace's
+  recorded EAS Simulator session still running another model, or the model
+  EAS chose when no --device-type was given. EAS cannot change a running
+  session's model, and Stim will not end the recorded session to make room --
+  it may be mid-run for whoever started it. Run \`stim stop\` for this
+  workspace, then rerun with the model you want. A recorded session that has
+  already ended is replaced on the requested model instead, and without
+  --device-type a live one is reused as it is. Nothing was created here.`
 			},
 			STIM_REMOTE_SESSION_STATE: {
 				summary: "the EAS session was created but its state could not be recorded, so Stim stopped it",
@@ -2784,6 +3725,7 @@ so a Debug run on one is wired to a LAN origin instead of localhost.`,
   The gate that proves a tunnel still reaches THIS workspace's Metro failed --
   before a session or a build, whether the tunnel is Expo's own, one Stim
   started (metro.tunnel: cloudflared/ngrok/auto), or a named metro.publicUrl.
+  A recorded tailscale tunnel skips this public probe (\`guide metro\`).
   The usual cause: the tunnel was built for a port this workspace no longer
   holds (a stale one survived a \`stop\`/\`start\` that reserved a different
   port), and it now serves ANOTHER workspace's dev server -- healthy, and
@@ -2848,6 +3790,11 @@ so a Debug run on one is wired to a LAN origin instead of localhost.`,
   relaunches that app on that device with this workspace's Metro port and loses
   in-memory state. Keep the existing --session flag and verify afterward.
 
+  ADB COULD NOT LIST OR RESTORE THE REVERSE. Before an Android reload Stim
+  checks the emulator's adb reverse for the Metro port. When adb cannot list
+  or re-apply it, nothing was reloaded; the remedy names the adb reverse
+  command to run before reloading again.
+
   MORE THAN ONE MATCHING PEER IS NOT A FAILURE. A workspace Metro serves one
   app, so several matching peers are that app on several devices. Stim reloads
   every one of them and reports the count in the facts as targets.`
@@ -2971,12 +3918,22 @@ captured"  (in metro.ndjson, bare RN)
   The command refused before doing anything: an unusable --wait value, a known
   setting with the wrong type ("Invalid <key> setting <value>. Expected <shape>."
   -- \`guide settings\` names the type each key takes), an invalid
-  Metro tunnel setting, an invalid android.dataPartitionSizeGb value, an unsafe
+  Metro tunnel setting, \`stim macos\` with macos.product or macos.infoPlist
+  unset (set both explicitly in .stim.json; see \`stim guide macos\`),
+  \`stim macos --remote eas|proxy|auto\` (name a hosting Mac instead),
+  an invalid android.dataPartitionSizeGb value, an unsafe
   android.avdConfig key or fragment, a malformed ios.signingIdentity,
-  ios.signingIdentitySha1 or ios.lanHost value, \`--device\` with an empty
-  serial or UDID, \`--device\` together with \`--remote\`, \`ios --device-type\`
-  or \`--runtime\` on a remote run (\`--remote\` or ios.remote; the remote
-  backend picks its own device), a working directory
+  ios.signingIdentitySha1 or ios.lanHost value, a metro.port or
+  STIM_METRO_PORT that another workspace reserves or another process holds,
+  a changed pin while this workspace's dev server runs or its supervisor
+  cannot be verified,
+  \`--device\` with an empty
+  serial or UDID, \`--device\` together with \`--remote\`, \`ios --runtime\`
+  on an eas/proxy run (\`--remote\` or ios.remote; that backend picks the
+  iOS version), \`ios --device-type\` on the proxy backend or with an
+  eas-cli older than 22.2.0 on the eas backend, \`android --system-image\` or
+  \`--device-profile\` on a remote run (\`--remote\` or android.remote), a
+  working directory
   with no package.json above it, or one whose nearest package.json does not
   parse or depends on neither react-native nor expo, so the directory is not
   an app (the refusal names that package.json and says which of the two it
@@ -2996,7 +3953,10 @@ captured"  (in metro.ndjson, bare RN)
   ios.deviceType, ios.runtime, android.systemImage or android.deviceProfile
   setting is checked the same way, and the check applies
   even when this workspace ALREADY owns a device, so a name that could never
-  create anything is caught rather than left to a later run. The
+  create anything is caught rather than left to a later run. When the bad
+  value came from a settings layer rather than a flag, the message also names
+  the layer (workspace, repo, committed, or machine) it is set at, since all
+  four settings are readable from the machine layer too. The
   \`pixel_fold\` and \`resizable\` profiles on a system image without
   foldable support (SupportPixelFold in its advancedFeatures.ini) refuse the
   same way, since the emulator quits on boot; the remedy names an installed
@@ -3010,6 +3970,12 @@ captured"  (in metro.ndjson, bare RN)
   is on stdout, except \`logs --json\`, whose stdout stays empty NDJSON; the
   refusal is on stderr. \`stop\` outside a project refuses rather than
   reporting that nothing was running.
+  For a changed Metro pin, run stim stop before retrying, or unset or restore
+  the pin; for an unverified supervisor, stop it with the tool that started it. A foreign holder is refused before anything starts; this project's
+  own Metro on the pin is attached to. stim web follows the same rules when
+  its page uses Metro. ios and android with --no-metro-check use the pin,
+  then the recorded port, then 8081, without probing or reserving; an invalid
+  pin still refuses.
   These errors are caught before the port is reserved and before any build or
   device work, so nothing was started. The one listing they need
   (\`simctl list runtimes\`, the SDK's system-images directory, \`avdmanager
@@ -3123,6 +4089,16 @@ captured"  (in metro.ndjson, bare RN)
   Matching this workspace's port or directory does not authorize cleanup,
   and stop has no override for process ownership.
 
+"port <n> is in use by <holder>; stim start will choose a free port"  (status)
+  A note, not a problem: no supervisor of this workspace runs, and
+  \`stim start\` reserves a free port when its own is taken. The holder's pid
+  and directory are in \`status --json\` under metro.heldBy.
+
+"port <n> is in use by <holder>, so this workspace's Metro cannot serve on
+it"  (status)
+  This workspace's supervisor runs but another process answers its port.
+  Run \`stim stop\`, then \`stim start\`, which reserves a free port.
+
 "stop        refusing to signal supervisor pid <n>: ..."  (stop)
   The records disagree, the saved OS identity is unavailable, or it records a
   port this project did not reserve. If process inspection is denied, retry
@@ -3176,6 +4152,10 @@ not on any remote"  (worktree remove)
   so per file -- those files die with the worktree either way, and a lockfile
   change anyone meant would have been committed. ONE other dirty path and the
   whole set is refused, churn included, so this never eats real work.
+  Untracked \`.watchman-cookie-*\` files, which watchman writes into the roots
+  it watches, are not work either: \`worktree remove\` deletes them itself and
+  ignores them when it counts dirty paths. Any other untracked file still
+  refuses.
   When it does refuse, the refusal PRINTS THE DIRTY PATHS, and the restore
   command under it carries those same paths: run it as printed rather than
   reaching for --force.
@@ -3306,9 +4286,9 @@ not on any remote"  (worktree remove)
   A line such as \`npm warn exec ... will be installed\` is normal when using
   the no-install form.
 
-"Unsupported engine" or a syntax error before Stim starts
-  Stim requires Node 22.12.0 or later.
-  Switch Node versions, then run the command again.
+"Unsupported engine" from npm, or a syntax error before Stim starts
+  Stim requires Node 22.12.0 or later. Stim itself refuses an older Node
+  with STIM_NODE_UNSUPPORTED; see that section.
 
 
 "Found no free Metro port between ..."
@@ -3391,6 +4371,30 @@ not on any remote"  (worktree remove)
   Expo build-cache provider would each use a different store. Set the named
   variable to an absolute path, or unset it to use the default. Metro and the
   cache provider, which cannot refuse, ignore a relative value with a warning.`
+			},
+			STIM_NODE_UNSUPPORTED: {
+				summary: "stim or stim-server started on a Node older than 22.12.0, often a project pin",
+				body: () => `STIM_NODE_UNSUPPORTED  ("Stim needs Node <floor> or later; this is Node <version> at <path>")
+  stim and stim-server refuse before loading anything else when the Node that
+  runs them is older than their engines floor. Both start through
+  \`#!/usr/bin/env node\`, so the working directory can choose that Node: asdf,
+  mise and Volta's node shim follow the project's .nvmrc, .node-version,
+  .tool-versions or package.json, and nvm and fnm do when a shell hook
+  switches versions on cd. A Stim installed with Volta keeps the Node it was
+  installed with. Run Stim with a supported Node for that one command:
+
+    ASDF_NODEJS_VERSION=<version> stim <command>
+    mise exec node@<version> -- stim <command>
+    volta run --node <version> stim <command>
+    fnm exec --using=<version> stim <command>
+    nvm exec --silent <version> stim <command>
+
+  <version> is 22.12.0 or later. asdf, mise, fnm and nvm keep global packages
+  per Node version, so when Stim was installed with npm under one of them, use
+  the version it was installed with; asdf names it when it prints "No version
+  is set for command stim" instead of running Stim. When that version is
+  older than 22.12.0, first install Stim with npm under a supported version.
+  The tools Stim starts inherit the override.`
 			}
 		}
 	},
@@ -3481,8 +4485,10 @@ apply. The run then reports \`devServer: { started: true, reason }\` in its
 JSON, with reason "not running" or "stopped (idle)". When that start fails,
 the run refuses with the start's own code (STIM_METRO_TIMEOUT,
 STIM_SUPERVISOR_EXITED, ...) before any build work. Release builds and
-\`--no-metro-check\` neither check nor start the dev server. \`--remote\`
-starts it the way \`stim start --remote\` does. Step 2 remains useful to warm
+\`--no-metro-check\` neither check nor start the dev server; hosted Debug iOS
+refuses --no-metro-check with STIM_BAD_ARG. \`--remote\`
+with eas or proxy starts it the way \`stim start --remote\` does. A named
+hosting Mac keeps Metro local through a private bridge; see hosted-ios. Step 2 remains useful to warm
 Metro while other work happens.
 
 Repeat step 3 whenever a NATIVE input changes. A JS-only edit needs nothing --
@@ -3501,6 +4507,17 @@ ambiguous no-platform request. Every reload goes over this workspace's Metro
 websocket, on both platforms. It never reopens a development-client URL,
 because that restarts the app rather than reloading its JavaScript.
 
+An Android reload first lists \`adb reverse\` on each live owned emulator
+launched against this Metro and re-applies the Metro port's reverse where it is
+missing. adb ties a reverse to its transport, and a transport that drops and
+reconnects comes back without it and without any error, which leaves the app
+cut off from Metro and Fast Refresh. After restoring one, Stim waits up to 8
+seconds, sending nothing, until the app on every emulator it checked is
+connected again, then sends the reload once. A dev server that cannot name
+its clients (bare React Native) gets a fixed 2.5-second wait instead. \`reverseRestored\` in the
+facts names the serials it restored. \`stim status\` reports the same loss as
+the android-reverse-missing issue.
+
 How the message is addressed depends on the dev server, and \`strategy\` in
 the facts reports which you got. Where Metro can name its clients, Stim
 addresses every peer matching the platform and reports \`metro-websocket\`. A
@@ -3546,9 +4563,10 @@ If the app is stuck before loading its first bundle, restart its process with
 the printed force-stop and launcher commands. Foregrounding the same process
 does not restart initialization. Confirm the bundle request and expected UI.
 
-Debug Android launches on an owned emulator created in the same run get up to
-60 seconds for bundle loading; the verify phase names that budget. Existing
-emulators, remote targets, and physical devices keep the 20-second budget.
+Debug Android launches on an owned emulator that the run creates, or whose
+adoption from the pool it finishes, get up to 60 seconds for bundle loading;
+the verify phase names that budget. Existing emulators, remote targets, and physical devices keep the
+20-second budget.
 Bundle delivery still requires the usual stability or app readiness check;
 an observed fatal error ends verification without waiting for the deadline.
 
@@ -3634,6 +4652,166 @@ WAITING FOR A CHANGE
   still running, which it notices at the next change.
   Without --json it reprints the human view on change.`,
 		sections: {
+			"hosted-ios": {
+				summary: "iOS on a named approved Mac: strict placement, private Metro, status and stop",
+				body: () => `IOS ON A HOSTING MAC
+
+If Stim is not installed globally, replace stim with npx stim.
+
+  stim settings set hosting.machines '["janics-mac-mini"]'
+  stim doctor --fix
+  # A person there approves: stim-server devices grant <id> --device-host
+  # Or runs stim-server setup on the worker with its client node, ticket and expiry.
+  stim doctor
+  stim ios --remote janics-mac-mini --device-type "iPhone 17 Pro" --runtime "iOS 27.0"
+  stim status --json
+  stim reload ios
+  stim stop
+
+The same setup serves macos --remote. Approval is separate from build, read
+and phone control. Set ios.remote to the machine name for a workspace default;
+no flag or setting runs here. eas and proxy keep their remote backend meanings.
+auto is accepted but refuses with STIM_BAD_ARG until automatic placement ships.
+Android --remote <machine> refuses with STIM_BAD_ARG: Android on a paired Mac
+is not available yet.
+
+A named Mac is strict: STIM_HOSTING_REFUSED names its reason; nothing boots
+here or elsewhere. --device cannot use a hosting Mac, and --simulator-app
+refuses. The host boots headless and ignores this Mac's iosSimulatorApp setting.
+--slot, --device-type and --runtime select the hosted simulator; --scheme,
+--configuration and --eas-profile select the app as usual. The build targets
+the offered simulator architecture, not this Mac's. --build-machine remains
+independent and selects a compatible build worker for a Debug cache miss.
+
+Stim builds or fetches before reserving, records the session immediately, then
+uploads the app on every run. Debug keeps Metro here; its supervisor owns a
+private gateway bound to this Mac's Tailscale address, pinned to the host peer
+and protected by a per-session secret. The host exposes only a loopback bridge.
+No start --remote is needed; metro.tunnel and metro.publicUrl are ignored.
+Debug requires a running supervisor with private gateway support before reserving
+a simulator. --no-metro-check refuses with STIM_BAD_ARG for hosted Debug runs.
+If its supervisor is missing or older, run stim stop; stim start, then retry.
+Non-Debug runs skip Metro. Launch is unverified until this workspace's Metro
+provides bundle evidence, or the host proves a live release process.
+
+A rerun on the same named Mac reattaches and delivers a new app attempt. A
+stopped or missing session is replaced; an unreachable or unknown owner refuses
+replacement. Switching between this Mac and a hosting Mac, or to a different
+hosting Mac, refuses for that slot: run stim stop first.
+Status adds ios.host { machine, session, selected, device: { name, runtime },
+agent, state } per slot. A shutdown local simulator is replaced in status; a
+booted or unknown local simulator stays visible alongside ios.host with a warning.
+The default slot appears only in ios, never in slots[]. No host UDID or gateway secret enters local device state or
+status. Ready is normal; stopped has a rerun hint; unknown or unreachable is
+unverified. A host server restart stops its sessions.
+
+stop and worktree remove wait for the host to stop, delete exactly its owned
+simulator without parking, close the gateway and clear placement. stop --json
+reports each hosted slot under outcomes.device["ios:host:<slot>"], retaining
+local device outcomes and successful siblings when another slot fails. Revoked or
+missing sessions clear placement too. An unreachable host retains placement
+and fails cleanup: rerun stim stop when it answers. Missing or unapproved local
+credentials require stim doctor to restore access before retrying stop. An
+unreadable machine or session remains recorded; status warns and stop names the
+workspace-state key to inspect. Only that slot's ios run refuses; restore its
+recorded machine and session from the host, then run stim stop for that slot.
+Reload returns a JSON error with that remedy when no other app can reload;
+logs remain readable. Unknown selection or agent metadata is normalized
+without discarding the owner. devices.idleShutdownMinutes
+does not stop a hosted simulator in this phase; its recorded session keeps Metro
+from idle stopping. Reruns upload only missing manifest and file digests from a
+session-scoped store; the host verifies bytes before reuse. When the iOS build
+ran on the hosting Mac's pinned node, it takes matching files from that build.
+A refused or timed-out handoff falls back to upload, retrying a still-busy host
+for at most one minute.
+
+stim logs and stim logs --errors pull native device records from bounded host
+queries. Concurrent followers share a collection, throttled per session, without
+blocking app delivery, viewing or control. Stop limits each log drain to 30 seconds with
+progress on stderr and a no-progress guard. The host collects a bounded final
+tail before deletion, including on revocation or server close; stop copies it
+back afterwards. If the final collection drops a backlog interval and eventually
+succeeds, a device warning record names that interval. A damaged collection checkpoint is ignored and
+rebuilt; it never blocks reading collected records. The client waits up to
+180 seconds for stop. The final collection and worker termination paths fit within
+that wait; an in-flight handoff copy and closing Metro or view transports are
+outside those worker bounds.
+Collected records remain in the session home after deletion;
+app blobs and materialized bundles are removed. Native queries read persisted
+entries, overlap by five seconds and de-duplicate; info-level or later-persisted
+entries may be unavailable. JavaScript logs arrive through Metro.
+The host advertises hosted-ios-data for iOS handoff and native logs. An older
+host gets an update note, uses uploads and shows logs already copied here.
+
+AGENT CONTROL
+
+On the hosting Mac, set hosting.agentDriver to agent-device. Both Macs need
+agent-device 0.21.20 or later (the policy and remote-config contract). The host
+starts one loopback daemon per installed iOS session under a child-aware
+ownership claim. Its daemon policy pins exactly that simulator UDID and denies
+shutdown. Stop, close, revocation, reinstall and graceful server close end its
+daemon and grant. A server crash can leave detached daemon processes and claims;
+restart alone does not prove they stopped. A daemon exit restarts only that
+session and rotates its grant; rerun stim ios to reattach and refresh the config.
+An unresolved proxy or daemon retains its claim and blocks reinstall and native
+teardown; clear a named claim only after proving its owner and child are gone.
+
+The client writes a separate 0600 remote-config file for each workspace slot.
+Status prints agent: <command>; ios.host.agent in --json carries driver,
+remoteConfig and command, never the token. Use the returned file:
+
+  agent-device open <bundleId> --remote-config <file>
+  agent-device snapshot --remote-config <file>
+  agent-device click <ref> --remote-config <file>
+  agent-device screenshot --remote-config <file>
+
+The command shape is agent-device <command> --remote-config <file>. Open leases
+the simulator automatically with ios-instance and the proxy provider, scoped
+to this session's tenant. Close releases it; Stim still owns the simulator.
+The config names daemonBaseUrl, daemonAuthToken, tenant, sessionIsolation,
+runId, clientId, deviceKey, leaseBackend, leaseProvider and platform; it carries
+no preallocated leaseId. stim stop closes the matching agent-device connection
+and removes that slot's config after the host confirms stop or revocation.
+The host stops the session daemon and identity-checked agent-device runners
+targeting its exact simulator UDID before deleting the simulator, even without close.
+
+Allowed: devices, open, close, snapshot, diff, wait, find, get, is, click, fill,
+press, type, focus, scroll, screenshot, longpress, swipe, back, home, orientation,
+appstate, alert and batch. These inspect or interact with the simulator and
+installed apps. devices lists only the session's simulator, filtered by the
+daemon policy. Its device claims are session-local and record / as the workspace;
+a host-side agent-device using the same simulator is not visible to the hosted daemon.
+Client device selectors are stripped and requests are pinned to iOS and that
+UDID; an explicitly named foreign UDID is refused. Selecting another device,
+boot/shutdown/erase, installs, uninstall, uploads, push, record, logs, network,
+perf, trace, clipboard and settings are refused. Stim installs; the agent cannot
+enumerate other host devices or write host files. Ambient client fields (cwd,
+stateDir, config and remoteConfig) are stripped, including inside batch steps.
+Host paths and launch inputs (--out, baseline, launchConsole, developerDir,
+installSource and similar fields) are refused, including inside batch steps.
+Only agent-device's generated screenshot temp artifact is accepted and returned
+to the client; arbitrary host screenshot destinations are refused. Runtime
+hints are dropped and only reporting/artifact metadata passes through.
+
+If hosting.agentDriver is none, the driver cannot enforce its policy, or the
+host does not advertise hosted-ios-agent, agent reports
+{ driver: 'none', setting: 'hosting.agentDriver' }. Update the host and check
+its setting and agent-device installation. No other simulator becomes reachable.
+Client hello carries only name and version, not features, so the host cannot gate
+daemon startup or grant issuance on client support. The client checks the host's
+hosted-ios-agent feature before using a grant.
+
+Stim Desktop and the phone app view and control the simulator through this
+Mac's stim-server relay, with an "on <machine>" label. Turn on Serve to phones
+in Desktop; pair the phone with this Mac, not the hosting Mac. frames.subscribe
+and control.begin address workspace, platform ios and slot, including named
+slots. The relay shares one authenticated host connection with hosted macOS
+viewers. Stopped sessions show a rerun remedy; unavailable hosts report why
+frames cannot arrive. Replay, duoFrame and physical targets are refused for
+hosted subscriptions. Desktop hides local Simulator.app, rotation, hardware
+buttons and simulator options; touch and text use the relay. The phone can also
+send the host's supported button, rotation and posture inputs.`
+			},
 			eas: {
 				summary: "download a matching EAS development build; explicit profile, costs, cache and miss remedies",
 				body: () => `EAS DEVELOPMENT BUILDS
@@ -3822,8 +5000,9 @@ result as proof instead of requiring an unrelated screenshot.`
   The labels are a closed set, and nothing else is ever printed in that
   column:
 
+    agent-device
     branch      budget      build       cache       caches      carry
-    checkout    deps        device
+    checkout    daemons     deps        device
     devices     error       failed      findings    fingerprint gems
     install     installs    ip.txt      lan         launch      lease
     lock        log
@@ -3832,7 +5011,7 @@ result as proof instead of requiring an unrelated screenshot.`
     result
     services
     setting     settings    setup       state       stats       stop
-    storage     swap        verify      version     workspace
+    storage     swap        verify      version     workspace   worktrees
 
   \`app\` and \`compilation cache\` join them in the stdout block a successful
   run ends with. When a native build runs, its compilation-cache result is
@@ -3943,6 +5122,16 @@ result as proof instead of requiring an unrelated screenshot.`
   is never touched: \`Reclaimed the environment; the working tree stays (it
   is the source checkout).\`
 
+  \`gc\` names each slow step on stderr as it starts, in every mode; its
+  report stays on stdout, and with \`--json\` stdout carries only the payload:
+
+    caches      measuring 18 shared caches
+    devices     listing simulators and emulators
+    worktrees   checking 26 projects for merged or idle worktrees
+    daemons     watchman pid 49040: checking 12 roots
+    daemons     removing stale watchman root /w/app-409
+    daemons     waiting up to 10s for 1 Gradle daemon to exit: pid 51234
+
   A GAP BETWEEN HEARTBEATS IS NOT A HANG. Stim runs device tools
   synchronously, so a long \`simctl\`, \`adb\` or copy call holds the timer
   until it returns; the next heartbeat then lands on the grid, which is why an
@@ -3950,26 +5139,40 @@ result as proof instead of requiring an unrelated screenshot.`
   killing a run.`
 			},
 			pool: {
-				summary: "parked and adopted simulators: what park and adoption clear or keep, the model and runtime match",
+				summary: "parked and adopted simulators and emulators: what park and adoption clear or keep, the model and runtime match, emulator storage, gc erase",
 				body: () => `  THE SIMULATOR POOL
   \`worktree remove\` PARKS this workspace's owned simulator instead of
   deleting it, and the next workspace that wants the same model and runtime
-  ADOPTS it. Adoption reuses the simulator but not its contents:
+  ADOPTS it. Adoption reuses the simulator and the app installed on it, but
+  not the previous workspace's state:
 
-    at park       shut down, \`simctl erase\` (apps, app data, keychain,
-                  privacy grants, pasteboard, photos, settings), renamed
-                  \`stim-parked (<model> <runtime>) <4 hex>\`
+    at park       shut down and renamed
+                  \`stim-parked (<model> <runtime>) <4 hex>\`; nothing is
+                  erased, and the pool record names the installed app's
+                  bundle id and build cache key
     at adoption   renamed for the adopting workspace, then, inside the boot
                   the run pays anyway, \`simctl privacy reset all\` and
-                  \`simctl keychain reset\`; at install, any other app is
-                  uninstalled
-
-  An erased simulator takes about 18 MB on disk instead of the gigabytes a used
-  one holds. Its first boot after the erase takes about 15s instead of a warm
-  boot's few seconds, and the app is always installed again. A SimSlim
-  profile survives the erase.
-
-  Park erases only a simulator that reports Shutdown. It waits up to 15s for
+                  \`simctl keychain reset\`; at install, every other user app
+                  is uninstalled, and this workspace's app, when it is
+                  installed, has its preferences domain deleted (an
+                  expo-dev-client app's is replaced by the two dev-menu-off
+                  keys, see \`guide facts devmenu\`) and its data
+                  container's Documents, Library, tmp and SystemData emptied
+
+  Adoption always clears the app's data, whichever workspace parked the
+  simulator: a new workspace starts from a fresh app state. The app itself
+  stays installed, so the usual byte comparison decides the install: the same
+  build prints \`install     unchanged\` and skips the copy. A parked record's
+  cache key that differs from this run's skips that comparison. App-group
+  containers, the pasteboard, photos, Safari data and Simulator settings are
+  not cleared; \`gc --cache parked --delete\` erases a parked simulator when a
+  clean system image is needed.
+
+  A parked simulator keeps its apps and data, so it can hold gigabytes. It
+  uses the Mac's disk, not a fixed partition, so there is no free-space check
+  on iOS; \`stim gc\` lists each parked simulator's app and size.
+
+  Park takes only a simulator that reports Shutdown. It waits up to 15s for
   the shutdown to settle, retries the shutdown once, and waits up to 15s more.
   A simulator that is still booted after that is deleted instead, and
   \`worktree remove\` prints
@@ -3996,6 +5199,11 @@ result as proof instead of requiring an unrelated screenshot.`
   the next attempt, unless it may have left native work running. Deletion also
   puts an opaque marker on the pool record so older Stim versions keep it
   protected. New versions resolve that marker through the same identity claim.
+  When a marker outlives its owner, Stim cannot tell whether the erase or
+  deletion ran, so adoption treats the device as erased and drops the recorded
+  app, cache key and scheme approvals. A \`gc --cache parked --delete\` erase
+  that fails after the erase command started keeps the device parked without
+  them for the same reason.
   A crash during a synchronous device-tool call leaves that work unverifiable; inspect
   the old process and its native children before following the claim's removal
   remedy. See \`stim guide errors STIM_CLAIM_REFUSED\`.
@@ -4010,8 +5218,7 @@ result as proof instead of requiring an unrelated screenshot.`
 
     device      stim-app-412 (iPhone 17 26.5) (9C1F..) adopted (17s)
 
-  That time includes the first boot after the erase and the two resets, so it
-  runs longer than a plain boot.
+  That time includes the two resets, so it runs longer than a plain boot.
   \`stim status\` prints one line while the pool is not empty:
 
     pool: 2 parked iOS simulators (max 3)
@@ -4019,12 +5226,21 @@ result as proof instead of requiring an unrelated screenshot.`
   \`stim gc\` reports the pool, and \`stim gc --delete\` empties every entry
   it can re-verify:
 
-    Parked simulators (2, 36 MB):
-      ios stim-parked (iPhone 17 26.5) 9c1f (9C1F..) iPhone 17 26.5 parked 3d ago 18 MB
-                  --delete attempts every parked simulator and keeps failures.
+    Parked simulators (2, 4.1G):
+      ios stim-parked (iPhone 17 26.5) 9c1f (9C1F..) iPhone 17 26.5 parked 3d ago com.example.app 2.3G
+                  --delete attempts verified deletions and keeps failures.
+
+  \`stim gc --cache parked\` reports only the pool, and with --delete ERASES
+  each parked simulator (\`simctl erase\`) and emulator (user data and
+  snapshots) it can re-verify instead of deleting it. The device stays parked
+  for adoption, with no app recorded; the next adopter installs its app again.
+  \`--cache all\` leaves them alone. Erase takes only a simulator
+  that reports Shutdown and an emulator that is not running and no workspace
+  references, under the same per-device claim as adoption.
 
-  \`gc --older-than <days>\` reports and deletes only the devices parked at
-  least that long; one parked at an unknown time stays.
+  \`gc --older-than <days>\` reports and deletes, or with \`--cache parked\`
+  erases, only the devices parked at least that long; one parked at an unknown
+  time stays.
 
   If simulator listing or deletion fails, \`gc --delete\` reports the failure
   and keeps that entry. It never turns an unverified absence into a dropped
@@ -4041,15 +5257,15 @@ result as proof instead of requiring an unrelated screenshot.`
   \`pool.androidParkedMax\` (default 3) or STIM_POOL_ANDROID_PARKED_MAX.
   A redirected STIM_HOME disables parking unless that environment override
   is set. Zero disables parking and adoption. \`stop\` keeps the assignment;
-  \`worktree remove\` parks eligible AVDs, and \`gc --delete\` empties the pool
-  (with --older-than, only the AVDs parked that long).
+  \`worktree remove\` parks eligible AVDs, \`gc --delete\` empties the pool
+  and \`gc --cache parked --delete\` wipes their user data (with
+  --older-than, only the AVDs parked that long).
 
   Adoption matches the system image, data partition size, and the creation
   settings from android.avdConfig / android.avdConfigFile. The AVD keeps its
-  original stim-<label> name. Parking wipes its user data, cache and
-  encryption-key images and its snapshots, the files the emulator recreates
-  on the next boot, so a parked AVD takes a few MB and adoption pays a cold
-  boot (about 20s) and a fresh install.
+  original stim-<label> name. Parking keeps its user data and Quick Boot
+  snapshot, so the installed app stays and the pool record names its package
+  and build cache key.
   Incompatible AVDs stay parked until eviction or GC. AVDs created by older
   versions without a recorded creation configuration are deleted at removal.
 
@@ -4065,10 +5281,9 @@ result as proof instead of requiring an unrelated screenshot.`
   manually clearing a claim, and keep the AVD data while its process state
   cannot be verified.
 
-  Android cleanup happens AFTER boot, before install or launch, for AVDs
-  parked with their data by older versions: \`adb shell pm clear\` clears
-  the adopting app's data while retaining its APK, and other third-party apps
-  are uninstalled. If ADB goes offline or closes the
+  Android cleanup happens AFTER boot, before install or launch:
+  \`adb shell pm clear\` clears the adopting app's data while retaining its
+  APK, and other third-party apps are uninstalled. If ADB goes offline or closes the
   connection, Stim waits for boot readiness and retries cleanup for up to 30
   seconds, verifying the same owned AVD before each destructive command.
   Failed cleanup blocks launch and remains pending for a retry. The installed APK's SHA-256 must match the
@@ -4077,10 +5292,25 @@ result as proof instead of requiring an unrelated screenshot.`
   If the retained APK has a conflicting signer or version, adoption uninstalls
   it and retries installation. Adoption stays pending until installation succeeds.
 
+  An emulator's /data partition is fixed, so an adopted AVD can run out of
+  room. Before installing, adoption reads the free space on /data
+  (\`adb shell df -k /data\`) and needs twice the APK size plus 512 MB. When
+  there is less, it runs \`pm trim-caches\`; when that is not enough, it
+  shuts the emulator down, wipes its user data through centralized teardown,
+  boots it again and installs:
+
+    device      stim-app has 97M free on /data after removing other apps and trimming caches; wiping its user data
+    device      stim-app (emulator-5556) booted with wiped user data
+
+  An install that fails with INSTALL_FAILED_INSUFFICIENT_STORAGE gets the
+  same steps: trim caches and retry, then wipe and retry. Only an adopting
+  run does this; a workspace's own emulator never loses data to it.
+
   The wipe resets apps, accounts, device settings and the shared storage
   inside the data partition; the AVD's creation settings and any separate
   SD card image remain. Status lists parked Android emulators; GC
-  reports their system image, hardware profile, age and disk size.
+  reports their system image, hardware profile, age, recorded app and disk
+  size.
 `
 			},
 			builds: {
@@ -4134,8 +5364,9 @@ PREDICTING THE NEXT BUILD (--plan)
   An Android plan reads the ABI from the emulator the slot records, or from
   the system image a new one would use. A plan refuses --device, --remote,
   --wait, --no-wait, --no-metro-check and --simulator-app with STIM_BAD_ARG.
-  Without --eas-profile it also refuses the android.remote setting and the
-  experimental compiler CAS with STIM_BAD_ARG, and refuses with
+  Without --eas-profile it also refuses the ios.remote and android.remote
+  settings with STIM_BAD_ARG. Without --eas-profile an Android plan also
+  refuses the experimental compiler CAS with STIM_BAD_ARG, and refuses with
   STIM_NO_DEVICE when no system image is installed.
 
 IOS SCHEME SELECTION
@@ -4172,8 +5403,10 @@ AN ARTIFACT THE DEVICE ALREADY HOLDS IS NOT INSTALLED AGAIN
     install     unchanged (emulator-5584 already has this build) (0.4s)
 
   On iOS the install line names the identity proof separately from the Expo
-  dev-client preference writes, so a slow simulator command is never charged
-  to an install that did not run:
+  dev-client simulator writes, so a slow simulator command is never charged
+  to an install that did not run. Those writes run only after a real install
+  or for a scheme approval the device record lacks (\`stim guide facts
+  devmenu\`), so a skipped rerun usually prints no second line:
 
     install     unchanged (stim-app already has this build) (0.4s)
     install     dev client prepared (0.9s)
@@ -4211,7 +5444,7 @@ $STIM_HOME/workspaces/<project>--<digest>/ (default ~/.stim/workspaces/).
 The aggregate run counters \`stats\` prints live beside it in
 $STIM_HOME/stats.json, one bucket per project and platform plus a machine-wide
 one, and the last 10 successful runs per project, platform and cache outcome
-that size \`status\`'s build estimate. The running build itself is the
+(plus the last 10 that set up their device) that size \`status\`'s build estimate. The running build itself is the
 activeBuild key of the workspace's state.json, cleared when the run exits.
 No .gitignore entry is created or required.
 Native preparation can change project files: expo prebuild generates native
@@ -4614,6 +5847,27 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
     4. trim shared cache entries nothing has used for 14 days
        (\`gc --delete --older-than 14\` for the caches)
 
+  IDLE SHUTDOWN (OFF BY DEFAULT): with devices.idleShutdownMinutes set, a
+  workspace's supervisor shuts down that workspace's owned simulators and
+  emulators once they have been idle that long, without waiting for a run
+  to go over budget. Idle is step 1 with that many minutes in place of 10:
+  booted, no driver, no Stim or agent-device lock, no build in progress, and
+  no activity. A stim-server client viewing the device (the phone app's
+  device viewer) counts as activity, here and in step 1. The supervisor
+  checks once a minute after the workspace's last Stim command, in-app log
+  and device log are all that old, rechecks under the workspace's native-run lock, and shuts devices down
+  through the same teardown as \`stop\`: never deleted, and physical
+  devices are never touched. It writes a device_idle_shutdown line to
+  metro.ndjson and records deviceIdleShutdowns in state.json, so \`stim
+  status\` shows "shut down after 30m idle" on the device until the next
+  \`ios\` or \`android\` run boots it again. When metro.idleStopMinutes is
+  shorter, the dev server's idle stop first shuts down the devices idle that
+  long, because no supervisor is left to check afterwards. Nothing checks
+  without a supervisor: release runs, and after \`stim stop\`. The setting
+  is read when the supervisor starts. Stim Desktop's simulator view is not a
+  stim-server client and does not count as a viewer. Turn it on with
+  \`stim settings set devices.idleShutdownMinutes 30 --scope machine\`.
+
   Steps 3 and 4 run only for disk. Memory and workspace limits never refuse;
   a run still over them prints one \`budget\` warning and continues. The
   current workspace is never reclaimed.
@@ -4632,8 +5886,8 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
 				summary: "every flag per command, Android variants and flavors, the per-run simulator model, runtime and system image",
 				body: () => `THE OPTION SURFACE, IN FULL
   start           --json --wait <seconds> --remote --reset-cache
-  ios             --slot <name> --json --plan --no-metro-check --no-build-cache --scheme <name> --configuration <name> --device-type <name> --runtime <version> --simulator-app <xcode|siniulator|stim-desktop> --device [udid] --wait <seconds> --no-wait --remote <proxy|eas>
-  android         --slot <name> --json --plan --no-metro-check --no-build-cache --variant <name> --system-image <id> --device-profile <id> --device [serial] --wait <seconds> --no-wait --remote <proxy|eas>
+  ios             --build-machine <auto|local|name> --slot <name> --json --plan --no-metro-check --no-build-cache --scheme <name> --configuration <name> --device-type <name> --runtime <version> --simulator-app <xcode|siniulator|stim-desktop> --device [udid] --wait <seconds> --no-wait --remote <eas|proxy|auto|machine>
+  android         --build-machine <auto|local|name> --slot <name> --json --plan --no-metro-check --no-build-cache --variant <name> --system-image <id> --device-profile <id> --device [serial] --wait <seconds> --no-wait --remote <proxy|eas>
   reload          [ios|android] --json
   device          lock <ios|android> [id] --slot <name> --for <duration> --wait <seconds> --json;
                   unlock [ios|android] --slot <name> --json
@@ -4645,7 +5899,7 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
                   set <key> <value> --scope <layer> --json; unset <key> --scope <layer> --json
   doctor          --json --fix --platform <ios|android>
                                   (--platform keeps shared checks and filters native findings)
-  gc              --delete --older-than <days> --cache <name|all|workspaces> --worktrees --json
+  gc              --delete --older-than <days> --cache <name|all|workspaces|recordings|parked> --worktrees --json
   worktree warm    --refresh; remove [path] --force
 
   DEVICE SLOTS
@@ -4667,7 +5921,7 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   and prints what it waits for. \`stop --slot\` interrupts a build only for
   its own slot or when it stops the workspace's only device (see STOP DURING
   A BUILD).
-  Named slots support local devices; remote sessions use the default slot.
+  Named slots support local devices and hosted iOS simulators; eas/proxy sessions use the default slot.
   Names use 1-64 letters, digits, underscores or hyphens, starting with a letter
   or digit. Reserved object-property names and web are refused.
 
@@ -4707,6 +5961,12 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   worktrees of the same Git repository; the source checkout must be available.
   Running it in the source checkout refuses.
 
+  Warm registers the app it prepares, so \`stim status\` lists the workspace
+  with phase "warming" while it runs and "ready" once it succeeds, until the
+  first start, ios, android, web or reload there or for 2 hours
+  (\`guide facts status\`). In a monorepo worktree root, that app is the one
+  the source checkout has registered.
+
   \`stim doctor\` reports the source checkout's fitness as a seed -- how far
   behind its upstream it is, uncommitted tracked changes, an interrupted rebase
   or merge, a detached HEAD, a diverged branch, a branch that is not the
@@ -4787,7 +6047,7 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   paths eligible under the source checkout's Git ignore rules, including .env
   and local configuration. The source's nonempty
   .worktreeexclude replaces its resolved worktree.exclude setting. Nested
-  registered worktrees, .DS_Store, .DerivedData, .idea, and
+  registered worktrees, .DS_Store, .DerivedData, .idea, .jj, and
   android/build/generated/autolinking caches are excluded, including inside
   newly copied directories. Gradle regenerates autolinking
   for the destination checkout on its next build. Warm also skips paths
@@ -4866,11 +6126,23 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   runtime when \`--runtime\` also resolved, which is what catches a pair like
   \`--device-type "iPhone 8" --runtime 26.5\` that each half would pass alone.
   \`--runtime\` takes a version (\`26.5\`) or a runtime's full name
-  (\`iOS 26.5\`), exactly; no prefix or suffix matches. Both flags choose
-  the local owned simulator only: with \`--remote\` or the ios.remote setting
-  they refuse with STIM_BAD_ARG, because the remote backend picks its own
-  device. The ios.deviceType and ios.runtime settings do not refuse there;
-  a remote run ignores them.
+  (\`iOS 26.5\`), exactly; no prefix or suffix matches. On a remote run
+  (eas/proxy via \`--remote\` or ios.remote) \`--runtime\` refuses with
+  STIM_BAD_ARG, because the remote backend picks the iOS version. So does
+  \`--device-type\` on the proxy backend. The eas backend honors
+  \`--device-type\`: Stim passes it to \`eas simulator:start --device\`,
+  unchecked against local runtimes, and refuses with STIM_BAD_ARG when
+  eas-cli is older than 22.2.0, the first release with that flag. A
+  recorded EAS session still running another model refuses with
+  STIM_REMOTE_DEVICE_MISMATCH instead of being reused; one that already
+  ended is replaced on the requested model. The ios.deviceType and
+  ios.runtime settings do not refuse on an eas/proxy run; it ignores them.
+  A named hosting Mac uses both selectors and its installed choices instead;
+  an unavailable choice is STIM_HOSTING_REFUSED. See hosted-ios.
+  \`android --system-image\` and \`--device-profile\` refuse with
+  STIM_BAD_ARG on every remote run (\`--remote\` or the android.remote
+  setting), and a remote run ignores android.systemImage and
+  android.deviceProfile.
 
   These flags describe a device that does not exist yet. When this workspace
   ALREADY owns a simulator and \`--device-type\` names a different model, or
@@ -4938,11 +6210,25 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   and the remedy is the cable. Metro is unaffected: a Debug app reaches it
   over the LAN either way.
 
+  WATCHING A LEASED ANDROID PHONE: while this workspace holds the phone's
+  lease, stim-server can stream its screen to paired clients that ask for the
+  physical device, and let one with control tap and type on it. stim-server
+  pushes the scrcpy server to /data/local/tmp for the stream and deletes it
+  when the stream stops; it installs nothing and changes no setting. Control
+  ends when the lease is released or expires, and stim-server never takes a
+  phone's lease itself.
+
   \`stop\` releases this workspace's leases and stops its log collectors.
   On a physical iPhone that also closes the app, because its collector owns
   the devicectl launch session. \`gc --delete\` removes expired lease files;
   neither command shuts down the phone or uninstalls the app.
 
+  WATCHING THE PHONE: while this workspace holds the lease, stim-server
+  streams a USB-cabled iPhone's screen to the phone app, view only; Stim
+  sends a physical iPhone no input. The lease ends with the run, so
+  \`device lock ios <udid>\` keeps it watchable between runs. A Wi-Fi phone
+  has no stream, and a locked phone shows its last frame until unlocked.
+
   A device build is LOCAL-TIER ONLY. Its cache key is
   \`<fingerprint>-<configuration>-device\`, so a device app can never collide
   with the simulator one, and neither the build-cache provider nor the Expo
@@ -4968,8 +6254,9 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   this workspace's Metro, and then wires the app to it: an expo-dev-client app
   through the deep link, passed to devicectl as \`--payload-url\` and followed
   by \`-- -EXDevMenuShowsAtLaunch 0 -EXDevMenuShowFloatingActionButton 0\`,
-  which is how a phone gets what a simulator gets from a defaults write, and a
-  bare app by writing \`<addr>:<port>\` into the app bundle's ip.txt --
+  the same launch arguments Stim's own \`simctl launch --initialUrl\` carries on
+  a simulator, and a bare app by writing \`<addr>:<port>\` into the app bundle's
+  ip.txt --
   RCTBundleURLProvider's own mechanism, which honours a colon-bearing value
   verbatim and never consults the compiled RCT_METRO_PORT. Stim never sets
   that define: it would put the reserved port into a compiled input and fork
@@ -5149,6 +6436,17 @@ THE POOL: WHICH DEVICE AN ID-LESS \`--device\` PICKS
   android.keystorePassword override it (see \`guide settings\`). The cache
   entry itself is never modified.
 
+  AN EXPO-UPDATES APP GETS A FRESH EMBEDDED UPDATE. expo-updates launches the
+  update with the newest commitTime for the binary's runtime version, and the
+  embedded bundle is one of those updates. The cached artifact's embedded
+  manifest (app.manifest) carries the CACHED build's id and time, so an
+  update the app downloaded after that build would launch instead of the
+  swapped JS. The swap gives the copy's manifest a new id and this run's time,
+  exactly as a full build does, on both platforms. An update published after
+  the swap can still download and launch on a later start, as it would on a
+  fresh build. A manifest the swap cannot rewrite, or one inside a dynamic
+  EXUpdates.framework on iOS, falls back to a full build.
+
   Before re-packing, THE ASSET GATE compares CONTENT HASHES of the assets
   React Native emits: what this workspace just emitted under --assets-dest
   against a manifest of what the cached build emitted, recorded as
@@ -5193,7 +6491,8 @@ THE POOL: WHICH DEVICE AN ID-LESS \`--device\` PICKS
   its builder's baked-in JS, a cache hit regenerates THIS workspace's bundle
   (the project's own \`expo export:embed\` / \`react-native bundle\`, plus
   its own hermesc when Hermes is enabled) into a copy of the artifact,
-  re-signs it and installs that; any swap failure falls back to a full build
+  refreshes an expo-updates manifest as described above, re-signs it and
+  installs that; any swap failure falls back to a full build
   rather than ever installing stale JS. Device logs are still collected, so
   \`logs --errors\` answers "does it repro in release/Hermes bytecode".
   A run with no \`--device\` installs on the simulator only. \`ios --device\`
@@ -5294,8 +6593,56 @@ wipe state to upgrade: it records ownership needed for safe teardown. Use the
 same slot-aware CLI for all commands while named assignments exist; older
 versions cannot reliably manage their assignments.
 
+ARCHIVE
+
+Linked-worktree removal and gc dead-project pruning keep history under
+$STIM_HOME/archive by default. See stim guide cleanup archive.
+
+MAINTENANCE
+
+Automatic maintenance is report-only in this release: it measures, plans and
+logs, and never stops or deletes resources. The default mode is report; it is
+off in CI and scoped STIM_HOME homes unless STIM_MAINTENANCE is explicit.
+Commands trigger a detached pass when disk and memory checks (every minute)
+or directory sizes (hourly) are due. guide, settings and help do not trigger
+it; gc --delete also skips the hook. status --watch also triggers checks.
+Size checks defer under high load. Attempts back off for at least one minute.
+Measured directories are workspace build outputs and Stim's shared native,
+Metro, ccache, Swift compilation and registered caches. Pressure checks read
+free disk on the Stim home, projects and worker root volumes. On macOS the
+memory signal is the sysctl pressure level, with no signal if sysctl fails.
+Other platforms use os.freemem(); macOS never falls back to it.
+Memory pressure is recorded only; memory stops are deferred to a later phase.
+
+  stim status                     last checks, plan and running pass
+  stim status --json              maintenance observations and recent records
+  stim logs --source maintenance  this workspace's maintenance records
+  stim gc                         live pressure and cached-size preview
+  stim settings set maintenance.mode off
+
+The machine log is $STIM_HOME/maintenance/maintenance.ndjson, rotated at
+maintenance.logMaxMb with the old generation retained for
+maintenance.logRetentionDays. Child crashes use maintenance/child.log.
+Actions and explaining skips are logged only when newly planned. A pass is
+logged after a size check or a change to actions, skips or blocked reasons.
+maintenance.logChecks enables debug observations; default false.
+status and doctor report invalid settings and unresolved claims with a removal
+command to run only after confirming the holder is gone. Invalid cache caps
+fall back to their own defaults; invalid maintenance settings disable passes.
+The run claim serializes passes with gc --delete; gc refuses a held claim
+with the holder and recovery guidance instead of waiting.
+
 CLEANUP AND DISK
 
+worktree remove stops the agent-device daemon when the workspace's
+agent-device/daemon.json exists, then removes its state directory with the
+workspace. If agent-device is missing or the stop fails, it keeps the directory
+and reports the retry command: agent-device daemon stop --state-dir <dir> --clean.
+A daemon.json whose process is gone is stale and does not block removal.
+gc --delete of a finished worktree does the same.
+stop closes owned-device sessions in that directory without deleting it.
+See stim guide logs for AGENT_DEVICE_STATE_DIR examples.
+
 WHAT RECLAIMS AN OWNED DEVICE
   stim worktree remove    parks eligible owned simulators and emulators
                             (\`guide lifecycle pool\`); deletes them when
@@ -5313,6 +6660,10 @@ WHAT RECLAIMS AN OWNED DEVICE
                             command has used in that long, even though the
                             project is still on disk, and clears only the
                             devices parked at least that long
+  stim gc --cache parked --delete
+                            ERASES (never deletes) verified parked simulators
+                            and wipes parked emulators' user data; they stay
+                            parked for adoption (\`guide lifecycle pool\`)
   stim gc --delete --worktrees
                             also runs \`stim worktree remove\` on every clean,
                             idle, Stim-managed linked worktree
@@ -5321,25 +6672,36 @@ WHAT RECLAIMS AN OWNED DEVICE
                             shuts DOWN (never deletes) owned devices with no
                             driver, claim or activity for that long
 
+\`gc --delete --cache watchman\` and \`gc --delete --cache gradle-daemons\`
+stop shared helper processes, not devices (\`guide cleanup memory\`).
+
 \`worktree remove\` and \`gc --delete\` are the only two commands that delete;
 \`gc --delete\` deletes worktrees only through \`worktree remove\`. \`gc
 --delete\` also clears workspace build outputs, trims oversized workspace logs
 (\`guide cleanup disk\`) and removes orphaned workspace directories, never a
-checkout. \`stim stop\` shuts a device
+checkout. Device recordings can also go without either: stim-server prunes
+them, and turning recording.enabled off deletes them (\`guide cleanup disk\`). \`stim stop\` shuts a device
 DOWN and leaves it assigned, which is what makes returning to a branch cost a
 boot rather than a create, a provision and a reinstall.
 
 Before shutting down, parking or deleting an owned device, Stim best-effort
 closes local agent-device sessions bound to its exact iOS UDID or live Android
 serial. An Android session must also name the owned AVD, because the next
-emulator on a console port reuses its serial. \`stop\` closes a session only
+emulator on a console port reuses its serial. For an emulator that is already
+shut down, Stim closes the sessions that name its AVD on any serial that no
+connected device now holds. \`stop\` closes a session only
 when agent-device's claim on the device names it and was taken inside this
-workspace; sessions from another workspace or claim stay open. Stim rechecks
+workspace. It also closes a session claimed from the workspace's git root
+itself, such as a worktree root above the app, but only after it has shut that
+device down and rechecked that the device is still stopped and that no other
+device holds its UDID or serial. Sessions from another workspace or claim,
+including sibling directories under the git root, stay open. Stim rechecks
 device ownership and uses agent-device's rejecting session target guard;
 sessions on other devices stay open. Physical devices are outside
 this cleanup. agent-device is optional: a missing binary skips this step, and a
 failed or timed-out list/close prints a device line on stderr while teardown
-continues. Cleanup allows at most 15 seconds of agent-device calls per device.
+continues. Each cleanup pass allows at most 15 seconds of agent-device calls
+per device; the pass \`stop\` makes after shutdown has its own budget.
 A local daemon that cannot use socket transport or a CLI without the target guard
 skips cleanup with a warning; no remote daemon is used.
 
@@ -5350,9 +6712,77 @@ written by a newer Stim -- costs one dim line on stderr and is otherwise left
 alone; only the next \`ios\` or \`android\` run moves an unparseable one aside
 to stats.json.corrupt-<unix ms> and starts a new one.`,
 		sections: {
+			archive: {
+				summary: "retained workspace history and explicit archive cleanup",
+				body: () => `ARCHIVE
+  Linked-worktree removal and gc pruning a registered root that is gone keep
+  state, ended agents, the error index, logs, closed recording segments and
+  workspace-local agent-device sessions under $STIM_HOME/archive.
+  Build outputs and open recording segments are deleted with the workspace.
+  Archives have no checkout, devices, ports or running processes. A recreated
+  path starts fresh; status links its earlier archives with replacedBy.
+  Paired clients with read can select archived[].id with archive instead of
+  workspace for server log queries and replay. Archived log subscriptions send
+  retained records, then logs-ended. Archived frame subscriptions need at and
+  cannot be physical or go live. Replay ranges report recording disabled.
+  Reads stay on this Mac.
+  An updated server is required; older servers refuse with bad-request when
+  workspace is omitted. There is no CLI archive log flag.
+  archive.enabled defaults true and accepts every settings layer. STIM_HOME
+  disables archives unless STIM_ARCHIVE_ENABLED is set. Empty stubs and orphaned
+  workspace directories are not archived. A failure prints one stderr line
+  beginning "could not archive:" and removal continues with empty stdout.
+
+  Retention runs on every worktree removal, archived or not, once an archive
+  exists. It deletes records past their age or count limit first, then expires
+  recordings, agent actions and logs by age from removedAt; trims per-workspace
+  logs (oldest rotated generations, then build logs, then oldest other files);
+  and removes the largest kind of the oldest archive while over total caps.
+  Archives with expired artifacts keep their record until the record limit. recording.enabled false at machine scope deletes archived
+  recordings on the next retention pass. Sizes are binary GB/MB; 0 keeps none.
+  See stim guide settings for the nine archive.* keys and overrides.
+
+  stim gc --cache archived                     list ids, kinds, bytes and expiry
+  stim gc --delete --cache archived             delete every archive
+  stim gc --delete --cache archived --older-than 14
+                                                only removed at least 14 days ago
+  stim gc --delete --cache archived:<id>         delete one; ignores --older-than
+  stim gc --delete --cache archived-logs        delete logs, keep records
+  stim gc --delete --cache archived-recordings  delete recordings, keep records
+  stim gc --delete --cache archived-agent       delete agent actions, keep records
+  Per-kind selectors also accept --older-than, measured from removedAt.
+  Normal gc, --cache all, --worktrees and unscoped --older-than exclude archives.
+  Archive scopes report abandoned staging directories and delete only those
+  with no live or unresolved claim. An unresolved claim names its removal command.
+
+  Directories are 0700 and files 0600. No redaction is applied; logs and agent
+  actions can contain secrets. Use archive.enabled false for a sensitive repo.
+  Archived logs and replay are not exposed through CLI or app readers yet.`
+			},
 			gc: {
 				summary: "what gc and worktree remove delete, keep and refuse: orphans, stale records, locks, leases, EAS sessions",
-				body: () => `LINKED WORKTREES
+				body: () => `AGENT-DEVICE (REPORT ONLY)
+Unscoped gc reports agent-device runner builds by platform and entry, last use,
+agent-device and Xcode versions, sessions, logs, other state, workspace state
+and hosted driver state. Stim never selects this state as a cache.
+Stim never trims or deletes the shared runner builds, sessions, logs and other
+state or the hosted driver dir; a workspace's own agent-device dir goes only with its workspace.
+A live owner or runner lease marks an entry in use. A lock marks it in use only
+when its owner is live or unknown. Unreadable lock owners and unreadable or unknown
+leases conservatively mark entries in use. Dead lock owners and leases do not.
+Use agent-device's own tooling or remove directories yourself to clear unused
+state. --cache scopes omit this report, including --cache all.
+
+SWIFTPM CACHE (REPORT ONLY)
+Unscoped gc also reports the user-level SwiftPM cache after agent-device:
+~/Library/Caches/org.swift.swiftpm on macOS, or org.swift.swiftpm under
+XDG_CACHE_HOME (default ~/.cache) elsewhere. It is shared by every SwiftPM
+build on this machine. Stim reports it and never deletes it. It is never in
+caches, never changes actionable, and --delete and --older-than never select
+it. Any --cache scope, including all, omits measurement and reports
+sections.swiftpmCache: null. Only stats and unscoped gc measure it.
+
+LINKED WORKTREES
   \`stim worktree remove\` works with any linked worktree, warmed or not.
   Git registration identifies the worktree; a Stim registry entry is not
   required. Before it reclaims anything, the command refuses a worktree git
@@ -5388,7 +6818,8 @@ SWEEPING FINISHED WORKTREES
   one that is idle: no recorded use for --older-than days, 7 without it; a
   worktree whose last use is unknown is kept. Both need the same clean state;
   a worktree is kept when it is the source checkout, bare, locked, in use,
-  dirty (untracked files count; pod install churn alone does not), unpushed
+  dirty (untracked files count; pod install churn and
+  watchman's untracked \`.watchman-cookie-*\` files alone do not), unpushed
   (commits no remote-tracking ref or other local branch reaches), or has
   initialized submodules. Without --worktrees, the report leaves out the
   source checkout and roots outside git.
@@ -5443,11 +6874,14 @@ SWEEPING FINISHED WORKTREES
   takes the pull request whose head is HEAD, else one whose head contains
   HEAD. A pull request whose head HEAD is past ("PR #12 merged, and HEAD has
   commits it does not"), one unrelated to HEAD (an older use of the branch
-  name), and one from a fork do not count. A merged or closed one makes the worktree finished
-  under the same clean state. Merged, its commits are kept on GitHub, so local
-  commits whose remote branch was deleted do not block removal. Closed, they
-  do: a closed pull request whose remote branch is gone keeps the worktree as
-  unpushed. An open pull request never makes a worktree finished. When gh is
+  name), and one from a fork that is not one of the repository's own remotes
+  (a stranger's fork reusing the branch name) do not count; a pull request
+  opened from the user's own fork counts like any other. A merged or closed
+  one makes the worktree finished under the same clean state. Merged, its
+  commits are kept on GitHub, so local commits whose remote branch was
+  deleted do not block removal. Closed, they do: a closed pull request whose
+  remote branch is gone keeps the worktree as unpushed. An open pull request
+  never makes a worktree finished. When gh is
   not installed, not signed in, or fails, the JSON pullRequestUnknown field
   and the report say why, and gc judges from git alone. A detached HEAD is
   not looked up. \`stim worktree remove\` makes the same check when
@@ -5492,6 +6926,20 @@ ORPHANED WORKSPACE DIRECTORIES
   it. A directory with a missing or unparseable workspace.json, or a root on
   an unmounted volume, is reported under Skipped and never deleted.
 
+STALE STATUS CACHE ENTRIES
+  \`stim status\` caches each folder's size under $STIM_HOME/disk-usage and
+  each worktree's pull request under $STIM_HOME/pull-requests. \`worktree
+  remove\` drops the entries of the worktree it removed (its checkout,
+  node_modules and workspace folder, and its pull request), not the size
+  entries of its owned devices' data folders. \`gc\` reports the
+  entries of a folder or worktree that was removed some other way under "Stale
+  status cache entries", and \`gc --delete\` removes them. An entry counts as
+  stale only when the path it records is gone and its volume is mounted (a
+  measured node_modules folder follows its checkout). An entry that records no
+  readable path, one whose path cannot be checked, and one on an unmounted
+  volume are kept and counted under Skipped. \`status\` measures a folder again
+  if it comes back.
+
 NAMED SERVER PORTS
   worktree remove stops TCP listeners on each named allocation and releases
   the ports. gc reports named allocations for missing workspaces; gc --delete
@@ -5683,9 +7131,65 @@ THE ONE CASE GC WILL NOT REAP
   is gone, and the unrelated process is never signalled. A missing, malformed,
   or unreadable identity leaves the record unverified and kept for a retry.
   Wall-clock timestamps and command names are not ownership proof.`
+			},
+			memory: {
+				summary: "watchman and Gradle and Kotlin daemon memory in gc, and when gc --delete --cache watchman or gradle-daemons stops them",
+				body: () => `MEMORY
+  Every \`gc\` without --cache, and \`gc --cache watchman\` or
+  \`gc --cache gradle-daemons\`, reports the long-lived helpers that grow while
+  they run: the shared watchman daemon, Gradle daemons and Kotlin compile
+  daemons. Each line gives the pid, physical footprint (the measure status
+  uses; resident size when the footprint cannot be read), uptime and whether
+  it is idle, and a kept one says why. The reclaimable line totals what
+  the two commands below would free now.
+
+  Only these two commands stop anything, and each acts only on its own kind.
+  Neither a plain \`gc --delete\` nor \`--cache all\` touches them:
+    stim gc --delete --cache watchman
+                                  runs \`watchman watch-del\` on each stale root
+                                  with no subscription or trigger, then
+                                  \`watchman shutdown-server\` only when
+                                  \`debug-status\` lists no client but gc's own
+                                  call and no root has a trigger; otherwise
+                                  the daemon is kept and the report names
+                                  each client, as the Stim workspace whose
+                                  dev server it belongs to where it can
+    stim gc --delete --cache gradle-daemons
+                                  stops each Gradle daemon its own
+                                  \`gradle --status\` reports IDLE, then each
+                                  Kotlin compile daemon with no open client
+                                  connection once every Gradle daemon is idle
+
+  A stale watch root is one whose directory is gone from a mounted volume, or
+  that sits in a linked worktree git pruned while its directory stayed.
+  Watchman drops a root itself when its directory is deleted, so stale roots
+  are rare. Removing one stops its recrawls but does not shrink the daemon;
+  only a restart returns its memory. After a shutdown the next client that
+  needs watchman starts it again and re-watches the roots in its state file.
+  Every watchman call uses --no-spawn, so gc never starts the daemon.
+  Shutting it down under a Metro that uses watchman would break that Metro's
+  file watching, which is why any connected client keeps it.
+
+  gc finds a Gradle daemon's Gradle user home from the daemon log it holds
+  open (lsof), and asks the daemon's own distribution for its status with
+  that home and the daemon's Java. When every daemon that status lists for a
+  home and version is idle, gc runs that distribution's \`gradle --stop\`;
+  otherwise it sends SIGTERM to each idle daemon, after checking the pid still
+  has the same start time. A build that picks a daemon between gc's last
+  check and the stop fails and must be run again, so gc re-checks the build
+  locks and the daemon's status right before each stop. Nothing is stopped while an Android build lock, or a build slot no
+  iOS build holds, is live or unresolved. stim-server stops the daemons of
+  offloaded builds (offload.gradleDaemonIdleMinutes, \`guide settings\`), so
+  while it runs gc keeps those. A daemon whose home, distribution or status cannot be read is
+  kept. Gradle stops an idle daemon itself after 3 hours and Kotlin after 2
+  hours by default.
+
+  --older-than does not apply to these kinds and is refused with
+  STIM_BAD_ARG. With STIM_HOME set, gc skips them: they are machine-global.
+  \`stim doctor\` notes a watchman footprint over 2 GiB.`
 			},
 			disk: {
-				summary: "disk usage, workspace build outputs and logs, AVD and build-log sizes, the data partition, trimming the shared caches",
+				summary: "disk usage, workspace build outputs, logs and device recordings, AVD and build-log sizes, the data partition, trimming the shared caches",
 				body: () => `DISK
   Logs, state, pidfiles and Xcode DerivedData are under the global workspace
   directory, and \`worktree remove\` reclaims them. \`gc --delete\` clears the
@@ -5695,7 +7199,8 @@ THE ONE CASE GC WILL NOT REAP
 
   Android AVDs normally live under ~/.android/avd, and a booted owned AVD can
   use several GB. \`worktree remove\` parks the workspace's owned AVD with its
-  user data and snapshots wiped, or deletes it when the pool is off or full;
+  user data and snapshots kept, or deletes it when the pool is off or full;
+  \`gc --cache parked --delete\` wipes a parked AVD's user data and snapshots;
   plain \`stop\` only shuts it down for reuse. Stim uses Android's default Quick Boot
   unless displayless Linux requires software rendering, where snapshots are
   disabled. The first boot and a boot after the emulator, system image, or AVD
@@ -5707,7 +7212,7 @@ THE ONE CASE GC WILL NOT REAP
   errors teardown\`).
   New owned AVDs default to an 8 GiB data partition, though project settings can
   change it. When enabled, Quick Boot keeps one automatic snapshot until the AVD is
-  parked or deleted.
+  wiped or deleted.
   \`gc\` prints the on-disk size beside an orphaned or stale owned Android AVD
   when its content directory can be read, and beside an orphaned or stale
   owned simulator the data size simctl reports for it.
@@ -5738,15 +7243,20 @@ setting applies only to a newly created AVD; recreate the environment to adopt
 a changed value.
 
 WORKSPACE BUILD OUTPUTS
-  Each workspace directory holds derived-data/, gradle-build/, android-cas/
-  and cache-provider/. \`gc\` reports them as one detected cache, "Workspace
-  build outputs", with a per-workspace size, last use and verdict. Plain
+  Each workspace directory holds derived-data/, gradle-build/, android-cas/,
+  cache-provider/, macos/build, the staged macos/<Product>.app and macos/staging-*
+  leftovers. \`gc\` reports them as one detected cache, "Workspace build
+  outputs", with a per-workspace size, last use and verdict. Plain
   \`gc --delete\` clears them for every workspace not in use (see \`guide
   cleanup gc\`), before anything else. \`--older-than <days>\` limits that to
   workspaces idle at least that long, and keeps one whose last use is
-  unknown. \`--cache workspaces\` acts on them alone; \`--cache all\` includes
-  them. Only those four directories go: workspace.json, state.json, logs/,
-  locks and device records stay, so the workspace keeps its devices and ports.
+  unknown. \`--cache workspaces\` acts on them alone, except in the workspace
+  directories that plain \`gc --delete\` removes whole (dead projects and
+  orphaned directories); \`--cache all\` includes them. macos/ itself,
+  macos/runtime.lock and its claim set, workspace.json, state.json, logs/,
+  other macOS files, locks and device records stay, as does the project's
+  own .build. The workspace keeps its devices and ports. A running, building,
+  unverified or hosted macOS app keeps its workspace untouched.
     stim gc --delete --cache workspaces --older-than 7
   Last use is the newest of the lastUsedAt that start, ios, android, reload
   and worktree warm record in state.json, lastBuild.startedAt,
@@ -5757,7 +7267,8 @@ WORKSPACE BUILD OUTPUTS
   The next build of an unchanged app installs from the shared build cache.
   After a native change the Xcode compilation cache speeds the rebuild, but on
   React Native 0.86 Swift does not use it (explicit modules are off), so that
-  build recompiles Swift.
+  build recompiles Swift. The next \`stim macos\` rebuilds its scratch from
+  nothing (a full Swift build) and restages the app.
 
 WORKSPACE LOGS
   \`gc\` reports the size of each workspace's logs/ (the workspaceLogs
@@ -5772,6 +7283,33 @@ WORKSPACE LOGS
   stops the collector. Build transcripts keep the whole run and are never
   trimmed, and nothing else under logs/ is touched.
 
+DEVICE RECORDINGS
+  stim-server records owned simulators, emulators and the Stim-owned Chrome
+  page while an automation tool drives them or a paired client watches them,
+  into recordings/ in the workspace directory (\`guide settings\`). It keeps
+  the last 15 minutes of recorded footage per device; idle time and time after
+  \`stim stop\` age nothing out, so \`stop\` ends recording and the footage
+  stays replayable. Across every workspace of this Stim home it keeps at most
+  1 GiB, deleting the oldest footage first. Recordings are deleted by:
+
+    stim worktree remove          that workspace's recordings, with its
+                                  workspace directory
+    stim gc --delete              the recordings of dead or orphaned
+                                  workspaces, with their workspace directory;
+                                  a workspace whose project root cannot be
+                                  proven gone keeps them
+    stim gc --delete --older-than <days>
+                                  also footage recorded before that many days
+                                  ago, in every workspace
+    stim gc --delete --cache recordings
+                                  every workspace's recordings, and nothing
+                                  else; --cache all includes them
+    recording.enabled false       the recordings of each workspace it turns off
+
+  \`gc\` lists them in the recordings section of \`gc --json\` with each
+  workspace's bytes, what a delete would remove (deleteBytes), and why the rest
+  stays.
+
 SHARED BUILD CACHES
   The caches that make a second workspace fast are alive by design and never
   included in a plain \`gc --delete\`. Every \`gc\` run reports them anyway,
@@ -5819,7 +7357,7 @@ read from, or an unknown key refuses with STIM_BAD_ARG naming the expected
 shape, before anything is written. Writes to the machine file take its lock
 and replace it atomically; a committed write keeps the file's other keys and
 indentation. Run \`stim settings\` from the app directory: workspace and
-committed resolve from the nearest package.json, repo from its Git
+committed resolve from the nearest package.json or Package.swift, repo from its Git
 repository. From a monorepo web package that resolves to its worktree's app
 (see stim guide ports), workspace and committed are that app's entry and
 .stim.json. worktree.exclude and worktree.defaultBranch are read only from
@@ -5838,9 +7376,11 @@ carries its dotted key, layers, and environment override under "x-stim".
 Resolution order, first match wins:
   1. workspace       ~/.stim/config.json, under this project's entry
   2. repo            ~/.stim/config.json, under this repo's git common dir
-  3. committed       .stim.json beside the app's package.json
-  4. machine         ~/.stim/config.json, top-level optimizations and
-                     android.deviceProfile only
+  3. committed       .stim.json beside the app's package.json or Package.swift
+  4. machine         ~/.stim/config.json, top-level optimizations,
+                     ios.deviceType, ios.runtime, android.systemImage,
+                     android.deviceProfile and devices.idleShutdownMinutes
+                     and archive.enabled
   5. Stim default
 An environment override, where a setting has one, wins over every layer.
 
@@ -5866,19 +7406,31 @@ An app's .stim.json can contain:
     "android": { "variant": "productionDebug" }
   }
 
+ARCHIVE SETTINGS
+${SETTINGS.filter((setting) => setting.key.startsWith("archive.")).map((setting) => `  ${setting.key}: ${setting.description}; default ${setting.default}; layers ${setting.scopes.join(", ")}; ${setting.env}`).join("\n")}
+Sizes use binary GB/MB. Archive ages and caps accept 0 to keep none.
+STIM_HOME makes archive.enabled false unless STIM_ARCHIVE_ENABLED is set.
+See stim guide cleanup archive for retention and explicit deletion.
+
 KEYS STIM READS
   ios.deviceType        e.g. "iPhone 17 Pro" -- the simulator model this
                         workspace's owned sim is created as, spelled exactly as
                         \`xcrun simctl list devicetypes\` names it, and one an
-                        installed runtime can create. The \`--device-type\`
-                        flag overrides this per invocation. A name no installed
-                        runtime offers is STIM_BAD_ARG and the creatable names
-                        are printed
+                        installed runtime can create. Readable from the
+                        machine layer too, so one machine can default every
+                        workspace to a model; a project layer still wins. The
+                        \`--device-type\` flag overrides this per invocation. A
+                        name no installed runtime offers is STIM_BAD_ARG and
+                        the creatable names are printed, naming the layer the
+                        value came from
   ios.runtime           e.g. "26.2" -- the iOS runtime that sim is created on,
                         as a version ("26.2") or a runtime's full name
-                        ("iOS 26.2"); nothing else matches. The \`--runtime\`
-                        flag overrides this per invocation, and an uninstalled
-                        version refuses the same way
+                        ("iOS 26.2"); nothing else matches. Readable from the
+                        machine layer too, so one machine can default every
+                        workspace to a runtime; a project layer still wins.
+                        The \`--runtime\` flag overrides this per invocation,
+                        and an uninstalled version refuses the same way,
+                        naming the layer the value came from
   ios.configuration     e.g. "Release" -- the Xcode configuration to build
                         (simulator only). Committing
                         { "ios": { "configuration": "Release" } } makes every
@@ -5886,9 +7438,10 @@ KEYS STIM READS
                         embedded JS, no Metro, cache keyed -release-sim, and
                         a JS-bundle swap on cache hits. The \`--configuration\`
                         flag overrides this per invocation. Unset means Debug.
-  ios.remote            "proxy" or "eas" to use that remote backend, the same
-                        as passing \`--remote proxy\` or \`--remote eas\`. The
-                        build still runs here; only the device is elsewhere.
+  ios.remote            "proxy", "eas", or a named approved Mac from
+                        hosting.machines, with the same meaning as --remote.
+                        "auto" is accepted but refuses until automatic placement
+                        ships. Unset runs here. See lifecycle hosted-ios.
   ios.simslimProfile    a SimSlim JSON profile under the app directory,
                         at most 64 KiB. Install the
                         external tool once with
@@ -5930,9 +7483,12 @@ KEYS STIM READS
                         interface.
   android.systemImage   e.g. "system-images;android-36;google_apis;arm64-v8a"
                         -- the sdkmanager package id the owned AVD is created
-                        from. The \`--system-image\` flag overrides this per
-                        invocation, and an id this SDK has not installed is
-                        STIM_BAD_ARG with the installed ids printed.
+                        from. Readable from the machine layer too, so one
+                        machine can default every workspace to an image; a
+                        project layer still wins. The \`--system-image\` flag
+                        overrides this per invocation, and an id this SDK has
+                        not installed is STIM_BAD_ARG with the installed ids
+                        printed, naming the layer the value came from.
   android.deviceProfile e.g. "pixel_fold" -- the avdmanager hardware profile a
                         new owned AVD is created with, spelled exactly as
                         \`avdmanager list device -c\` prints it. Defaults to
@@ -6036,15 +7592,35 @@ ${ANDROID_AVD_CONFIG_HELP.map((line) => `                          ${line}`).joi
                         shares this machine and is the only mode that needs no
                         tunnel. "expo" lets the Expo dev server tunnel itself.
                         "cloudflared" and "ngrok" name a managed provider
-                        explicitly. Any other value is refused as invalid.
+                        explicitly. "tailscale" explicitly selects a tailnet-only
+                        foreground serve process, never Funnel; "auto" never
+                        selects it. The device must share the tailnet. See
+                        \`guide metro\`. Any other value is refused as invalid.
   metro.ngrokUrl        the stable managed ngrok URL. It requires metro.tunnel
                         "ngrok" and passes --url to ngrok http. Stim owns
                         this process.
   metro.publicUrl       an existing tunnel's URL. Takes precedence over
                         starting one, whatever metro.tunnel says -- Stim
                         did not create it, so a Metro request through it is
-                        still gated the same way a managed tunnel's is. Set it
+                        still gated through a public bundle probe. Set it
                         before Expo start so the manifest advertises it.
+  metro.port            this workspace's Metro port, 1024-65535;
+                        STIM_METRO_PORT overrides it. Stim reserves this
+                        number instead of picking one from 8082 up, for a
+                        workspace whose tools already expect a port. A
+                        committed value suits a single checkout; give each
+                        worktree its own in the workspace layer or the
+                        environment. start refuses with STIM_BAD_ARG when
+                        another workspace reserves it or another process
+                        holds it. start, ios, android and web refuse a
+                        changed pin while this workspace's dev server runs
+                        (run stim stop before retrying) or its supervisor
+                        cannot be verified (stop it with the tool that
+                        started it). A foreign holder is refused before
+                        anything starts; this project's Metro on the pin is
+                        attached to. --no-metro-check uses the pin, then the
+                        recorded port, then 8081, without probing or reserving;
+                        an invalid pin still refuses.
   metro.warmupUrl       optional object with per-platform bundle URLs:
   metro.warmupUrl.ios
   metro.warmupUrl.android
@@ -6072,6 +7648,23 @@ ${ANDROID_AVD_CONFIG_HELP.map((line) => `                          ${line}`).joi
                         driven. Read
                         when \`start\` spawns the supervisor; see
                         \`guide metro\`.
+  devices.idleShutdownMinutes
+                        minutes an owned simulator or emulator stays idle
+                        (\`gc --idle\` conditions; an open stim-server viewer
+                        counts as activity) before its workspace's supervisor
+                        shuts it down, never deletes it. Default 0, never.
+                        Machine or project layers. Read when the supervisor
+                        starts; see \`guide lifecycle budget\`.
+  macos.product         the explicit Swift Package executable product built in
+                        Debug by stim macos
+  macos.infoPlist       development Info.plist relative to Package.swift,
+                        without shared URL schemes or an update feed
+  macos.arguments       string array passed directly to the executable;
+                        see stim guide macos for the prototype's limits
+  macos.assetCatalog    optional .xcassets directory relative to Package.swift,
+                        compiled into Contents/Resources before signing
+  macos.resources       map of Contents/Resources destinations to source paths
+                        relative to Package.swift; see stim guide macos
   web.url               the page \`stim web\` opens in the owned Chrome, an
                         http:// or https:// URL. {port:<label>} becomes the
                         workspace's named port (allocated like \`stim ports
@@ -6129,7 +7722,7 @@ ${ANDROID_AVD_CONFIG_HELP.map((line) => `                          ${line}`).joi
                         them from the environment or the machine layers.
 
 Each setting takes its documented type: string, array of strings, number,
-boolean, or object. ios.remote, android.remote, metro.tunnel, web.viewport,
+boolean, or object. android.remote, metro.tunnel, web.viewport,
 optimizations.android.compilerCache and optimizations.android.pch take only
 their listed choices. A value of the wrong
 type or outside those choices is refused by name on every command that resolves
@@ -6185,6 +7778,18 @@ overrides the file:
 budget is off. A value of the wrong shape refuses start, ios and android with
 STIM_BAD_ARG. See \`guide lifecycle budget\` for what each limit reclaims.
 
+AUTOMATIC MAINTENANCE IS MACHINE-LEVEL
+Report-only in this release: it measures and plans, and deletes or stops nothing.
+STIM_HOME and CI make the mode off unless STIM_MAINTENANCE is set.
+See \`guide cleanup\` for checks, plans and log paths.
+
+${SETTINGS.filter((setting) => setting.key.startsWith("maintenance.") || /^caches\..*MaxGb$/.test(setting.key)).map((setting) => `  ${setting.key}  ${setting.env}  ${setting.default === void 0 ? "unset" : `default ${setting.default}`}
+    ${setting.description}`).join("\n")}
+
+Maintenance uses the sysctl pressure level on macOS, with no memory signal
+when sysctl fails. os.freemem() and maintenance.minAvailableMemoryGb apply
+only on other platforms.
+
 THE IOS SIMULATOR APP IS MACHINE-LEVEL
 Top-level \`iosSimulatorApp\` in ~/.stim/config.json selects the macOS app that
 displays Stim's owned local iOS simulator after boot. It is not a project
@@ -6251,7 +7856,9 @@ to its app path for every command it starts.
 THE DEVICE POOL BOUNDS ARE MACHINE-LEVEL TOO
 \`pool.iosParkedMax\` caps how many parked simulators \`worktree remove\` may
 leave behind for a later workspace to adopt. It is machine-level for the same
-reason: the disk they sit on is the whole machine's, about 18 MB each once erased.
+reason: the disk they sit on is the whole machine's. A parked simulator keeps
+its apps and data, so it can hold gigabytes until \`stim gc --cache parked
+--delete\` erases it.
 
   {
     "pool": { "iosParkedMax": 3 }
@@ -6278,6 +7885,242 @@ test suites and the end-to-end harness use one -- and a scoped config must not
 leave simulators on the machine it cannot account for. A redirected home that
 wants a pool says so with the variable.
 
+DESKTOP ACCESS TICKETS
+Stim Desktop's Add wizard sets STIM_ACCESS_TICKET for one \`doctor --fix\`
+run. Agents never set it, never run \`stim-server setup\`, never edit
+\`offload.*\` or \`hosting.*\` for the user, and never approve requests.
+Stim sends the ticket (43 base64url characters) only in build and device-host access
+requests and stores only its SHA-256 ticketHash. With --fix, a still-pending
+request is replaced when its ticketHash is missing or differs from the current
+ticket; matching hashes and approved credentials are preserved.
+Approved doctor entries under buildMachines and deviceHosts include host
+{ name, screenRecording, accessibility } when the worker reports it.
+
+HOSTING MACHINES ARE MACHINE-LEVEL
+\`hosting.machines\` names Macs that may host owned simulator sessions,
+by MagicDNS name with an optional serve port (default 7443). Name each node
+and port once. This is separate from build offloading:
+
+  stim settings set hosting.machines '["janics-mac-mini"]'
+  stim doctor --fix
+
+Only \`doctor --fix\` asks for device-host access. A person on that Mac
+approves the printed id with \`stim-server devices grant <id> --device-host\`.
+A person can also run \`stim-server setup\` on the worker: one node, one ticket,
+one expiry, at most one request per capability, with per-grant y/N in a
+terminal or \`--yes\` otherwise. Agents never run \`stim-server setup\` or
+approve requests. Setup never changes TCC or enables Funnel; an SSH-driven
+run is not offered. Without a terminal or --yes, setup refuses before installing
+unless every chosen capability already has a matching approval. Desktop reuse
+requires an existing tailnet route. Ctrl-C or SIGTERM completes the journal,
+releases the setup claim and exits 1; a typed N also exits 1. Hosting grants
+include no read, control or build capability.
+$STIM_HOME/device-host-machines.json stores a private token and pinned tailnet
+node. Doctor never prints the token; it reports each machine under deviceHosts
+in JSON. Stim sends tokens only to the pinned node's own tailnet address,
+with its MagicDNS name for TLS and Host routing. A changed node refuses
+access, and uncertain replies or unreadable credentials preserve the pin.
+Invalid hosting settings report an error and preserve every saved credential.
+\`doctor --fix\` forgets entries removed from hosting.machines; remove a
+replaced machine, run it, then re-add the name to request a new approval.
+A definite revoked or lapsed request can be requested again with --fix.
+An in-progress approval inspection reports busy rather than replacing its
+pending token. \`stim macos --remote <machine>\` runs a macOS app on an
+approved machine (stim guide macos); \`ios\` and \`android\` do not yet
+place sessions on these machines. To view or control a hosted macOS app, a person
+on that Mac approves Screen & System Audio Recording and Device Control and Data
+Access (Accessibility on macOS 26 and earlier) for Stim Host, the app
+\`stim-server service install\` runs the server under.
+
+On a hosting Mac, \`hosting.agentDriver\` names the tool it starts so a
+client's coding agent can drive the macOS apps and iOS simulators it hosts for that client.
+The default, \`none\`, starts nothing. For macOS, \`agent-device\` starts its
+shared daemon only when that agent-device can lease a single app (its
+\`macos-app\` lease backend); otherwise agent control reports \`none\` with a
+notice, and no client is handed the Mac's desktop. STIM_AGENT_DEVICE_BIN in
+stim-server's environment names an agent-device binary to use instead of
+~/.local/bin/agent-device. Hosted iOS uses one daemon per simulator, pinned by
+its UDID policy; both Macs need agent-device 0.21.20 or later. See guide lifecycle
+hosted-ios. \`doctor\` on that Mac notes an installed hosted app that runs while
+the setting is \`none\`.
+
+BUILD MACHINES ARE MACHINE-LEVEL
+\`offload.machines\` lists the Macs on the tailnet that may build for this one,
+by MagicDNS name, each optionally with the port of its \`tailscale serve\`
+route (default 7443):
+
+  {
+    "offload": { "machines": ["janics-mac-mini"] }
+  }
+
+\`doctor --fix\`, run in any app directory, asks each named Mac for build access and pins its tailnet
+node in $STIM_HOME/build-machines.json. A person approves the request on that
+Mac with \`stim-server devices grant <id> --build\`; doctor prints the id.
+A person can instead run \`stim-server setup\` on the worker with a node,
+ticket and expiry, under the approval rule above. Build never includes read
+or control.
+Stim connects to a named Mac only while its name still belongs to the pinned
+node and never sends the token to another node. \`doctor\` reports each
+machine's pairing state and, for an approved machine, asks it for one build
+offer and lists every reason it would not take this app's iOS build: no
+answer, another Stim build, CPU, Xcode, simulator SDK or CocoaPods, no
+Bundler for an app whose Gemfile.lock pins CocoaPods, no iPhone simulator on
+the runtime \`stim ios\` builds for here, low disk, or busy. With Package.swift
+and no platform selection on a Mac, it also checks the macOS Xcode and SDK.
+
+\`offload.machine\` (machine scope, default auto) selects placement for
+\`ios\`, \`android\` and \`macos\`. \`--build-machine <auto|local|name>\`
+overrides STIM_OFFLOAD_MACHINE, which overrides the setting. A blank environment
+value is unset. Trimmed auto/local are case-insensitive. Machine names match
+configured names case-insensitively, with port 7443 when omitted; reports use
+the configured entry.
+
+  auto   follows offload.mode and keeps its local fallback behavior
+  local  builds only on this Mac for this invocation
+  name   requires a matching entry in offload.machines, already paired and
+         approved; ignores offload.mode and this Mac's load/slot gating
+
+A name never prompts for pairing, tries another machine or falls back here.
+Any refusal or failure is STIM_OFFLOAD_REFUSED with the machine and reason.
+Device, Release/non-Debug, --remote, Android CAS compiler builds, builds with
+the build cache off, and an unknown simulator runtime cannot build there and
+refuse on a cache miss. Invalid values, unlisted names and unpaired names refuse
+at setup before consulting the cache; they create no build record or failed-run
+stats. A listed paired name with a cache hit compiles nothing, contacts no worker
+and records buildMachine with builtOn absent. Build failures retain the selected
+value; builtOn is here or the configured machine entry when compilation ran.
+Prebuild and pod install still run on this Mac before a named offload. A refusal
+starts no local xcodebuild, Gradle or SwiftPM compile.
+Run stim doctor --fix to ask for build access if not paired. A person on the
+worker finds the id with stim-server devices and approves it with
+stim-server devices grant <id> --build, or runs stim-server setup there with
+the client node, ticket and expiry. Check stim settings get offload.machines,
+or rerun with --build-machine auto or --build-machine local. Ctrl-C cancels
+the remote build without a local xcodebuild, Gradle or SwiftPM compile.
+
+Copyable agent prompt:
+  Run stim ios --build-machine janics-mac-mini. If it refuses, report the
+  STIM_OFFLOAD_REFUSED reason and remedy; do not retry with another placement.
+
+With offload.machine auto, \`offload.mode\` decides where an iOS simulator Debug build or an Android
+emulator debug build or a stim macos SwiftPM Debug build compiles:
+
+  auto   (default) here while this Mac has capacity: a free
+         \`concurrency.maxBuilds\` slot (always, with no build limit) and a
+         load per core under \`offload.maxLoadPerCore\`. Otherwise on a
+         build machine that accepts the build and is expected to be faster:
+         while every slot here is busy, any machine that accepts; while only
+         the load is high, a machine whose load per core is lower than this
+         Mac's. A machine too old to report its load counts only while every
+         slot here is busy.
+  force  on a build machine whenever one accepts it
+  off    always here
+
+Load per core is the 5-minute load average divided by the CPU count; a Mac's
+native builds are its Stim runs in prebuild, pods or compile on that Mac, not
+the ones it offloaded.
+\`offload.maxLoadPerCore\` (default 2) is the load per core at which a Mac
+counts as saturated, both here and on a build machine.
+
+STIM_OFFLOAD_MODE overrides it for one command. Device, Release and
+\`--remote eas|proxy\` builds, Android builds with the Apple Clang CAS compiler cache,
+and iOS/Android runs with the build cache off, always build here. Hosted iOS
+Debug builds can use a separate --build-machine, targeting the hosting Mac's
+architecture and runtime.
+macOS uses matching Xcode and macOS SDK, with a per-client SwiftPM dependency
+cache on the worker. It skips JavaScript dependencies, prebuild and pods; see
+stim guide macos. macOS artifacts are not cached.
+An offloaded iOS/Android build first runs prebuild (and \`pod install\` for iOS) here,
+then asks every paired machine what it can build. It takes one whose Stim
+build matches this Mac and CPU matches the target simulator, with enough disk, that does not decline,
+preferring the one that already holds this repository, then the least loaded,
+and moves to the next one in that order when a machine that offered fails the
+sync or refuses to start the build.
+For iOS the machine's Xcode and simulator SDK must match, and it needs an
+iPhone simulator on the target runtime. Its CocoaPods must match too, unless
+the app's Gemfile.lock pins CocoaPods: both Macs then run that version through
+bundler, so the machine needs only Bundler on its stim-server PATH and
+installs the pinned gems itself on the first build. For Android its JDK major
+version must match, and its Android SDK must hold the NDK, build-tools and
+compile platform that the project's React Native version names in
+gradle/libs.versions.toml; Gradle and AGP come from the synced project. When
+no machine takes the build in auto placement, the run prints one line with each machine's
+reason, such as \`janics-mac-mini: busy (load at or above 2/core; load
+8.2/core, 2 builds) -> building here\`, and compiles here. It sends the files
+\`git ls-files -co --exclude-standard\` lists (the machine keeps only files it
+lacks, so an unignored secret such as \`.env\` is sent too), builds with
+Stim's own code there, refuses unless the fingerprint there equals this one,
+and brings the \`.app\` or APK back. An Android build there uses this Mac's
+variant, target ABI, Gradle build cache, PCH and compiler cache choices, so
+the APK matches the ABI-narrowed cache key. Stim checks the archive's sha256
+and fingerprints this checkout again before it stores the app under the
+post-mutation key and installs it the usual way, so an APK is still compared
+with the installed one before an install is skipped.
+While a machine builds, Stim pings it every 15 seconds and treats a minute of
+silence as a dropped connection while it waits for the build. When the
+connection drops without a close, Stim reconnects to the same pinned machine
+for up to 3 minutes and takes the running build back; the machine keeps it
+running for 5 minutes without a connection, then cancels it. With auto, a drop while the
+app is fetched still builds here. Interrupting the run with Ctrl-C closes the
+connection, which cancels the build there; a run killed another way, or
+interrupted while it reconnects, leaves it until those 5 minutes pass. With auto, a failure after a machine took the build prints \`offload failed: <reason>
+-> building here\` and compiles here. The run's lastBuilds entry and
+\`--json\` facts record the reason as offloadFallback. Offloading holds no
+local build slot; that fallback takes one. \`stim stats\` keeps where each
+compiling build ran and why (\`guide facts stats\`).
+An offloaded app lands only in this Mac's build cache, not in a remote cache
+provider. A project whose xcodebuild changes its own fingerprinted inputs
+fails the offload fingerprint check: auto builds here; a named placement refuses.
+
+On the build machine, stim-server keeps each client's checkouts, dependencies,
+DerivedData, compilation cache, ccache and Gradle home under
+\`offload.workerRoot\` (absolute; default $STIM_HOME/build-worker), one area
+and Stim home per client and repository, and one Gradle home per client. It
+runs one offloaded build at a time. It declines a build while that volume has
+less than 10 GB free, while its own native builds and the offloaded one fill
+its \`concurrency.maxBuilds\`, or while its load per core is at or above its
+\`offload.maxLoadPerCore\`, and reports the reason in its offer. It boots and
+installs nothing. While an offloaded build runs there, it holds one of that
+Mac's \`concurrency.maxBuilds\` slots, so a local Stim build there waits for it
+and counts it as busy; the slot is freed when the build ends, is cancelled or
+its process is gone. Android builds there run on the JDK in stim-server's
+JAVA_HOME (else the macOS default JDK) with the SDK in its ANDROID_HOME (else
+~/Library/Android/sdk). The client's Gradle daemon stays warm there for
+\`offload.gradleDaemonIdleMinutes\` (default 30; 0 stops it when each build
+ends; a new value applies from the next daemon) and never holds a build
+slot. While none of the client's builds runs, stim-server stops it sooner
+when a build is cancelled, the client is revoked, or the machine has less
+than 2 GB of memory available, and deleting the client's directory under the
+worker root stops it too.
+\`stim-server service install [--serve]\` on the build machine keeps stim-server
+running as a login LaunchAgent; \`--path-prepend <dir>\` and \`--env KEY=VALUE\`
+pin a PATH entry or variable such as a private CocoaPods that stim-server's
+login-shell environment would otherwise replace.
+\`stim-server service update --release <version>\` there moves the service to
+that exact stim-server release from the public npm registry once npm verifies
+its integrity and registry signatures; \`--from <dir>\` installs the packed
+packages of a checkout instead. It waits for offloaded builds and hosted
+sessions to finish, restarts the job, and switches back when the new server
+exits or does not answer within 90 seconds; \`stim-server service rollback\` returns
+to the previous server. A client Mac approved for builds or device hosting
+there can ask for the same update over its tailnet connection: an npm release
+always, and its own packed build only while \`server.acceptClientBuilds\` is
+true on that machine (default false).
+Replacing a loaded service waits up to 45 seconds for its existing listeners to
+release the port. Uninstall does not wait for the port. If stopping the old job
+or starting the new one fails, install restores the previous plist and attempts
+to restart a previously loaded LaunchAgent; if it cannot, it prints the
+launchctl bootout/bootstrap remedy. A running LaunchAgent does not prove readiness; check \`stim-server service status\`
+and its reported log. The server listens before it touches the Stim home; a
+read-only child process reads the Stim home, server and recording directories,
+and until it returns \`/health\` answers 503 with \`startup.state\` pending.
+A read that does not return within 10 seconds, plus up to one second to stop
+the child, leaves the server listening and degraded, with the reason in
+\`/health\` and \`stim-server service status\`, and no status followers,
+watchers, native helpers or recorder; it reads again every 30 seconds and
+serves once a read returns. It preserves claims and recordings; it does not
+restore an inaccessible volume or grant filesystem access.
+
 THE GC WORKTREE GRACE PERIOD IS MACHINE-LEVEL
 \`gc.worktreeGraceMinutes\` is how long \`gc --delete\` waits before it removes
 a merged or idle linked worktree. The clock starts at the worktree's latest
@@ -6294,6 +8137,25 @@ which overrides the file. Absent means 120. \`0\` removes a finished worktree at
 once. A value that is not a whole number 0 or more is warned about by \`gc\`,
 which then uses 120. See \`guide cleanup\` for what else keeps a worktree.
 
+DEVICE RECORDINGS CAN BE TURNED OFF
+stim-server records the screens of owned simulators, emulators and the
+Stim-owned Chrome page while an automation tool drives them or a paired client
+watches them, so the phone app can scrub back through them. It keeps the last
+15 minutes of footage per device under $STIM_HOME/workspaces/<id>/recordings/,
+on this Mac only, and serves it only to paired clients. \`recording.enabled\`
+turns it off:
+
+  stim settings set recording.enabled false --scope machine
+
+It is a boolean, true by default, set at machine, repo or workspace scope; the
+workspace layer wins, then repo, then machine. STIM_RECORDING (true, false, 1
+or 0) overrides every layer; stim-server reads it from its own environment when
+it starts. Turning it off takes effect at once: \`stim settings set\` deletes
+the recordings of every workspace it turns off, and stim-server stops recording
+them within seconds, as soon as \`stim status\` shows recording.enabled false
+for them. Turning it back on records from then on. See \`guide cleanup\` for
+how recordings are removed otherwise.
+
 STIM NEEDS NO PROJECT CHANGES TO RUN
 Nothing above is required to use Stim. The performance caches that used to
 be setup steps are supplied by Stim on the command lines it composes itself:
@@ -6649,11 +8511,28 @@ platform "web":
                page document is error whatever its
                status; another request's network failure or HTTP 5xx is
                error, a 4xx warn, a canceled request debug; browser messages such
-               as CSP violations; the browser's own lifecycle
+               as CSP violations; the browser's own lifecycle; in-app
+               route changes (history API or fragment) as web_route with
+               url, at most four a second
+  src agent    input a DevTools client other than Stim's sent to the page
+               while connected, as agent_action with driver (the tool),
+               command click, type, press or scroll, msg (e.g. 'Clicked
+               button "Save"', "Typed 12 characters into input#email"),
+               deviceId (web.targetId) and details. Typed text is never
+               recorded, only its length. Clicks, key presses, text input
+               and wheel scrolls in the top frame are observed; pointer
+               moves and iframes are not, and a typing, key or scroll burst
+               is one record. Input from Stim Desktop's or the phone's Take
+               over is not recorded, nor is other input within 3 seconds of
+               it, nor input while no other client is connected. A person
+               clicking a headed window while a tool is connected counts as
+               that tool, and a script that disconnects within a few hundred
+               milliseconds of its first input goes unrecorded
 Expo also prints web console calls on Metro ("Web LOG"), so they can appear
 twice: once from the page (client), once from Metro (metro, level info).
 Each load of the page's top-level document is a page-load marker: stim web,
-stim reload, and a reload or navigation the page makes itself. logs --errors
+stim reload, and a reload or navigation the page makes itself. A reload's
+marker carries reload: true. logs --errors
 and the status error count report the page's records (platform web) from the
 latest load only, the way Chrome DevTools clears its console when the page
 navigates. A page load does not hide the native app's errors, and an ios or
@@ -6669,7 +8548,20 @@ them start their own browser:
 The port reaches only the Stim profile: Chrome refuses remote debugging on
 your default profile, and Stim never attaches to a browser it did not start.
 The port is managed like metro: stim ports lists it as web-cdp (managed),
-and ports get, stop and release refuse it.
+and ports get, stop and release refuse it. While a tool is connected,
+status reports it as the browser's driver (web.activity, "driven by
+playwright"), the way it names agent-device on a simulator, and its clicks,
+typing and scrolls are agent actions: stim logs --source agent lists them,
+web.activity.recent["agent-action"] dates the newest, and Stim Desktop and
+the phone show them in the Web device's agent feed. web.targetId is the
+owned page; a tab another tool opens is not captured.
+
+stim status also reports the document the page loaded last and how that
+load went: web.page { url, state: loading | loaded | failed, error?, route? }.
+route is the URL the page shows after an in-app route change since that
+load, and is absent when none moved it. A failed
+load (the dev server is down, a certificate error, a crash) shows on status's
+web line.
 
 OWNERSHIP AND CLEANUP
 
@@ -6689,10 +8581,390 @@ which would otherwise block the next launch. status reports
 browser-unverified when an identity cannot be proven; follow stim guide
 errors teardown.
 
+STIM DESKTOP
+
+Stim Desktop shows the owned Chrome as a Web tile next to the simulators,
+with live frames of the page read from its DevTools endpoint, the page's URL,
+a "Page failed to load" pill and "Driven by" when a tool is attached. Take
+over sends clicks, scrolls and keys to the page. The tile's buttons open the
+URL in your own browser (never the Stim profile), run stim reload web, and
+close the browser with stim stop --slot web.
+
+THE PHONE APP
+
+The phone app shows the page as a Web tile in the devices grid and the
+workspace screen, and opens it in the device viewer as H.264 video through
+stim-server. With Control on, taps click, drags scroll and the keyboard types;
+Back goes back in the page's history. Reload in the workspace menu runs stim
+reload web. While stim-server recorded the page (\`guide settings\`, device
+recordings), the viewer can scrub back through it, with the agent's actions
+as markers.
+
 LIMITS
 
-Chrome and Chromium only. No Stim Desktop or phone viewer yet. The owned page
-is one tab: a page the app opens in a new window is not captured.`
+Chrome and Chromium only. The owned page is one tab: a page the app opens in
+a new window is not captured.`
+	},
+	macos: {
+		summary: "Swift Package macOS Debug apps: owned bundle, logs, local window viewing, and --remote on another Mac",
+		body: () => `MACOS: SWIFT PACKAGE DEVELOPMENT PROTOTYPE
+
+If Stim is not installed globally, replace stim with npx stim.
+
+ios --remote <machine> shares hosting.machines and its separate device-host
+approval. Read guide lifecycle hosted-ios for simulator placement and Metro.
+
+Run from the directory containing Package.swift. This prototype builds one
+explicit executable product in Debug, creates an isolated development app,
+and launches it. It does not use package scripts, Metro, simulators, Xcode
+projects, release builds, provisioning, or store distribution.
+
+Set macos.product and macos.infoPlist explicitly in .stim.json. Optional
+macos.arguments is an array of arguments passed directly to the executable:
+
+  { "macos": { "product": "MyApp", "infoPlist": "Support/Info-Development.plist" } }
+
+The plist must contain CFBundleIdentifier and CFBundleExecutable matching the
+product. Use a development plist without shared URL schemes or an update feed.
+Stim gives the copied bundle a workspace-specific identifier. SwiftPM resource
+bundles and frameworks in the reported build directory are copied into it;
+macos.resources maps destinations under Contents/Resources to file or directory
+sources relative to the Swift Package directory, for example:
+
+  { "macos": { "resources": { "AppIcon.icns": "Support/AppIcon-Dev.icns" },
+               "assetCatalog": "Support/Assets.xcassets" } }
+
+macos.assetCatalog selects an optional .xcassets directory compiled by fixed
+xcrun actool arguments. Copies and the compiled Assets.car are added before
+ad hoc signing. If actool does not emit Assets.car, staging refuses; set
+LSMinimumSystemVersion in the plist when Xcode requires a deployment target.
+Destinations are non-empty relative paths without empty, . or
+.. segments, at most 1024 characters, and cannot overlap another resource,
+Assets.car when a catalog is set, or a SwiftPM resource bundle. At most 256
+resources are allowed. Sources must exist as regular files or directories;
+their realpaths must stay inside the git repository root, or the Swift Package
+directory when there is no git root, and a source directory cannot contain
+symbolic links. Sources can use ../ to reach other files
+inside that repository. Custom packaging scripts are not run and extra
+executables, including Stim Desktop's sim-fold helper, are not built.
+
+  stim macos              # fixed SwiftPM Debug build, then launch
+  stim macos --json       # one launch record; progress goes to stderr
+  stim status --json      # environments[].macos and build state
+  stim logs --source build
+  stim logs --errors
+  stim stop               # stop this workspace's owned app and supervisor
+
+Each invocation stops its previous owned app, rebuilds and launches. SwiftPM
+keeps incremental outputs in the workspace's runtime directory under STIM_HOME.
+Local stim macos starts the app in the background without activating it or
+changing focus: it sets STIM_BACKGROUND_LAUNCH=1 in the app's environment, which
+Stim Desktop honors. An app that activates itself at launch still takes focus.
+Hosted launches (macos --remote) do not set it.
+macOS artifacts are not cached. This prototype has no --plan, --slot, or reload command.
+A failed build records its error and compiler output without launching an app.
+Runtime stdout and stderr become client records; build output becomes build
+records, all with platform "macos". Unexpected app exits are error records.
+Stim runs the app with NSUnbufferedIO=YES, so Swift print output arrives per
+line instead of when the app exits.
+
+BUILD OFFLOAD
+
+--build-machine <auto|local|name> overrides STIM_OFFLOAD_MACHINE and the
+machine setting offload.machine (default auto). local builds here; a name
+requires the matching configured and paired build machine, ignoring offload.mode
+and this Mac's capacity. Any failure is STIM_OFFLOAD_REFUSED without a local xcodebuild, Gradle or
+SwiftPM compile or another machine. Invalid, unlisted or unpaired selections
+refuse before stopping the app or changing its build record. See stim guide errors STIM_OFFLOAD_REFUSED.
+
+With offload.machine auto, offload.mode places these SwiftPM Debug builds:
+auto builds here while this Mac has capacity, force uses an approved build
+machine when one accepts, and off always builds here. Configure offload.machines
+and approve build access as described in stim guide settings. The worker needs
+matching Stim, CPU architecture, Xcode and macOS SDK, plus network access to
+fetch package dependencies the first time. It keeps SwiftPM dependencies in a
+per-client cache and incremental outputs per repository. It runs fixed swift
+build commands without JavaScript installs, prebuild or pods. It receives only
+the files git lists (tracked and untracked, not ignored). Resource and catalog
+sources must be among those files. The client sends resolved sources relative
+to the repository root; the worker resolves them inside its checkout.
+
+The client validates the development plist and resource entries before asking a machine. It verifies
+the returned archive's sha256, bundle identifier, executable, declared resources
+and ad hoc signature
+before replacing the owned bundle, then launches locally as usual. With auto, every offload
+failure falls back to the local build, including force. Failed staging preserves
+the previous bundle. No failed artifact is promoted or cached. The build record
+is unchanged by invalid, unlisted or unpaired setup refusals. It
+carries buildMachine (selected) and builtOn (here or the machine, absent until
+a build runs), and errorCode on a typed failure. It carries offloadedTo only for a remote build, and offloadFallback when an offload
+attempt falls back here. Placement and failure reasons are in build logs.
+
+OWNERSHIP AND LOCAL VIEWING
+
+The supervisor owns a process-identity claim with the app as its child. Stop
+signals only verified recorded identities. An unverifiable or malformed owner
+refuses with STIM_MACOS_OWNER_UNVERIFIED; other apps remain untouched.
+
+Stim Desktop shows this app in its workspace, with Build and run, Open app (local
+apps only) and Stop, and a live preview that updates itself while the app runs. Capture and Open app verify the recorded executable, bundle
+identifier, PID and process start time. Open app rechecks that the captured window
+is still the app's front window, or raises the pinned one, then activates that
+owned app for normal native input.
+The preview follows the app's front standard window, its main window with any
+attached sheet, as the app opens, switches, closes or resizes windows. It never
+captures another process's windows, menus or the desktop. Without Device Control
+and Data Access permission (Accessibility on macOS 26 and earlier) Stim cannot
+tell which window is in front, so the preview shows only an app whose one window
+contains the others. The viewer never captures its own process recursively.
+The captured view is read-only; background mouse/keyboard relay is not included.
+
+Capture requires existing Screen & System Audio Recording permission (Screen
+Recording on macOS 14); Open app also requires Device Control and Data Access
+permission (Accessibility on macOS 26 and earlier). The first native viewer opening
+shows one Desktop setup screen for both permissions, named for this Mac's macOS
+version, with statuses, Request permissions, Settings and Check again. Settings
+opens the matching System Settings > Privacy & Security pane. You approve normal macOS requests; Stim never resets or grants access
+automatically. Permissions on the app card reopens setup. Builds never prompt.
+If unavailable, use the normal app window and
+read the workspace logs.
+
+PHONE VIEWING AND CONTROL
+
+A paired phone shows native app and build state in the workspace and home list.
+Tap the app tile to view the app's front window through stim-server. The server
+requires read access and its macos-window feature; it rechecks the recorded PID,
+process start time, executable and bundle before capture and on every frame.
+It never captures the desktop or another application, and offers no replay.
+The view follows the app's front standard window like the Desktop preview. A
+server advertising macos-windows also sends a macos-windows event on the frames
+subscription with the captured window and the app's windows (id, title and frame
+in points), after subscribing and whenever they change. Viewing starts only with
+an open window; after the app closes its last one the view reports a delay until
+another opens.
+
+WINDOWS
+
+The view follows the app's front window by default. A controller can pin it to
+one of the app's windows instead: with a server advertising macos-window-select,
+input.window { session, window: <id from macos-windows> } brings that window to
+the front of the app, and capture and input stay on it while another window
+comes forward on the Mac. input.window { session, window: null } follows the
+front window again. The pin also ends when its window closes or minimizes, or
+when the Control session that set it ends for any reason, including release,
+takeover, disconnect and the five-minute idle timeout, since viewers without
+Control cannot unpin; macos-windows reports pinned true while it holds. Choosing
+a window while the app shows a modal dialog, or one that just closed, is dropped
+without ending Control. The phone's Control toolbar and Stim Desktop's app card and
+hosted viewer offer the same choice as a Window menu: Follow front window, or a
+window by title. Stim Desktop's local preview pins without Control because it
+only raises the window among the app's own windows. An agent that drives the app
+through the stim-server protocol sends the same input.window.
+
+A server advertising macos-window-control also supports the phone's Control
+mode on a control pairing. Tap/click and drag act on the displayed window;
+Scroll mode turns a drag into pixel scrolling. The main toolbar offers Keyboard
+and Scroll. Keyboard types printable ASCII and attaches an extra-key strip with
+Tab, Escape, Backspace, arrows and labeled Select all, Undo, Save, Copy, Paste,
+Cut and Find shortcuts. Shift, Control, Option and Command apply to the next
+supported key, then clear; dismissing the keyboard clears them too.
+
+A newly built phone client with Keyboard Controller is required; this native
+change cannot be delivered to an older client by a JavaScript update. Servers
+advertising macos-keyboard-extended accept modified a-z and 0-9 one key at a
+time. Older servers retain fixed shortcuts and navigation but cannot receive
+other modified letters or digits. Multi-character modified input and symbols
+are not supported; ordinary typing keeps using input.text.
+
+Shortcuts for a-z and 0-9 use the key that types the character in the Mac's
+current keyboard layout, using the Command layer when Command is held. Dvorak
+and Dvorak-QWERTY Command are supported. On Russian and similar layouts
+(Cyrillic, Greek, Hebrew, Arabic), Latin-letter shortcuts work with Command;
+Control-only or Option-only letter shortcuts are refused. With Control, the
+layout's Control table must also yield the requested character or, for letters,
+its C0 control character; otherwise the shortcut is refused. The Mac's selected
+input source is read on each key, so switching layouts takes effect on
+the next key. Letters and digits available only with Shift or Option, or through
+a dead key (for example digits on AZERTY), are refused with a reason naming the
+layout, and Control ends. Stim does not add modifiers to reach those characters.
+Ordinary typing and navigation do not depend on the layout. Symbols such as
+comma remain unsupported key names.
+Control posts input to the owned process without activating it or raising its
+window; only choosing a window to pin raises it among the app's windows. Only when the captured window is not the app's key window (or its
+attached sheet) does Stim activate the app to deliver input, waiting up to one
+second for focus. The helper then sends a controlActivated notice, which stim-server
+logs.
+Clicks on views that reject the first mouse, such as custom views and SwiftUI
+onTapGesture regions, do not land while the app is in the background. Use
+Desktop's Open app to bring the app to the front for those views.
+Control holds one exclusive server session per owned app, ends on disconnect,
+revocation, takeover or five minutes without input, and does not take a CLI
+simulator/device lock. Each action rechecks the exact owned process and that the
+captured window is still the app's front standard window, or the pinned one. The
+app's other windows are allowed; input goes to the captured window, and a sheet attached to it takes
+focus and pointer input. Input that arrives while the view moves to another
+window is dropped and Control continues. A modal dialog window refuses input. A
+sheet larger than the captured window is not supported. Existing Device
+Control and Data Access permission (Accessibility on macOS 26 and earlier) is
+required. The phone and server never request or reset it. A refusal ends Control
+with its reason while viewing and logs remain usable. Older servers remain
+view-only.
+Native Control uses dynamically resolved private CoreGraphics input SPI in the
+server helper, outside the phone and Mac App Store app binaries. A missing symbol
+or incompatible macOS version refuses Control while viewing and logs remain usable.
+
+The existing capture host needs Screen & System Audio Recording permission (Screen
+Recording on macOS 14). If capture is denied,
+open Permissions in Stim Desktop on the host Mac, approve its normal OS requests
+and reconnect the phone viewer. The Desktop host presents setup on the first
+native viewer opening, including one initiated by the phone. A server started
+outside Desktop uses that launching host's permissions; granting this copy of Stim
+may not apply to it. The server never requests or resets permissions. Status and logs still work. Tap the build card for
+SwiftPM output or the logs card for native runtime stdout and stderr. Metro is not
+used.
+
+ON ANOTHER MAC
+
+stim macos --remote <machine> builds the Debug app on this Mac and runs it on an
+approved hosting Mac over the tailnet, without SSH. The machine must be listed
+in hosting.machines and approved: stim doctor --fix asks it, a person on that
+Mac runs stim-server devices grant <id> --device-host or stim-server setup
+with that client node, ticket and expiry (guide settings), and stim doctor then
+records the approval. Stim connects only to the machine's pinned tailnet node.
+A refusal or an unreachable host fails the command; it never launches here
+instead.
+
+The --remote value is a hosting Mac name from hosting.machines. macOS refuses
+eas and proxy because it has neither backend. It also refuses auto until
+automatic placement ships. These reserved names are case-insensitive and
+trimmed; they refuse with STIM_BAD_ARG before state access or a connection.
+
+Logs: the host records the hosted app's stdout, stderr and exit like a local run.
+stim logs, including --errors, --json and --follow, asks the host over the same
+approved connection, copies the records it has not copied yet into the
+workspace's logs/macos-host.ndjson and prints them with the local records.
+stim stop copies the last ones, including the exit record, before it forgets the
+placement, so the logs stay readable after stop. A host that cannot answer, because
+it is unreachable or runs a stim-server that predates this, costs one stderr
+warning (after up to 10 seconds of connecting); stdout still carries the records already copied, so logs --json stays
+valid NDJSON. The host's unified log is not collected: os.Logger output that is
+not written to stderr does not appear.
+
+Phones and Stim Desktop view and control the hosted app through this Mac's
+stim-server, which relays to the host. Hosted iOS simulator tiles use the same
+relay and show on <machine>; see guide lifecycle hosted-ios. The phone sends clicks, scrolls,
+text and keys; Stim Desktop's Control sends clicks, drags and typed text.
+
+  stim macos --remote mini          # build here, deliver, launch on mini
+  stim macos --remote mini --json   # { platform, product, launchId, build, host }
+  stim status --json                # environments[].macos.state and macos.host
+  stim stop                         # stop the session on mini and confirm it
+  stim worktree remove <path>       # also stops it
+
+The copy keeps the plist's own CFBundleIdentifier. The host runs it as
+<id>.hosted<slot> from a fixed slot pool, so the bundle id stays the same
+across rebuilds; whether macOS keeps the permissions the hosted app asks for
+itself also depends on how the host signs it. Running the
+command again reuses the session and delivers a new copy. macos.arguments are
+passed to the hosted launch as plain arguments, without environment injection:
+at most 32 arguments, 1024 characters each and 8192 characters total. Empty
+strings are allowed; NUL, CR and LF are refused. Values are stored in the host's
+app receipt and visible in process listings, so do not put secrets there. Older
+hosts ignore them and Stim warns to update stim-server on the host.
+status --json reports the host's applied arguments under
+environments[].macos.arguments.
+A workspace has one macOS app: a local stim macos
+refuses while it runs on a host, and --remote with a different machine refuses
+until stim stop. When the host cannot be reached or does not confirm the stop,
+the placement stays recorded; restore the connection and run stim stop again.
+
+Viewing and controlling the hosted app from a phone needs Screen & System Audio
+Recording and Device Control and Data Access (Accessibility on macOS 26 and
+earlier), granted once on the host to the app that runs stim-server, not to the
+hosted app. stim-server service install runs the server under the signed Stim
+Host app (dev.stim.host, installed in ~/Applications) and shows
+macOS's own requests on that Mac's screen; a person there approves them.
+stim-server service status shows the grants, and stim doctor here reports an
+approved host that lacks them. A server started by Stim Desktop uses Desktop's
+grants.
+
+Hosted delivery carries the staged bundle with declared resources and compiled assets.
+When offload built it on the host's own tailnet node, the host copies the files
+from the build it kept for this Mac instead of receiving them again, admitting
+only bytes that match the bundle's digests here. That needs both the build and
+the device-host approval for this Mac. Files the host cannot take, an older
+host, or a build fetched more than 10 minutes earlier are uploaded as before.
+
+status --json reports macos.host { machine, session, appSlot, appAttempt,
+bundleId, agent }. For hosted placements only, status asks the host for the
+session state with about a 3 s timeout per connection and request and a 10 s
+cache. It reports stopped when the host says the session stopped, for example
+after a stim-server restart there, and unverified when the host is unreachable
+or cannot confirm. Run stim macos --remote <machine> to launch a stopped app
+again, or stim stop to clear or reconcile the placement. The host field stays
+in status --json for cleanup.
+While a placement is recorded, gc treats the workspace as in use. agent says
+how a coding agent drives the app: { driver: "none", setting:
+"hosting.agentDriver" } until the hosting Mac's owner sets that setting there,
+or { driver: "agent-device", remoteConfig, command }. remoteConfig is a mode
+0600 file in the workspace directory that holds the credential; run the command
+it names and never print the file. stop, worktree remove and gc first run
+agent-device close and disconnect for the connection that agent-device reports
+as connected to that remote config (the default or active session), then delete
+the file, so the next hosted workspace needs no manual disconnect. Any other
+connection, including one under another session name, stays untouched, and a
+failure or a missing agent-device is reported without blocking the stop. When
+the hosted session ends, stim-server removes its agent-device session
+directories under its own state directory. Start with agent-device open
+<bundleId> --remote-config <path>, using macos.host.bundleId; the lease allows
+open, close, snapshot, wait, find, get, is, click, fill, press, type, focus,
+scroll, screenshot and batch on that app only. The agent-device on this Mac must
+know the macos-app lease backend. A request outside that command list, or a
+method the relay does not forward, is refused with an agent-device UNAUTHORIZED
+error whose details.reason is STIM_AGENT_REQUEST_REFUSED and whose message names
+the refused command or method; do not retry it.
+
+Agents that built, launched and drove test copies on another Mac with an SSH
+script such as mini-desktop.sh use these instead:
+
+  script command             stim
+  build                      stim macos --remote <mac>
+  launch                     the same command; the host launches it under the
+                             session's own home
+  shot <out.png>             agent-device screenshot --remote-config <path>
+  click, rclick, key, type   agent-device click, press or type --remote-config <path>
+  quit                       stim stop (verified stop; the host frees the slot
+                             and removes the app's defaults)
+  clean                      stim worktree remove
+  3 concurrent slots         concurrency.maxDevices on the host; one bundle id
+                             slot per session
+
+The agent-device rows work once the host's agent field names agent-device.
+
+DESKTOP DOGFOOD
+
+This repository's apps/desktop/.stim.json selects the full StimDesktop app,
+its development plist, asset catalog, fonts, branding and licences. Its sim-fold
+helper is not built. It monitors the regular Stim home alongside the installed
+app, with a workspace-specific bundle identifier and separate preferences.
+Its launch arguments disable automatic cleanup and notification alerts in this development copy.
+Use Window > SwiftUI Playground for in-memory production screen fixtures.
+
+  cd apps/desktop
+  stim macos
+  stim logs --source build
+  stim stop
+
+When using an unreleased CLI from this repository, build the packages first and
+set STIM_BIN to the absolute packages/stim-cli/dist/cli.mjs path before running
+that executable's macos command. The development app inherits this CLI override;
+the installed app's CLI preference and running server remain unchanged.
+
+Ask an agent: "In my Swift Package app, configure the executable product and a
+development Info.plist for stim macos. Build and show its owned window in Stim
+Desktop, verify a source edit and readable failed-build logs, then stop only
+this workspace's app. Do not change permissions or use custom build scripts."
+`
 	}
 };
 //#endregion
@@ -6774,7 +9046,7 @@ function renderIndex(version) {
 	return lines.join("\n");
 }
 function guideCommand(program, version, status = (running) => guideStatus({
-	projectRoot: findProjectRoot(process.cwd()),
+	projectRoot: findProjectRoot$1(process.cwd()),
 	running
 })) {
 	program.command("guide [topic] [section]").description("Print reference documentation for THIS version of Stim (topics: " + topicNames().join(", ") + "). A topic with sections prints its section index; name a section to print only it, e.g. `stim guide errors STIM_NO_METRO` or `stim guide lifecycle builds`. Generated by the binary, so it cannot drift from the installed CLI.").action(async (topic, section) => {