stim 1.13.0 → 1.15.0

package/dist/{guide-BfZ0OmiP.mjs → guide-cCSGRFd3.mjs}

@@ -1,7 +1,7 @@
-import { a as findProjectRoot } from "./project-DGeclhvO.mjs";
-import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-xB0Frkg6.mjs";
-import { t as RECENT_LAUNCH_MS } from "./status-sszP4XKU.mjs";
-import { t as guideStatus } from "./guide-status-BaMYu55M.mjs";
+import { a as findProjectRoot$1 } from "./project-CV3tDFHl.mjs";
+import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-CduVcoxj.mjs";
+import { t as RECENT_LAUNCH_MS } from "./status-l84Gbvp2.mjs";
+import { t as guideStatus } from "./guide-status-CIoWK6mG.mjs";
 import { SETTINGS_SCHEMA_URL } from "@stim-cli/core/state";
 import chalk from "chalk";
 //#endregion
@@ -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
@@ -34,18 +38,17 @@ MULTIPLE DEVICES
 Use ios/android --slot <name> to retain multiple devices in one workspace,
 including several of the same model. Reuse the same slot name on subsequent
 runs. Read guide lifecycle options for the complete slot workflow. Use the
-reported device ID for UI interaction. All slots share Metro; reload can reach
-multiple devices, and a shared bundle request does not prove a slot launched.
+reported device ID for UI interaction. All slots share Metro and reload can
+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.
 
 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
@@ -75,7 +78,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
@@ -83,6 +87,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
@@ -104,6 +114,9 @@ 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.
 
+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
@@ -160,10 +173,11 @@ RULES DURING THE LOOP
   the error screen remains, follow the printed reload remedy instead of
   running ios or android again. If launch says FATAL because the app process exited,
   fix the crash and run the platform command again; Metro cannot restart it.
-- ios and android install the app, launch it, and check readiness. Trust the
-  exact device, app, Metro, and launch facts in the final summary. Use the full
-  reported device ID. Never assume a simulator named booted belongs to this
-  workspace.
+- ios and android install the app, launch it, and check readiness. A running
+  copy of the app is stopped and launched fresh, so in-app state does not
+  survive the run. Trust the exact device, app, Metro, and launch facts in the
+  final summary. Use the full reported device ID. Never assume a simulator
+  named booted belongs to this workspace.
 - After each ios or android run, give the user one compact result: exact device,
   app id, launch state, cache result, total duration, and whether stim logs
   --errors passed. Include a remedy only when action remains. Do not repeat the
@@ -195,10 +209,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
@@ -283,6 +298,7 @@ Read the matching guide before acting in these situations:
 | Web app in an owned Chrome (stim web)                 | stim guide web                   |
 | Web or API server ports                               | stim guide ports                 |
 | Remote device, custom Metro, or tunnel                | stim guide metro                 |
+| Metro stopped and no one ran stim stop                | stim guide metro                 |
 | Cache miss, bypass, or fingerprint exclusions         | stim guide lifecycle builds      |
 | Capacity limits                                       | stim guide lifecycle concurrency |
 | budget lines, reclaimed field, or low disk            | stim guide lifecycle budget      |
@@ -295,8 +311,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                |
 
@@ -325,12 +344,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: {
@@ -357,9 +378,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:
@@ -389,6 +414,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
@@ -406,7 +471,34 @@ 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",
@@ -418,6 +510,11 @@ per session, with the preview URL.`,
   mode            "bare-inproc" | "expo-child" | null (see \`guide metro\`)
   logsDir         where the NDJSON timeline is written
   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 ios --json
 
@@ -468,7 +565,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
@@ -487,6 +589,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 }
@@ -585,7 +696,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
@@ -627,7 +739,8 @@ 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
   durationMs      wall time for the whole run
   reclaimed       present only when the run was over its disk or memory
@@ -644,6 +757,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
 
@@ -656,7 +771,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.
@@ -674,6 +790,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
 
@@ -689,6 +808,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\`)
@@ -696,6 +817,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
 
@@ -716,6 +838,36 @@ 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? }
+                  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\`.
+  buildMachines   one { machine, state, dnsName?, deviceId?, requestedAt?,
+                  offloadable?, reasons?, problems?, capacity? } 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". 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
 
@@ -738,7 +890,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:
@@ -788,12 +941,44 @@ RULES
   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
+  unrelated schemes remain unapproved. The approvals persist
+  until the simulator is erased, so Stim records the ones it
+  wrote on the workspace's device record and writes only the
+  ones missing from it. Parking drops the record, so an
+  adopted simulator gets them again 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
@@ -805,8 +990,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
@@ -853,7 +1038,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
@@ -868,7 +1053,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
@@ -881,7 +1066,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
@@ -895,10 +1081,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 }
@@ -952,10 +1141,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
@@ -973,6 +1164,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";
@@ -996,14 +1191,47 @@ 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
     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
@@ -1015,6 +1243,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 |
@@ -1029,26 +1260,96 @@ 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
 
+  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
+  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
@@ -1068,8 +1369,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
@@ -1082,20 +1383,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
@@ -1103,25 +1429,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\`).
 
@@ -1140,6 +1487,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
@@ -1148,15 +1505,48 @@ 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\`).
+  Whenever nothing serves the port, metro also carries lastStop when the cause
+  is known, one of:
+    { reason: "idle", at, idleMinutes }
+    { reason: "requested", at, by, byPid, byWorkspace? }  a Stim command
+    { reason: "signal", at, signal }        a signal no Stim command sent
+    { reason: "server-exited", at, mode, code, signal }
+    { 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, 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
@@ -1164,30 +1554,98 @@ 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
+  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
@@ -1208,10 +1666,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.
@@ -1231,23 +1722,108 @@ 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:
+
+  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,
@@ -1269,14 +1845,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: {
@@ -1299,7 +1880,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
@@ -1326,12 +1909,19 @@ 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>, ...] } }
 
   \`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.
 
 HOW A RUN IS COUNTED (\`stats\`)
@@ -1353,7 +1943,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.
@@ -1374,7 +1965,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\`)
+  While at least one build machine is paired, every run that compiles
+  records where it built and why, in a placement: { at, project, platform,
+  decision, reason, machine?, buildMs?, localEstimateMs?, failed? }.
+  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.`
 			}
 		}
 	},
@@ -1398,10 +2012,33 @@ 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
+Plain \`stim start\` is local and does not create a tunnel. Remote intent
 comes from \`start --remote\`, \`ios.remote\`, or \`android.remote\`. The
 \`metro.tunnel\` setting selects the provider after remote intent exists.
 
+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
@@ -1429,7 +2066,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
 
@@ -1440,6 +2077,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
@@ -1454,7 +2097,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
@@ -1505,13 +2158,56 @@ 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
   is read when \`start\` spawns the supervisor; a value that is not a whole
   number of 0 or more is refused, as \`stim settings set\` refuses it.
 
+  WHY IT STOPPED: a supervisor that stops its dev server writes a
+  supervisor_stopped line (supervisor_idle_stopped for an idle stop) whose
+  stop field and message give the cause, and records the same cause as
+  devServerStop in state.json. A dev server that failed to start is
+  supervisor_failed instead. Plain \`status\` prints it after "not running"
+  while the workspace keeps its port (\`stim stop\` releases the port, so its
+  own stops show only in the log).
+    requested      a Stim command stopped it and says which: stim stop,
+                   stim worktree remove, stim gc --delete, stim start
+                   --reset-cache, or budget reclaim (with the workspace whose
+                   ios, android or start run reclaimed it)
+    signal         a SIGTERM or SIGINT with no Stim stop request recorded,
+                   so it likely came from outside Stim (level warn)
+    server-exited  the dev server exited on its own (level error). Expo CLI
+                   also exits 0 when it gets SIGTERM, so "exit code 0" with
+                   no request usually means something outside Stim signalled
+                   the Expo process
+    idle           metro.idleStopMinutes, above
+  A supervisor killed with SIGKILL, or one that crashed, cannot write
+  anything; neither can one whose state file was not writable. The next
+  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
@@ -1572,7 +2268,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
@@ -1653,10 +2356,15 @@ 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)
+  --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 (one or more), or all.
                    An unknown value is REJECTED rather than quietly matching
                    nothing.
@@ -1670,7 +2378,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
@@ -1720,9 +2433,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
@@ -1765,9 +2488,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
@@ -1876,9 +2602,9 @@ WHAT WRITES WHAT
                        console-only; missing reports or symbols are not proof
                        of a healthy app. No symbol downloads are performed.
                        Android may keep a crashed Java PID alive behind its
-                       crash dialog. Follow the app-scoped force-stop remedy
-                       printed by android after fixing the crash, then rerun
-                       stim android. Metro reload alone cannot recover it.
+                       crash dialog. Fix the crash, then rerun stim android,
+                       which force-stops that process before launching. Metro
+                       reload alone cannot recover it.
 
                        The connection refusal \`TCP Conn ... Failed :
                        error 0:61 [61]\` (61 is ECONNREFUSED) is not even
@@ -1925,13 +2651,17 @@ 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                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) 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
@@ -2128,8 +2858,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
@@ -2243,6 +2977,37 @@ 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.
+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",
@@ -2574,13 +3339,14 @@ so a Debug run on one is wired to a LAN origin instead of localhost.`,
 "this project's sim is X, but --device-type asked for Y"
   The project already owns a simulator of a different model, and Stim will
   not silently boot a different one. Reap it (\`worktree remove\`, or
-  \`gc --delete\`) and run \`stim ios\` again to create the requested model.
-  That loses the old sim's app state.
+  \`gc --delete\`) and run \`stim ios\` again to create the requested model,
+  which loses the old sim's app state, or pass \`--slot <name>\` to create it
+  beside the current one. The \`remedy\` field in \`--json\` names the same
+  choices.
 
 "this project's sim runs iOS X, but --runtime asked for Y"
   The same refusal for an explicit \`--runtime\` that names another installed
-  iOS version than the project's sim runs. Reap the sim the same way, or pass
-  \`--slot <name>\` to create one on the requested runtime beside it. The
+  iOS version than the project's sim runs, with the same remedy. The
   ios.runtime setting alone never refuses; it applies at creation.
 
 "this project's emulator uses device profile X, but Y was requested"
@@ -2719,6 +3485,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",
@@ -2748,6 +3526,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
@@ -2812,6 +3591,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.`
@@ -2935,10 +3719,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\`, 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 a remote run (\`--remote\` or ios.remote; the remote 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
@@ -2958,7 +3754,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
@@ -2972,6 +3771,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
@@ -3085,6 +3890,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
@@ -3138,6 +3953,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.
@@ -3268,9 +4087,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 ..."
@@ -3353,6 +4172,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.`
 			}
 		}
 	},
@@ -3463,6 +4306,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
@@ -3508,9 +4362,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.
 
@@ -3590,7 +4445,11 @@ WAITING FOR A CHANGE
   state, and recomputes every 30 seconds as a fallback. A log append updates
   only the log error count and device activity, no sooner than 15 seconds
   after the previous refresh. Ctrl+C, SIGTERM or closing its stdout ends it
-  with exit 0. Without --json it reprints the human view on change.`,
+  with exit 0. On Linux, so does the exit of the process that started it
+  when its stdout is a pipe. It notices within a few seconds even when
+  nothing changes, except a closed stdout pipe on Linux whose starter is
+  still running, which it notices at the next change.
+  Without --json it reprints the human view on change.`,
 		sections: {
 			eas: {
 				summary: "download a matching EAS development build; explicit profile, costs, cache and miss remedies",
@@ -3781,7 +4640,7 @@ result as proof instead of requiring an unrelated screenshot.`
   column:
 
     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
@@ -3790,7 +4649,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
@@ -3901,6 +4760,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
@@ -3908,26 +4777,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
@@ -3954,6 +4837,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\`.
@@ -3968,8 +4856,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)
@@ -3977,12 +4864,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
@@ -3999,15 +4895,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.
 
@@ -4023,10 +4919,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
@@ -4035,14 +4930,29 @@ 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: {
-				summary: "optional cache warm-up, build optimizations, fingerprints, .fingerprintignore, install unchanged, runtime state",
+				summary: "optional cache warm-up, build optimizations, fingerprints, .fingerprintignore, install unchanged, running app restart, runtime state",
 				body: () => `OPTIONAL CACHE WARM-UP FOR REPEATED NATIVE WORK
   When several native worktrees are coming, build the source checkout once to
   seed the shared caches before warming the linked worktrees. Skip this extra
@@ -4092,8 +5002,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
@@ -4130,8 +5041,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)
@@ -4145,13 +5058,31 @@ AN ARTIFACT THE DEVICE ALREADY HOLDS IS NOT INSTALLED AGAIN
   \`--json\` carries installSkipped so a caller can tell a skipped run from an
   installed one.
 
+A RUNNING APP IS RESTARTED, LIKE XCODE'S RUN
+  Before it launches, \`ios\` and \`android\` read the device's process list.
+  When the app is already running, from an earlier run or after an install
+  that was skipped, Stim stops it and launches it fresh: \`simctl terminate\`
+  on a simulator, \`am force-stop\` on an emulator or an \`android --device\`
+  phone. The new process requests its bundle, so launch verification has real
+  evidence instead of an old process that fetched nothing. In-app state from
+  the previous session does not survive. The launch line says so:
+
+    launch      com.example.app restarted running app (was pid 4242) (0.9s)
+
+  A stop that fails refuses the launch rather than reusing the old process.
+  When the process list cannot be read, Stim launches without stopping
+  anything and verification reports what it observes. An iPhone run
+  (\`ios --device\`) needs no extra step: its collector launches with
+  devicectl's \`--terminate-existing\`. Remote targets launch through
+  \`agent-device open --relaunch\`.
+
 RUNTIME STATE AND BUILD INPUTS
 Runtime state is stored outside the project tree under
 $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
@@ -4554,6 +5485,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.
@@ -4572,8 +5524,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 <proxy|eas>
+  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
@@ -4585,7 +5537,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
@@ -4609,23 +5561,32 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   A BUILD).
   Named slots support local devices; remote sessions use the default slot.
   Names use 1-64 letters, digits, underscores or hyphens, starting with a letter
-  or digit. Reserved object-property names are refused.
+  or digit. Reserved object-property names and web are refused.
 
   stop --slot shuts down that slot's owned devices and releases its leases,
   retaining Metro and sibling slots. stop --slot default targets only the
   workspace's default device, the same one ios/android address with no
   --slot and status reports with no [slot] label; it never touches a remote
-  session even though remote sessions use the default slot. Plain stop
-  handles the whole workspace.
+  session even though remote sessions use the default slot. stop --slot web
+  closes only the owned Chrome from stim web. A slot the workspace has not
+  recorded is refused with STIM_BAD_ARG and the list of its slots; nothing is
+  stopped. A slot whose first build is still running counts as recorded, and
+  that build is interrupted. Plain stop handles the whole workspace.
   status reports named devices under slots and counts their memory. Device
   caps count every slot. Recycling uses the same model/runtime-matched pool
   for every slot, with one shared cap per platform and oldest-first eviction.
 
-  Metro cannot reliably identify a particular simulator's bundle request.
-  When slots coexist, a shared bundle event is not proof that a particular
-  slot launched: Debug launch can report unverified. Check the reported device
-  directly. Release verification still checks its process. reload ios/android
-  addresses matching Metro peers across slots; it is not a single-slot reload.
+  When slots coexist, a Debug launch counts a Metro bundle delivery as proof
+  only when it is attributable to that launch's device. On macOS, Metro records
+  which simulator app process requested an iOS bundle (through lsof), so each
+  simulator slot proves its own launch. Any other delivery (Android, a physical
+  iPhone, or a simulator request lsof could not resolve) proves the launch only
+  while no other slot of the same platform is running: a booted owned device,
+  a log collector or a device lease. stop --slot <name> ends all three.
+  Otherwise the launch reports unverified with "not provably to this device":
+  check the reported device directly. Release verification still checks its
+  process. reload ios/android addresses matching Metro peers across slots; it
+  is not a single-slot reload.
 
   That is the whole surface today, and it is deliberately small. It can grow
   when a flag is genuinely the best answer -- but project-specific knowledge
@@ -4638,6 +5599,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
@@ -4718,7 +5685,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
@@ -4797,7 +5764,21 @@ 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.
+  (\`iOS 26.5\`), exactly; no prefix or suffix matches. On a remote run
+  (\`--remote\` or the ios.remote setting) \`--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 a remote run; it ignores them.
+  \`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
@@ -4865,11 +5846,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
@@ -4895,8 +5890,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
@@ -5076,6 +6072,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
@@ -5120,7 +6127,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\`
@@ -5240,6 +6248,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
@@ -5248,25 +6260,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.
 
@@ -5315,7 +6338,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.
@@ -5370,11 +6394,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
@@ -5419,6 +6446,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
@@ -5610,9 +6651,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
@@ -5622,7 +6719,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
@@ -5634,7 +6732,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.
@@ -5665,15 +6763,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,
@@ -5684,7 +6787,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
@@ -5699,6 +6803,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,
@@ -5746,7 +6877,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
@@ -5765,9 +6896,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
+                     only
   5. Stim default
 An environment override, where a setting has one, wins over every layer.
 
@@ -5797,15 +6930,21 @@ 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
@@ -5857,9 +6996,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
@@ -5963,15 +7105,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
@@ -5999,6 +7161,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
@@ -6178,7 +7357,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 }
@@ -6205,6 +7386,211 @@ 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.
 
+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\`.
+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 it hosts for that client.
+The default, \`none\`, starts nothing. \`agent-device\` starts its
+daemon only when that agent-device can lease a single macOS 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. \`doctor\` on that Mac notes a hosted macOS 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.
+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. 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\` builds, Android builds with the Apple Clang CAS compiler cache,
+and iOS/Android runs with the build cache off, always build here.
+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 and CPU match this Mac exactly, 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
+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).
+Installation alone 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
@@ -6221,6 +7607,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:
@@ -6516,7 +7921,7 @@ An https:// URL on a plain HTTP server fails with ERR_SSL_PROTOCOL_ERROR, and
 an http:// URL on an HTTPS server with ERR_EMPTY_RESPONSE; the remedy line
 prints the settings command that switches the scheme. web.viewport phone
 gives the page a 390x844 touch screen at 3x instead of the 1280x800 desktop
-window. See stim guide settings.
+page. See stim guide settings.
 
 MONOREPO RECIPE: A VITE PACKAGE WITH A BASE PATH AND HTTPS
 
@@ -6576,11 +7981,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
@@ -6596,7 +8018,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
 
@@ -6605,6 +8040,8 @@ claim for its lifetime; Chrome is the claim's child. Stim signals the
 supervisor or Chrome only after verifying the process identity it recorded.
   stim stop               closes Chrome and keeps the profile, so cookies and
                           storage survive the next stim web
+  stim stop --slot web    closes only Chrome, keeping the profile, Metro and
+                          every device
   stim worktree remove    closes Chrome and deletes the profile
   stim gc --delete        does the same for a workspace whose path is gone,
                           and forgets ledger entries of deleted profiles
@@ -6614,10 +8051,385 @@ 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.
+
+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, 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. 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
@@ -6699,7 +8511,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) => {