stim 1.8.0 → 1.9.0

package/dist/{guide-BTAlD1_y.mjs → guide-BiAbhs1J.mjs}

@@ -1,13 +1,11 @@
-import { a as findProjectRoot } from "./project-DDZWf_16.mjs";
-import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-BXXorVM2.mjs";
-import { t as guideStatus } from "./guide-status-Craq9z0t.mjs";
+import { o as findProjectRoot } from "./project-DS112DYB.mjs";
+import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-D030k0t4.mjs";
+import { t as guideStatus } from "./guide-status-BAMVU0ZA.mjs";
 import chalk from "chalk";
-//#endregion
-//#region src/guide/index.ts
-const TOPICS = {
-	agent: {
-		summary: "The normal coding-agent workflow, safety rules, and topic routing",
-		body: () => `AGENT WORKFLOW
+//#region src/guide/agent.ts
+var agent_default = {
+	summary: "The normal coding-agent workflow, safety rules, and topic routing",
+	body: () => `AGENT WORKFLOW
 
 Use Stim to run React Native and Expo apps without sharing a Metro port or
 device with another workspace. Prefer plain output: it streams each phase and
@@ -27,12 +25,6 @@ the source checkout is infrastructure, not a workspace: you edit, build, and run
 in the worktree, and you keep the seed fit to copy. Every rule below about the
 source checkout's fitness as a seed belongs to this workflow.
 
-Doctor reports that fitness -- how far behind the seed is, uncommitted tracked
-changes, an interrupted rebase or merge, a detached HEAD, a diverged branch, a
-branch that is not the default one -- only once the repository has at least
-one linked worktree, so read it from inside the worktree. A single-checkout
-session is never told that its own branch is a problem.
-
 MULTIPLE DEVICES
 
 Use ios/android --slot <name> to retain multiple devices in one workspace,
@@ -67,44 +59,18 @@ If warm fails or reports incomplete, resolve the reported failure first.
 A warm that cannot record its ownership claim refuses before copying. Follow
 the printed remedy and keep concurrent runs on the same STIM_HOME.
 
-Before native worktree work, run doctor for the platform in scope. The STATUS
-block at the top of this topic says when it is due here: never run in this
-checkout, older than seven days, or run under another Stim version. No block
-means doctor is current and Stim is up to date; the same block names a newer
-Stim release when one exists. Doctor checks the source
-checkout from a linked worktree. Fix relevant findings and inspect the
-upstream gap; in the single-checkout workflow those seed findings do not
-appear. It also prints the running CLI version and the stim installation
-resolved from PATH. If that resolved installation is older than another one,
-fix PATH or the installation before continuing so commands and guidance match.
-Doctor reports cross-volume staging and build-cache copies; read guide settings
-for placement overrides and guide lifecycle options for warm behavior.
-For iOS Debug architecture findings, review the project's overrides and imported
-Podfile helpers using guide lifecycle options. Doctor --fix does not change them.
-For parallel iOS work, review the recommended optional SimSlim setup in
-stim guide lifecycle simslim. If simulator process startup times out, check
-host memory pressure and free memory before retrying. Boot progress reports
-current and highest observed pressure; a timeout does not establish OOM.
-Avoid repeated reboots under unchanged pressure; do not restart other
-workspaces' devices or close their apps without asking. That guide covers
-the recovery steps and profile tradeoffs.
-An Android boot timeout under observed elevated memory pressure gets one
-extra wait while the emulator process this run started is alive. It never
-launches a second emulator. For a timeout, read guide errors STIM_NO_DEVICE
-and free memory by stopping only unneeded devices in workspaces you own;
-ask before closing other apps or devices. Device count alone is not evidence
-of memory pressure.
-For a linked native library carrying Git metadata, add the printed .git entries to
-.fingerprintignore only when the native build does not read Git state.
+Before native work, run doctor for the platform in scope when the STATUS block
+at the top of this topic says it is due. No block means doctor is current and
+Stim is up to date. In the worktree workflow, run it from the linked worktree
+so it also checks the source checkout. Follow each finding's printed remedy,
+and read the routed topic below before acting on one you do not understand. If
+the stim resolved from PATH is older than another installation, fix PATH or the
+installation before continuing so commands and guidance match. Under host
+memory pressure, stop only devices in workspaces you own; ask before closing
+other apps or other workspaces' devices.
 
   stim doctor --platform ios          # or: --platform android
 
-For stale Android CMake launcher findings, stop native builds and run
-stim doctor --fix --platform android in the affected checkout before warming
-more worktrees. It removes affected ignored, untracked generated .cxx
-configurations, including installed native modules; the next build recreates
-them. It preserves source, custom launcher settings, and the shared ccache.
-
   # Skip Git creation if the harness already created this linked worktree.
   git worktree add -b <branch> <worktree-path> HEAD
   cd <worktree-path>
@@ -245,8 +211,14 @@ Ask the user before these actions:
   existing Stim ownership record is deleted only when it has no unique commits.
 - worktree remove --force, because it also discards uncommitted and untracked
   files.
-- gc --delete, because it deletes orphaned resources. gc --delete --cache all
-  empties the shared build caches instead; it inspects nothing else.
+- gc --delete, because it deletes orphaned resources and clears the build
+  outputs of every workspace not in use. Run stim gc --json first and show
+  the user the entries its sections list (guide facts gc). gc --delete
+  --cache all empties the shared build caches and those outputs instead, and
+  gc --delete --cache workspaces clears only the outputs; both inspect
+  nothing else.
+- gc --delete --worktrees, because it runs worktree remove on every clean,
+  idle linked worktree Stim manages, across projects.
 - stop when the workspace owns an EAS session, because it irreversibly ends
   that remote session. For a local device, stop shuts it down but does not
   delete it. An explicit stop shuts down a Stim-owned simulator even when
@@ -280,6 +252,12 @@ Read the matching guide before acting in these situations:
 | Capacity limits                                       | stim guide lifecycle concurrency |
 | Cache statistics from stim stats                      | stim guide facts stats           |
 | Worktree carry-over                                   | stim guide lifecycle options     |
+| Doctor finding: seed checkout or cross-volume copy    | stim guide lifecycle options     |
+| Doctor finding: iOS Debug archs, .cxx, fingerprints   | stim guide lifecycle builds      |
+| Temporary storage placement                           | stim guide settings              |
+| Read or change a setting (stim settings)              | stim guide settings              |
+| 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            |
 | worktree remove refusal or --force                    | stim guide errors remove         |
 | Cleanup failure or unverified cleanup ownership       | stim guide errors teardown       |
@@ -316,10 +294,12 @@ FULL TOPIC LIST
   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 settings             # configuration files and supported keys`
-	},
-	facts: {
-		summary: "The --json payloads: `start`, `ios`, `android`, `reload`, `stop`, `status`, `doctor`, `device lock`/`unlock`, and the error contract",
-		preamble: () => `SLOTS
+};
+//#endregion
+//#region src/guide/facts.ts
+const facts = {
+	summary: "The --json payloads: `start`, `ios`, `android`, `reload`, `stop`, `status`, `doctor`, `device lock`/`unlock`, `gc`, and the error contract",
+	preamble: () => `SLOTS
 Named ios/android runs add slot to their JSON facts. Default-run fields remain
 compatible. status adds a slots array per environment with each named slot's
 ios/android device facts; top-level ios/android still describe default.
@@ -328,14 +308,37 @@ Named collector, lease-holder, and launch keys use platform:slot internally.
 FACTS CONTRACT
 
 \`start\`, \`ios\`, \`android\`, \`reload\`, \`stop\`, \`status\`, \`stats\`, \`doctor\`,
-and \`device lock\`/\`device unlock\` each print exactly ONE line of JSON on
+\`gc\`, and \`device lock\`/\`device unlock\` each print exactly ONE line of JSON on
 stdout for \`--json\`. Every other line goes to stderr, so it is always safe
 to pipe. \`logs --json\` is the one exception: it is NDJSON, one record per
-line by design (see \`guide logs\`), not this single-payload contract.`,
-		sections: {
-			payloads: {
-				summary: "every field of the start, ios, android and reload payloads, the error contract, the device rules",
-				body: () => `  stim start --json
+line by design (see \`guide logs\`), not this single-payload contract.
+
+status's unprovisionedWorktrees lists this repository's linked worktrees with
+no Stim environment. \`worktree warm\` does not create one; \`start\`, \`ios\`,
+\`android\` and \`doctor\` register it.
+
+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
+is still running.
+
+  remoteDevices   [{ platform, backend, sessionId, state, startedAt,
+                  webPreviewUrl }], empty when the workspace has none
+  backend         "eas"
+  state           "claimed"    Stim's ownership ledger holds this workspace's
+                               claim, so \`stop\` and \`gc --delete\` can end it
+                  "unclaimed"  the ledger has no claim for this workspace;
+                               \`stop\` still ends the recorded session
+                  "unknown"    the ledger could not be read
+  webPreviewUrl   the browser page showing the remote screen, recorded when
+                  Stim created the session, or null
+
+Plain status prints one "remote <platform>: EAS session <id> billable" line
+per session, with the preview URL.`,
+	sections: {
+		payloads: {
+			summary: "every field of the start, ios, android and reload payloads, the error contract, the device rules",
+			body: () => `  stim start --json
 
   port            the Metro port RESERVED for this workspace
   supervisorPid   the detached supervisor's pid, or NULL when a dev server was
@@ -355,11 +358,11 @@ line by design (see \`guide logs\`), not this single-payload contract.`,
   deviceName      its name, or null
   deviceType      the owned simulator's MODEL, as
                   \`xcrun simctl list devicetypes\` names it ("iPad Pro 13-inch
-                  (M4)"). Read from the simulator itself, so a run driven by
+                  (M5)"). Read from the simulator itself, so a run driven by
                   the ios.deviceType setting reports it too, not only a
                   \`--device-type\` run. Null on \`--device\` and on a
                   simulator Stim does not own
-  runtime         that simulator's iOS runtime version ("18.5"), from the same
+  runtime         that simulator's iOS runtime version ("26.5"), from the same
                   record. Null on the same paths as deviceType
   fingerprint     the @expo/fingerprint hash of the native inputs, AS STORED.
                   A run that had to \`expo prebuild\` or \`pod install\`
@@ -612,10 +615,10 @@ RULES
     \`android --device\` and
     \`ios --device\`, which use a connected physical device Stim never
     creates, boots, or deletes.`
-			},
-			devmenu: {
-				summary: "why the Expo dev menu or Tools button is or is not over the app, per platform and device kind",
-				body: () => `  EVERY DEV-CLIENT DEEP LINK CARRIES disableOnboarding=1
+		},
+		devmenu: {
+			summary: "why the Expo dev menu or Tools button is or is not over the app, per platform and device kind",
+			body: () => `  EVERY DEV-CLIENT DEEP LINK CARRIES disableOnboarding=1
   INSIDE ITS PROJECT URL
   (\`...?url=http%3A%2F%2Fhost%3Aport%2F%3FdisableOnboarding%3D1&disableFab=1\`),
   and expo-dev-launcher finishes its own dev-menu ONBOARDING
@@ -706,10 +709,129 @@ RULES
   developer trust, has no API at all and is always the user's.
   \`guide errors unverified\` has the signature and the
   full commands.`
-			},
-			stats: {
-				summary: "the stats payload, what counts as a run, hit, miss and failed, timeSavedMs, the heartbeat estimate",
-				body: () => `  stim stats --json
+		},
+		gc: {
+			summary: "the gc report payload: mode, sections, reasons, failures, and the gc refusals",
+			body: () => `  stim gc [--delete] [--older-than <days>] [--cache <name|all|workspaces>]
+          [--worktrees] --json
+
+  The report the text prints, as one payload. Show the user its sections
+  before you run \`gc --delete\`. Under --delete it is the report that run
+  acted on: each entry's outcome is a stderr line, \`failures\` counts the
+  entries it could not delete, and a nonzero count exits 1. Run
+  \`stim gc --json\` again to see what is left.
+
+  mode            "dry-run" | "delete"
+  cacheScope      the --cache name, or null. When set, devices, project
+                  entries and locks were not inspected and their sections
+                  are empty
+  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
+                  the default 7 because --older-than was not given
+  actionable      true when --delete with the same flags reclaims something
+  failures        null on a dry run; under --delete, the entries it could
+                  not delete
+  sections        one array per report section, in the text order. Every key
+                  is present, empty when there is nothing to report:
+    deadProjects            { path }
+    invalidProjects         { path }  the registry key is not absolute
+    orphanedPorts           { project, label, port }
+    orphanedWorkspaces      { dir, projectRoot, bytes }  --delete removes the
+                              whole workspace directory
+    linkedWorktrees         { path, idleDays, willRemove, reason, detail }
+                              only with --worktrees
+    parkedSimulators        { udid, name, model, runtime, parkedAt, bytes,
+                              listed }
+    parkedEmulators         { name, systemImage, parkedAt, bytes, listed }
+    orphanedDevices         { kind, id, name, bytes, directory }
+    staleDevices            { kind, id, name, project, slot, idleDays,
+                              bytes }  only with --older-than
+    staleDeviceRecords      { kind, id, project, slot }  --delete clears
+                              the record only
+    orphanedEasSessions     { id, name, platform, status, projectScope }
+    staleBuildLocks         { path, platform, key, pid, projectRoot }
+    staleBuildSlots         { path, index, pid, projectRoot }
+    unresolvedBuildClaims   { kind: "lock" | "slot", path }  never touched
+    buildsInProgress        { path, platform, key, pid, projectRoot }
+                              never touched
+    expiredDeviceLeases     { path, platform, id, deviceName, holder,
+                              expiresAt }
+    keptDeviceLeases        { name, path, detail }  never deleted
+    deviceSweepNotices      { message }
+    easSessionSweepNotices  { message }
+    skipped                 { path, detail }  not classified as dead
+    workspaceBuildOutputs   { dir, projectRoot, bytes, idleDays, willClear,
+                              reason, detail }  derived-data, gradle-build,
+                              android-cas and cache-provider of each
+                              workspace; willClear marks the ones --delete
+                              would clear
+    caches                  { name, dir, source, bytes, note, willEmpty,
+                              emptySkipped }  alive, not garbage; willEmpty
+                              marks the ones --delete would empty
+  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
+  listing was unavailable.
+
+  reason is null for an entry --delete acts on, and otherwise a stable code
+  to branch on; detail is the text line, for the user. Never parse detail.
+    workspaceBuildOutputs   unresolved | in-use | last-use-unknown |
+                            recently-used
+    linkedWorktrees         not-a-worktree | bare-repository |
+                            source-checkout-unknown | source-checkout |
+                            locked | in-use | status-unreadable | dirty |
+                            unpushed-unchecked | unpushed | submodules |
+                            last-use-unknown | recently-used
+
+  These print the error contract instead and exit 1:
+
+    { "code": "STIM_BAD_ARG", "message": "...", "remedy": "..." }
+
+  - a --cache name that no shared cache carries; the remedy names the
+    caches on this machine
+  - --cache together with --worktrees`
+		},
+		status: {
+			summary: "the status payload's build field: a running ios or android build, its phase, and its estimate",
+			body: () => `  stim status --json
+
+  Each entry of environments 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 }
+
+  state            "running" while the run's own native-run claim is live;
+                   "stale" when that claim was released or its process is
+                   gone -- the run was killed, and the next run replaces the
+                   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.
+  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.
+  expectedMs       the median duration of this project's last successful
+                   runs with that outcome on that platform, or null with
+                   no history
+  expectedPhaseMs  the median duration of this phase in those runs, or null
+  basis            how many runs the medians come from (at most 10)
+
+  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)
+
+  There is no completion fraction: a compile's log volume depends on what
+  is already built, so it does not measure progress.`
+		},
+		stats: {
+			summary: "the stats payload, what counts as a run, hit, miss and failed, timeSavedMs, the heartbeat estimate",
+			body: () => `  stim stats --json
 
   { "version": 1,
     "project": { "key": "<path>", "ios": <bucket|null>,
@@ -738,8 +860,13 @@ HOW A RUN IS COUNTED (\`stats\`)
   as a hit and is credited nothing: the compile it skipped was paid for in the
   wait, and with no cold run recorded for this project and platform there is
   nothing to compare against, so it credits nothing either. The saved figure
-  is therefore an ESTIMATE and is printed as one. Nothing per run is stored;
-  the file is $STIM_HOME/stats.json (see \`guide lifecycle builds\`).
+  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
+  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.
 
   A run also keeps the duration of its own two long phases in that bucket:
   the build phase of a miss that compiled (lastColdBuildMs) and the last
@@ -758,12 +885,14 @@ HOW A RUN IS COUNTED (\`stats\`)
   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.`
-			}
 		}
-	},
-	metro: {
-		summary: "The dev server: `stim start`, the supervisor, and starting your own",
-		body: () => `THE DEV SERVER
+	}
+};
+//#endregion
+//#region src/guide/metro.ts
+var metro_default = {
+	summary: "The dev server: `stim start`, the supervisor, and starting your own",
+	body: () => `THE DEV SERVER
 
   stim start
   stim start --remote   # prepare Metro for a remote device
@@ -777,7 +906,8 @@ another worktree's bundler.
   --json            one line of facts on stdout, everything else on stderr:
                       { port, supervisorPid, mode, logsDir, alreadyRunning }
   --wait <seconds>  how long to wait for server and remote tunnel readiness
-                    (default 60 for each)
+                    (default 60 for each). Unlike ios/android/device lock
+                    --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
@@ -825,7 +955,8 @@ REMOTE DEVICE BACKENDS
   The EAS backend needs eas-cli and an account with EAS Simulator access. An
   EAS session is billable. EAS does not inherit the proxy credentials. Always
   tear the session down: \`stop\`, \`worktree remove\`, and \`gc --delete\`
-  can end sessions that Stim proves it owns.
+  can end sessions that Stim proves it owns. \`stim status\` lists each
+  recorded session with its preview URL (see \`guide facts\`).
 
 IDEMPOTENT
   A healthy dev server on the reserved port is a no-op: \`start\` prints the
@@ -904,12 +1035,15 @@ STARTING YOUR OWN BUNDLER STILL WORKS
   and finding output is back to redirecting it to a file yourself. Prefer
   \`start\`.
 
-  \`stop\` leaves an externally started server running. Stop it with the tool
-  that started it.`
-	},
-	ports: {
-		summary: "Workspace ports for web and API servers that Stim does not manage",
-		body: () => `NAMED SERVER PORTS
+  \`stop\` leaves an externally started server running and keeps the port
+  reserved while it answers from this project. Stop it with the tool that
+  started it.`
+};
+//#endregion
+//#region src/guide/ports.ts
+var ports_default = {
+	summary: "Workspace ports for web and API servers that Stim does not manage",
+	body: () => `NAMED SERVER PORTS
 
 If Stim is not installed globally, replace stim with npx stim.
 
@@ -961,10 +1095,12 @@ cleanup: versions without ports do not know about named allocations.
 
 A shared API does not get a shared reservation. Pass its port by environment
 instead of allocating a separate label in every worktree.`
-	},
-	logs: {
-		summary: "Querying the merged NDJSON timeline, and what --errors means",
-		body: () => `LOGS
+};
+//#endregion
+//#region src/guide/logs.ts
+var logs_default = {
+	summary: "Querying the merged NDJSON timeline, and what --errors means",
+	body: () => `LOGS
 
   stim logs [filters]
 
@@ -972,6 +1108,11 @@ Reads every *.ndjson file in the global workspace logs directory, merges them in
 ordered by timestamp, prints what matches, and EXITS. The file set is
 discovered, not enumerated.
 
+metro.ndjson, client.ndjson and device.ndjson are size-capped. At about 8 MiB a file
+becomes <name>.1, replacing the previous .1, and a new file starts. Queries read
+both generations, so the oldest records drop off first. History and --since
+reach back only as far as those records.
+
 EXIT 0 MEANS THE QUERY SUCCEEDED, whether or not records matched. A clean
 \`stim logs --errors\` check requires exit code 0 AND no matching errors in
 captured logs. A workspace that has never produced a timeline refuses with
@@ -1063,7 +1204,7 @@ FLAGS
   records; use its printed --tail value to include all records before grouping.
   To read the complete timeline without the default error-record limit:
     stim logs --source all
-  This includes all sources, levels and history, not just the latest errors;
+  This includes all sources, levels and retained history, not just the latest errors;
   add --since, --level or --grep to narrow it. --source all selects sources,
   not stack depth. For untouched captured records use:
     stim logs --source all --json
@@ -1245,38 +1386,41 @@ WHAT WRITES WHAT
 
   A collector is killed and replaced on the next \`ios\` / \`android\` run for
   that platform, and reaped by \`stop\`.`
-	},
-	errors: {
-		summary: "Every refusal Stim can print: an index of codes, and one section for each",
-		sectionHint: "<CODE>",
-		preamble: () => `WHAT STIM REFUSES, AND WHY
-
-Every refusal from \`ios\` / \`android\` carries a stable CODE. Branch on the
-code, never on the message.`,
-		sections: {
-			STIM_EAS_BUILD_MISSING: {
-				summary: "no completed EAS development build matches; build only with session authorization",
-				body: () => `STIM_EAS_BUILD_MISSING
+};
+//#endregion
+//#region src/guide/errors.ts
+const errors = {
+	summary: "Every refusal Stim can print: an index of codes, and one section for each",
+	sectionHint: "<CODE>",
+	preamble: () => `WHAT STIM REFUSES, AND WHY
+
+Every refusal listed here carries a stable CODE, whichever command prints it.
+Branch on the code, never on the message.`,
+	sections: {
+		STIM_EAS_BUILD_MISSING: {
+			summary: "no completed EAS development build matches; build only with session authorization",
+			separator: "--- EAS BUILD CODES (`ios --eas-profile` / `android --eas-profile`) ---",
+			body: () => `STIM_EAS_BUILD_MISSING
   No compatible build matches the selected EAS project, profile, platform and
   native fingerprint. No device was acquired and no local or cloud build was
   started. The remedy prints the exact npx eas-cli build command. Check session
   authorization for its potential cost before running it, then retry Stim.
   See stim guide lifecycle eas.`
-			},
-			STIM_EAS_UNAVAILABLE: {
-				summary: "EAS lookup/download failed, or another run holds the artifact claim",
-				body: () => `STIM_EAS_UNAVAILABLE
+		},
+		STIM_EAS_UNAVAILABLE: {
+			summary: "EAS lookup/download failed, or another run holds the artifact claim",
+			body: () => `STIM_EAS_UNAVAILABLE
   EAS CLI is unavailable, a profile/fingerprint/list/download operation failed,
   the response could not be validated, or another run holds the artifact claim.
   Follow the printed remedy: inspect the named EAS command or retry once the
   holder finishes. This is not proof that a build is missing. No native build
   is started. See stim guide lifecycle eas.`
-			},
-			STIM_WORKSPACE_STATE: {
-				summary: "$STIM_HOME/workspaces could not be prepared, or the digest directory belongs to another project",
-				aliases: ["STIM_WORKSPACE_COLLISION"],
-				separator: "--- BUILD-PATH CODES (`stim ios` / `stim android`) ---",
-				body: () => `STIM_WORKSPACE_STATE / STIM_WORKSPACE_COLLISION
+		},
+		STIM_WORKSPACE_STATE: {
+			summary: "$STIM_HOME/workspaces could not be prepared, or the digest directory belongs to another project",
+			aliases: ["STIM_WORKSPACE_COLLISION"],
+			separator: "--- BUILD-PATH CODES (`stim ios` / `stim android`) ---",
+			body: () => `STIM_WORKSPACE_STATE / STIM_WORKSPACE_COLLISION
   Stim could not prepare this project's global workspace directory under
   $STIM_HOME/workspaces. Check that STIM_HOME is writable and has free
   space. An EPERM on a directory the user CAN write is a sandbox, not a
@@ -1284,10 +1428,10 @@ code, never on the message.`,
   readable-name-plus-digest directory already has a workspace.json for a
   different canonical project path; do not overwrite it until you identify
   which workspace owns it.`
-			},
-			STIM_NO_METRO: {
-				summary: "nothing provably this workspace's dev server holds the reserved port (ios, android, reload)",
-				body: () => `STIM_NO_METRO
+		},
+		STIM_NO_METRO: {
+			summary: "nothing provably this workspace's dev server holds the reserved port (ios, android, reload)",
+			body: () => `STIM_NO_METRO
   Nothing that could be proven to be THIS workspace's dev server holds the
   reserved port -- or no port is reserved at all. The gate fires in about a
   second, before the device is even booted, rather than after four minutes of
@@ -1302,26 +1446,26 @@ code, never on the message.`,
 
   Reload requires the recorded launch's port to be this workspace's live
   Metro. It refuses a missing, changed, unresponsive, or foreign port.`
-			},
-			STIM_NO_FINGERPRINT: {
-				summary: "@expo/fingerprint produced no hash, so the shared cache cannot be addressed",
-				body: () => `STIM_NO_FINGERPRINT
+		},
+		STIM_NO_FINGERPRINT: {
+			summary: "@expo/fingerprint produced no hash, so the shared cache cannot be addressed",
+			body: () => `STIM_NO_FINGERPRINT
   \`@expo/fingerprint\` produced no hash, so the shared build cache cannot be
   addressed. Stim uses its declared @expo/fingerprint dependency directly,
   independently of the target project's package graph. This is a refusal
   rather than a silent full build because an unaddressable cache means every
   workspace on the commit compiles from scratch, forever.`
-			},
-			STIM_PREBUILD_FAILED: {
-				summary: "expo prebuild could not generate the native directory",
-				body: () => `STIM_PREBUILD_FAILED
+		},
+		STIM_PREBUILD_FAILED: {
+			summary: "expo prebuild could not generate the native directory",
+			body: () => `STIM_PREBUILD_FAILED
   \`expo prebuild\` could not generate the missing native directory. The
   extracted output is above the code; the transcript is in
   the global workspace logs/build-<platform>.ndjson file.`
-			},
-			STIM_DEPS_FAILED: {
-				summary: "pod install or gradle sync failed; the bundler ladder and BUNDLE_FROZEN",
-				body: () => `STIM_DEPS_FAILED
+		},
+		STIM_DEPS_FAILED: {
+			summary: "pod install or gradle sync failed; the bundler ladder and BUNDLE_FROZEN",
+			body: () => `STIM_DEPS_FAILED
   \`pod install\` (iOS) or the gradle dependency sync (Android) failed. On iOS
   this runs only when Podfile.lock and Pods/Manifest.lock disagree, or Pods is
   absent -- which is exactly what a carried worktree produces.
@@ -1349,10 +1493,10 @@ code, never on the message.`,
   \`yarn install\`, \`bun install\`, \`npm ci\`) or that same pod ladder. The
   message names the command, quotes its last lines, and nothing is copied: fix
   the source checkout, then warm again.`
-			},
-			STIM_BUILD_FAILED: {
-				summary: "xcodebuild or gradle failed; the two Android APK refusals; a damaged compilation-cache object",
-				body: () => `STIM_BUILD_FAILED
+		},
+		STIM_BUILD_FAILED: {
+			summary: "xcodebuild or gradle failed; the two Android APK refusals; a damaged compilation-cache object",
+			body: () => `STIM_BUILD_FAILED
   xcodebuild or gradle failed. The EXTRACTED diagnostics are printed (capped),
   not the transcript. Read the log path on the next line for the rest.
   Two Android refusals share this code without gradle itself failing:
@@ -1383,10 +1527,10 @@ code, never on the message.`,
   object, and upgrading the CLI does not clear it. Empty that one cache with
   \`gc --delete --cache "compilation cache"\`, then build again. The next
   build is a cold one.`
-			},
-			STIM_PATH_TOO_LONG: {
-				summary: "Windows only: the project root leaves no room for the NDK object paths ninja must open",
-				body: () => `STIM_PATH_TOO_LONG  (android, Windows only)
+		},
+		STIM_PATH_TOO_LONG: {
+			summary: "Windows only: the project root leaves no room for the NDK object paths ninja must open",
+			body: () => `STIM_PATH_TOO_LONG  (android, Windows only)
   The NDK's ninja is not long-path aware, so every CMake object path has to
   stay under Windows' MAX_PATH. React Native's codegen objects are named
   after their mangled absolute source path, so each carries the project root
@@ -1402,10 +1546,10 @@ code, never on the message.`,
   preflight does not inspect that configured path and may refuse it too.
   \`doctor --platform android\` reports the same root as a finding for the
   emulator's ABI.`
-			},
-			fallbacks: {
-				summary: "release cache-hit notes that are not codes: swap failure, asset gate, uninstall, device fallbacks",
-				body: () => `FALLBACK NOTES THAT ARE NOT CODES (release cache hits)
+		},
+		fallbacks: {
+			summary: "release cache-hit notes that are not codes: swap failure, asset gate, uninstall, device fallbacks",
+			body: () => `FALLBACK NOTES THAT ARE NOT CODES (release cache hits)
   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
@@ -1471,10 +1615,10 @@ code, never on the message.`,
   The same refusal on a FRESHLY BUILT app is a code (STIM_NO_PROFILE,
   STIM_PROFILE_MISMATCH, STIM_NO_SIGNING_IDENTITY), not a note: building again
   would produce the same app and refuse again.`
-			},
-			STIM_BUILD_WAIT_TIMEOUT: {
-				summary: "waited ~90 minutes for another workspace's build of the same fingerprint",
-				body: () => `STIM_BUILD_WAIT_TIMEOUT
+		},
+		STIM_BUILD_WAIT_TIMEOUT: {
+			summary: "waited ~90 minutes for another workspace's build of the same fingerprint",
+			body: () => `STIM_BUILD_WAIT_TIMEOUT
   This run was waiting for ANOTHER workspace's build of the same fingerprint
   (see \`guide lifecycle concurrency\`), and no artifact arrived within ~90
   minutes.
@@ -1483,10 +1627,10 @@ code, never on the message.`,
   may have failed. The message names the current pid and lock directory:
   check the pid, and if it is not really building, remove that directory and
   run the command again.`
-			},
-			STIM_CLAIM_REFUSED: {
-				summary: "an ownership claim blocks the operation; inspect its holder before removing an unresolved claim",
-				body: () => `STIM_CLAIM_REFUSED
+		},
+		STIM_CLAIM_REFUSED: {
+			summary: "an ownership claim blocks the operation; inspect its holder before removing an unresolved claim",
+			body: () => `STIM_CLAIM_REFUSED
   A build lock records the holder's process IDENTITY, not just its pid, so a
   recycled pid reads as a gone builder rather than a live one, and a builder
   busy in a long \`simctl\` or gradle call reads as live rather than as stale.
@@ -1524,10 +1668,10 @@ 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_CLAIM_UNAVAILABLE: {
-				summary: "a process identity or warm claim store is unavailable, so the protected operation refuses",
-				body: () => `STIM_CLAIM_UNAVAILABLE
+		},
+		STIM_CLAIM_UNAVAILABLE: {
+			summary: "a process identity or warm claim store is unavailable, so the protected operation refuses",
+			body: () => `STIM_CLAIM_UNAVAILABLE
   Every ownership claim records the holder's process identity, captured through
   the \`unique-pid\` native module. This code is that capture failing: no
   prebuilt binary for this platform and architecture, or the OS refusing to
@@ -1547,10 +1691,10 @@ code, never on the message.`,
   access to the existing claim store, checking parent permissions, symlink
   targets, mount access and sandbox rules, then retry. Do not switch STIM_HOME to evade a claim:
   concurrent runs must coordinate through the same store.`
-			},
-			STIM_INSTALL_FAILED: {
-				summary: "simctl, adb, or devicectl refused the artifact; the one signer-conflict retry",
-				body: () => `STIM_INSTALL_FAILED
+		},
+		STIM_INSTALL_FAILED: {
+			summary: "simctl, adb, or devicectl refused the artifact; the one signer-conflict retry",
+			body: () => `STIM_INSTALL_FAILED
   The artifact built or came from cache, but \`simctl install\` / \`adb install\` /
   \`devicectl device install app\` refused it. A signature or architecture
   mismatch, or a full device.
@@ -1569,10 +1713,10 @@ code, never on the message.`,
   the flavor's id and not the gradle namespace -- and gives you the
   \`adb -s <serial> uninstall <applicationId>\` that clears it. Re-running after
   that is a cache hit: one install, no build.`
-			},
-			STIM_LAUNCH_FAILED: {
-				summary: "installed but would not start; the developer-trust tap on a phone",
-				body: () => `STIM_LAUNCH_FAILED
+		},
+		STIM_LAUNCH_FAILED: {
+			summary: "installed but would not start; the developer-trust tap on a phone",
+			body: () => `STIM_LAUNCH_FAILED
   Installed, but the app would not start. On Android this usually means no
   launchable activity resolved.
   On a local iOS simulator, a timed-out launch can mean the simulator cannot
@@ -1590,41 +1734,41 @@ code, never on the message.`,
   Trust, then run the command again. It is a per-developer-certificate tap, not
   a per-build one -- but an uninstall clears it, including the one Stim's own
   signer-conflict retry performs.`
-			},
-			STIM_NO_SCHEME: {
-				summary: "Xcode schemes unavailable or no unambiguous app scheme in ios/",
-				body: () => `STIM_NO_SCHEME
+		},
+		STIM_NO_SCHEME: {
+			summary: "Xcode schemes unavailable or no unambiguous app scheme in ios/",
+			body: () => `STIM_NO_SCHEME
   Stim could not list or select an app scheme in ios/. Share the intended app
   scheme so xcodebuild can see it. Select an available exact name with
   \`stim ios --scheme <name>\`. An unknown explicit name prints available choices.
   Without an explicit selector, a workspace
   name match wins; otherwise Stim accepts a sole non-test scheme, or a listed
   scheme matching app.json. Unmatched ambiguous schemes are refused.`
-			},
-			STIM_NO_PROFILE: {
-				summary: "no or undecodable embedded.mobileprovision; build once from Xcode",
-				separator: "--- iOS SIGNING CODES (`ios --device`, and only there) ---",
-				context: `A simulator build needs no signature, which is why none of these can fire on
+		},
+		STIM_NO_PROFILE: {
+			summary: "no or undecodable embedded.mobileprovision; build once from Xcode",
+			separator: "--- iOS SIGNING CODES (`ios --device`, and only there) ---",
+			context: `A simulator build needs no signature, which is why none of these can fire on
 the normal path. A device build carries one, and Stim re-seals any bundle it
 modifies with the identity the bundle already names -- so it checks, before
 spending a build or a bundle, that the check can succeed.`,
-				body: () => `STIM_NO_PROFILE
+			body: () => `STIM_NO_PROFILE
   The built or cached .app has no embedded.mobileprovision, or
-  \`security cms -D\` could not decode the one it has. The first means the build
+  \`openssl smime\` could not decode the one it has. The first means the build
   produced an unsigned app -- almost always a simulator-sliced artifact.
   Set a team and a Development profile for the target's configuration in
   Xcode > Signing & Capabilities, then BUILD ONCE FROM XCODE to install the
   profile. Stim will not do that step: registering a device or minting a
   profile changes your Apple Developer account, so Stim never passes
   -allowProvisioningUpdates.`
-			},
-			STIM_PROFILE_MISMATCH: {
-				summary: "the profile is expired, has no ProvisionedDevices, or does not name this UDID",
-				context: `A simulator build needs no signature, which is why none of these can fire on
+		},
+		STIM_PROFILE_MISMATCH: {
+			summary: "the profile is expired, has no ProvisionedDevices, or does not name this UDID",
+			context: `A simulator build needs no signature, which is why none of these can fire on
 the normal path. A device build carries one, and Stim re-seals any bundle it
 modifies with the identity the bundle already names -- so it checks, before
 spending a build or a bundle, that the check can succeed.`,
-				body: () => `STIM_PROFILE_MISMATCH
+			body: () => `STIM_PROFILE_MISMATCH
   The profile inside the app cannot admit this phone. Three shapes, and the
   message names which one and the profile type it found:
     - it expired, or carries no ExpirationDate at all;
@@ -1638,14 +1782,14 @@ spending a build or a bundle, that the check can succeed.`,
   With --eas-profile, follow the EAS device:create and build commands in the
   refusal instead. Registration, signing changes and cloud builds need session
   authorization. See stim guide lifecycle eas.`
-			},
-			STIM_NO_SIGNING_IDENTITY: {
-				summary: "no single keychain identity resolves; ios.signingIdentitySha1 for two certificates",
-				context: `A simulator build needs no signature, which is why none of these can fire on
+		},
+		STIM_NO_SIGNING_IDENTITY: {
+			summary: "no single keychain identity resolves; ios.signingIdentitySha1 for two certificates",
+			context: `A simulator build needs no signature, which is why none of these can fire on
 the normal path. A device build carries one, and Stim re-seals any bundle it
 modifies with the identity the bundle already names -- so it checks, before
 spending a build or a bundle, that the check can succeed.`,
-				body: () => `STIM_NO_SIGNING_IDENTITY
+			body: () => `STIM_NO_SIGNING_IDENTITY
   No single keychain identity could be resolved to re-seal with. Either
   \`security find-identity -v -p codesigning\` lists nothing, or the identity
   the artifact's own profile names is absent, or two certificates share that
@@ -1653,14 +1797,14 @@ spending a build or a bundle, that the check can succeed.`,
   Open Xcode > Settings > Accounts and download your certificates, or unlock
   the login keychain with \`security unlock-keychain\`. For the two-certificate
   case, set ios.signingIdentitySha1 to the SHA-1 hash beside the one you want.`
-			},
-			STIM_CODESIGN_FAILED: {
-				summary: "codesign failed on the modified copy; the cache entry is untouched and the run builds fresh",
-				context: `A simulator build needs no signature, which is why none of these can fire on
+		},
+		STIM_CODESIGN_FAILED: {
+			summary: "codesign failed on the modified copy; the cache entry is untouched and the run builds fresh",
+			context: `A simulator build needs no signature, which is why none of these can fire on
 the normal path. A device build carries one, and Stim re-seals any bundle it
 modifies with the identity the bundle already names -- so it checks, before
 spending a build or a bundle, that the check can succeed.`,
-				body: () => `STIM_CODESIGN_FAILED
+			body: () => `STIM_CODESIGN_FAILED
   \`codesign --force --sign\` or \`codesign --verify --strict\` exited non-zero
   on the modified copy. The verbatim codesign stderr is quoted, because it is
   the answer: a locked login keychain reports errSecInternalComponent, an
@@ -1668,14 +1812,14 @@ spending a build or a bundle, that the check can succeed.`,
   and confirm exactly one identity matches the name. The cache entry itself is
   never modified -- the failure is on a temporary copy, and the run builds
   fresh.`
-			},
-			STIM_NO_LAN_ADDRESS: {
-				summary: "the Mac has no non-internal IPv4 interface; a tunnel cannot help a phone",
-				separator: "--- iOS DEVICE DEBUG REACHABILITY CODES (`ios --device` in Debug) ---",
-				context: `A phone does not share the host's loopback and USB carries no reverse forward,
+		},
+		STIM_NO_LAN_ADDRESS: {
+			summary: "the Mac has no non-internal IPv4 interface; a tunnel cannot help a phone",
+			separator: "--- iOS DEVICE DEBUG REACHABILITY CODES (`ios --device` in Debug) ---",
+			context: `A phone does not share the host's loopback and USB carries no reverse forward,
 so a Debug run on one is wired to a LAN origin instead of localhost. Both codes
 fire BEFORE the build, because a refusal that costs a build is a bad refusal.`,
-				body: () => `STIM_NO_LAN_ADDRESS
+			body: () => `STIM_NO_LAN_ADDRESS
   This Mac reports no non-internal IPv4 interface, so there is no address to
   give the phone: it is offline, or on nothing but utun/awdl/bridge. Join a
   Wi-Fi or Ethernet network, or connect this Mac by cable, and run again.
@@ -1684,13 +1828,13 @@ fire BEFORE the build, because a refusal that costs a build is a bad refusal.`,
   ip.txt is read by RCTBundleURLProvider, which prefixes the scheme. A tunnel
   cannot be expressed to a phone, so --device ignores metro.publicUrl,
   metro.tunnel and metro.ngrokUrl and says so when one is set.`
-			},
-			STIM_LAN_METRO_UNREACHABLE: {
-				summary: "the LAN origin did not answer as this workspace's Metro; ios.lanHost on a multi-NIC Mac",
-				context: `A phone does not share the host's loopback and USB carries no reverse forward,
+		},
+		STIM_LAN_METRO_UNREACHABLE: {
+			summary: "the LAN origin did not answer as this workspace's Metro; ios.lanHost on a multi-NIC Mac",
+			context: `A phone does not share the host's loopback and USB carries no reverse forward,
 so a Debug run on one is wired to a LAN origin instead of localhost. Both codes
 fire BEFORE the build, because a refusal that costs a build is a bad refusal.`,
-				body: () => `STIM_LAN_METRO_UNREACHABLE
+			body: () => `STIM_LAN_METRO_UNREACHABLE
   The chosen LAN origin did not answer as THIS workspace's Metro: no answer, a
   5xx, or a dev server that is not this one -- the message says which.
   \`stim start\` prints the port it reserved. On a Mac with several interfaces
@@ -1700,12 +1844,12 @@ fire BEFORE the build, because a refusal that costs a build is a bad refusal.`,
   routes a host connection to its own address over loopback, so the gate passes
   through a firewall that will block the phone. That evidence only ever arrives
   from the phone's own bundle request, which is what \`launched\` reports.`
-			},
-			unverified: {
-				summary: "launched: \"unverified\" with the Local Network path reason, and the routed recovery",
-				context: `A phone does not share the host's loopback and USB carries no reverse forward,
+		},
+		unverified: {
+			summary: "launched: \"unverified\" with the Local Network path reason, and the routed recovery",
+			context: `A phone does not share the host's loopback and USB carries no reverse forward,
 so a Debug run on one is wired to a LAN origin instead of localhost.`,
-				body: () => `LAUNCH UNVERIFIED, LOCAL NETWORK NOT GRANTED (not a code -- a routed remedy)
+			body: () => `LAUNCH UNVERIFIED, LOCAL NETWORK NOT GRANTED (not a code -- a routed remedy)
   An app that has not been granted Local Network reaches nothing on the LAN,
   and CFNetwork reports each attempt as NSURLErrorDomain -1009 "The Internet
   connection appears to be offline." with the path reason
@@ -1791,17 +1935,18 @@ so a Debug run on one is wired to a LAN origin instead of localhost.`,
   General > VPN & Device Management) is refused to automation by the same gate
   that refuses the app, agent-device's own runner included, so its remedy is
   "ask the user" and nothing else. An uninstall clears both.`
-			},
-			STIM_NO_DEVICE: {
-				summary: "no usable phone, or the owned simulator or emulator could not be created or booted",
-				separator: "--- DEVICE AND CAPACITY CODES ---",
-				body: () => `STIM_NO_DEVICE
+		},
+		STIM_NO_DEVICE: {
+			summary: "no usable phone, or the owned simulator or emulator could not be created or booted",
+			separator: "--- DEVICE AND CAPACITY CODES ---",
+			body: () => `STIM_NO_DEVICE
   With \`--device\`, no physical device answered the selection: none connected,
   a named serial/UDID that is not connected, several connected with none named
   (the refusal lists them), or one that is connected but unusable -- an
   unauthorized Android device, or an iPhone that is unpaired or has Developer
-  Mode off. Hardware is never created or booted, so there is nothing to retry
-  into existence: fix the cable, the trust prompt, or Developer Mode.
+  Mode off, over a cable or over Wi-Fi alike. Hardware is never created or
+  booted, so there is nothing to retry into existence: fix the cable, the
+  trust prompt, or Developer Mode.
   Otherwise the owned simulator/emulator could not be created or could not
   reach a booted state. \`stim doctor\` checks the toolchain; \`stim status\` says what
   Stim thinks it owns. Re-running the command creates a fresh owned device
@@ -1851,10 +1996,10 @@ so a Debug run on one is wired to a LAN origin instead of localhost.`,
   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.`
-			},
-			STIM_DEVICE_BUSY: {
-				summary: "another workspace holds the lease on that phone and the wait ran out",
-				body: () => `STIM_DEVICE_BUSY
+		},
+		STIM_DEVICE_BUSY: {
+			summary: "another workspace holds the lease on that phone and the wait ran out",
+			body: () => `STIM_DEVICE_BUSY
   Only on a \`--device\` run. Another workspace holds the lease on that phone,
   and the wait ran out: the message names the holder root, the device, and the
   expiry as a clock time and a remaining duration, and \`--json\` adds
@@ -1868,10 +2013,25 @@ so a Debug run on one is wired to a LAN origin instead of localhost.`,
   no token left in its \`state.json\` (its workspace directory was recreated).
   The remedy for that last one is \`stim device unlock\`, which releases by
   holder rather than by token.`
-			},
-			STIM_DEVICE_LOST: {
-				summary: "the lease was gone or re-held at the pre-install check; rerun",
-				body: () => `STIM_DEVICE_LOST
+		},
+		STIM_DEVICE_WIRELESS_FAILED: {
+			summary: "an iPhone paired over Wi-Fi timed out or dropped during install or launch; use the cable",
+			body: () => `STIM_DEVICE_WIRELESS_FAILED
+  Only on an \`ios --device\` run whose iPhone devicectl reaches over Wi-Fi
+  (transportType localNetwork). The \`devicectl device install app\` ran past
+  its 15-minute Wi-Fi bound, the phone did not appear in its own process list
+  within the 120-second Wi-Fi launch bound, or devicectl reported that the
+  connection dropped in its own ERROR output (an app's log lines never count).
+  The message names the transport and quotes devicectl. Connect the phone
+  with a cable, keep it unlocked, and run the command again: a cabled phone
+  installs over the cable. A cause devicectl names -- a locked phone, an
+  untrusted host, Developer Mode off, full storage, the developer-trust tap --
+  keeps STIM_INSTALL_FAILED or STIM_LAUNCH_FAILED and its own remedy, even
+  when the step also timed out and even during a signer-conflict reinstall.`
+		},
+		STIM_DEVICE_LOST: {
+			summary: "the lease was gone or re-held at the pre-install check; rerun",
+			body: () => `STIM_DEVICE_LOST
   Only on a \`--device\` run. The run held a lease, and the raise before the
   install found it gone or held under another token -- another workspace took
   the device in that window. The message names the new holder and its expiry.
@@ -1879,10 +2039,10 @@ so a Debug run on one is wired to a LAN origin instead of localhost.`,
   AFTER the install has started this is not a failure: the app is already on
   the phone, so the run prints one warning, continues, and reports
   \`lease: null\` in \`--json\`.`
-			},
-			STIM_AT_CAPACITY: {
-				summary: "concurrency.maxDevices reached; a refusal, not a queue",
-				body: () => `STIM_AT_CAPACITY
+		},
+		STIM_AT_CAPACITY: {
+			summary: "concurrency.maxDevices reached; a refusal, not a queue",
+			body: () => `STIM_AT_CAPACITY
   Only when concurrency.maxDevices is set (it is UNSET by default, so this never
   fires unless you opted in). Booting a NEW owned device would exceed the cap:
   the machine already has that many Stim-owned devices booted. It is a refusal, not
@@ -1893,10 +2053,10 @@ so a Debug run on one is wired to a LAN origin instead of localhost.`,
   \`ios\` on an environment you already have is idempotent. (The build cap
   behaves differently: a compile WAITS for a free slot rather than refusing.
   See \`guide lifecycle concurrency\`.)`
-			},
-			STIM_BUILD_SLOT_TIMEOUT: {
-				summary: "the maxBuilds wait gave up with every slot held by a running process",
-				body: () => `STIM_BUILD_SLOT_TIMEOUT
+		},
+		STIM_BUILD_SLOT_TIMEOUT: {
+			summary: "the maxBuilds wait gave up with every slot held by a running process",
+			body: () => `STIM_BUILD_SLOT_TIMEOUT
   Only when concurrency.maxBuilds is set. The build cap does not refuse, it
   WAITS -- this code is that wait giving up: ~90 minutes elapsed and every one
   of the N slots was still held by a running process, or by a holder Stim could
@@ -1910,50 +2070,50 @@ so a Debug run on one is wired to a LAN origin instead of localhost.`,
   the message names the directory: remove the slot of a builder that is not
   building, or raise concurrency.maxBuilds
   (\`guide lifecycle concurrency\`).`
-			},
-			STIM_NO_REMOTE_SESSION: {
-				summary: "the backend could not use agent-device, or metro.tunnel names an unusable provider",
-				separator: "--- REMOTE-DEVICE CODES (`ios --remote <proxy|eas>` / `android --remote <proxy|eas>`) ---",
-				body: () => `STIM_NO_REMOTE_SESSION
+		},
+		STIM_NO_REMOTE_SESSION: {
+			summary: "the backend could not use agent-device, or metro.tunnel names an unusable provider",
+			separator: "--- REMOTE-DEVICE CODES (`ios --remote <proxy|eas>` / `android --remote <proxy|eas>`) ---",
+			body: () => `STIM_NO_REMOTE_SESSION
   The selected backend could not use agent-device, or metro.tunnel names a
   provider or mode this workspace cannot use (e.g. "expo" on a bare RN
   project). The remedy line says which. Nothing was created yet.`
-			},
-			STIM_REMOTE_PROXY_CONFIG: {
-				summary: "--remote proxy needs AGENT_DEVICE_DAEMON_BASE_URL and AGENT_DEVICE_DAEMON_AUTH_TOKEN",
-				body: () => `STIM_REMOTE_PROXY_CONFIG
+		},
+		STIM_REMOTE_PROXY_CONFIG: {
+			summary: "--remote proxy needs AGENT_DEVICE_DAEMON_BASE_URL and AGENT_DEVICE_DAEMON_AUTH_TOKEN",
+			body: () => `STIM_REMOTE_PROXY_CONFIG
   \`--remote proxy\` requires AGENT_DEVICE_DAEMON_BASE_URL and
   AGENT_DEVICE_DAEMON_AUTH_TOKEN. These variables provide credentials after
   proxy is selected. They never select the backend.`
-			},
-			STIM_REMOTE_EAS_UNAVAILABLE: {
-				summary: "--remote eas needs eas-cli",
-				body: () => `STIM_REMOTE_EAS_UNAVAILABLE
+		},
+		STIM_REMOTE_EAS_UNAVAILABLE: {
+			summary: "--remote eas needs eas-cli",
+			body: () => `STIM_REMOTE_EAS_UNAVAILABLE
   \`--remote eas\` requires eas-cli. Proxy environment variables do not change
   this selection and are not passed to EAS.`
-			},
-			STIM_REMOTE_PLATFORM_MISMATCH: {
-				summary: "the recorded remote session belongs to the other platform; stop, then rerun",
-				body: () => `STIM_REMOTE_PLATFORM_MISMATCH
+		},
+		STIM_REMOTE_PLATFORM_MISMATCH: {
+			summary: "the recorded remote session belongs to the other platform; stop, then rerun",
+			body: () => `STIM_REMOTE_PLATFORM_MISMATCH
   This workspace already has a recorded remote session, and it belongs to the
   OTHER platform ("Session <id> belongs to android, not ios"). A workspace
   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_SESSION_STATE: {
-				summary: "the EAS session was created but its state could not be recorded, so Stim stopped it",
-				body: () => `STIM_REMOTE_SESSION_STATE
+		},
+		STIM_REMOTE_SESSION_STATE: {
+			summary: "the EAS session was created but its state could not be recorded, so Stim stopped it",
+			body: () => `STIM_REMOTE_SESSION_STATE
   The EAS session was created and is healthy, but recording it in this
   workspace's state failed (an unwritable STIM_HOME, a full disk). A session
   nothing references is a session nothing will ever stop, so Stim stopped the
   one it had just created and removed its ownership claim before reporting:
   this code means nothing is running and nothing is still billing. Repair the
   state storage the message names, then run the remote command again.`
-			},
-			STIM_REMOTE_SESSION_CLEANUP: {
-				summary: "Stim could not prove an EAS session ended; eas simulator:stop --id",
-				body: () => `STIM_REMOTE_SESSION_CLEANUP
+		},
+		STIM_REMOTE_SESSION_CLEANUP: {
+			summary: "Stim could not prove an EAS session ended; eas simulator:stop --id",
+			body: () => `STIM_REMOTE_SESSION_CLEANUP
   Stim tried to end an EAS session and could not PROVE it ended: \`eas
   simulator:stop\` failed, or its output did not confirm the stop, or the
   session stopped but its claim in the machine ledger could not be removed.
@@ -1962,10 +2122,10 @@ so a Debug run on one is wired to a LAN origin instead of localhost.`,
   \`eas simulator:stop --id <id>\` -- and for a ledger that outlived its
   session, the ledger path to repair. The same code covers a recorded session
   that could not be verified before replacement: inspect it, then \`stim stop\`.`
-			},
-			STIM_REMOTE_METRO_WRONG: {
-				summary: "the tunnel reaches a Metro that is not this workspace's",
-				body: () => `STIM_REMOTE_METRO_WRONG
+		},
+		STIM_REMOTE_METRO_WRONG: {
+			summary: "the tunnel reaches a Metro that is not this workspace's",
+			body: () => `STIM_REMOTE_METRO_WRONG
   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.
@@ -1974,39 +2134,39 @@ so a Debug run on one is wired to a LAN origin instead of localhost.`,
   port), and it now serves ANOTHER workspace's dev server -- healthy, and
   wrong. Re-run \`stim start\` (it prints the port it reserved) and, for a
   manual tunnel, rebuild it against that port.`
-			},
-			STIM_REMOTE_METRO_UNREACHABLE: {
-				summary: "a remote start could not create its managed tunnel or tell the device where Metro is",
-				body: () => `STIM_REMOTE_METRO_UNREACHABLE
+		},
+		STIM_REMOTE_METRO_UNREACHABLE: {
+			summary: "a remote start could not create its managed tunnel or tell the device where Metro is",
+			body: () => `STIM_REMOTE_METRO_UNREACHABLE
   A remote start could not create its selected managed tunnel, or the device
   could not be told where Metro is. Follows the same remedy as
   STIM_NO_REMOTE_SESSION's tunnel guidance -- set metro.tunnel, or use
   metro.publicUrl for an existing endpoint.`
-			},
-			STIM_RELOAD_AMBIGUOUS: {
-				summary: "both owned apps are live; name the platform",
-				separator: "--- RELOAD CODES (`stim reload [ios|android]`) ---",
-				body: () => `STIM_RELOAD_AMBIGUOUS
+		},
+		STIM_RELOAD_AMBIGUOUS: {
+			summary: "both owned apps are live; name the platform",
+			separator: "--- RELOAD CODES (`stim reload [ios|android]`) ---",
+			body: () => `STIM_RELOAD_AMBIGUOUS
   Both owned apps are live. Name ios or android; Stim never guesses.`
-			},
-			STIM_RELOAD_RELEASE: {
-				summary: "the live app has embedded JS; run a Debug build first",
-				body: () => `STIM_RELOAD_RELEASE
+		},
+		STIM_RELOAD_RELEASE: {
+			summary: "the live app has embedded JS; run a Debug build first",
+			body: () => `STIM_RELOAD_RELEASE
   The live app was launched with embedded JavaScript. Run the platform command
   with a Debug configuration or variant first.`
-			},
-			STIM_RELOAD_STOPPED: {
-				summary: "the recorded app is gone, its device is not live and owned, or the process could not be proven",
-				aliases: ["STIM_RELOAD_UNOWNED", "STIM_RELOAD_PROBE_FAILED"],
-				body: () => `STIM_RELOAD_STOPPED / STIM_RELOAD_UNOWNED / STIM_RELOAD_PROBE_FAILED
+		},
+		STIM_RELOAD_STOPPED: {
+			summary: "the recorded app is gone, its device is not live and owned, or the process could not be proven",
+			aliases: ["STIM_RELOAD_UNOWNED", "STIM_RELOAD_PROBE_FAILED"],
+			body: () => `STIM_RELOAD_STOPPED / STIM_RELOAD_UNOWNED / STIM_RELOAD_PROBE_FAILED
   The recorded app is gone, its exact device is not live and owned by this
   workspace, or simctl/adb could not prove the process exists. No launch or
   device lifecycle action is taken; follow the printed platform-command or
   process-probe remedy.`
-			},
-			STIM_RELOAD_FAILED: {
-				summary: "the reload failed; the remedy differs by shape -- read it before acting",
-				body: () => `STIM_RELOAD_FAILED
+		},
+		STIM_RELOAD_FAILED: {
+			summary: "the reload failed; the remedy differs by shape -- read it before acting",
+			body: () => `STIM_RELOAD_FAILED
   The Metro websocket reload did not reach a peer Stim could identify. Two
   shapes reach this code and the remedy differs. Read it rather than assuming.
 
@@ -2032,27 +2192,27 @@ so a Debug run on one is wired to a LAN origin instead of localhost.`,
   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.`
-			},
-			STIM_WORKTREE_REMOVAL_IN_PROGRESS: {
-				summary: "a managed remote start found worktree remove holding the lock; wait, then rerun",
-				separator: "--- DEV-SERVER CODES (`stim start`) ---",
-				body: () => `STIM_WORKTREE_REMOVAL_IN_PROGRESS
+		},
+		STIM_WORKTREE_REMOVAL_IN_PROGRESS: {
+			summary: "a managed remote start found worktree remove holding the lock; wait, then rerun",
+			separator: "--- DEV-SERVER CODES (`stim start`) ---",
+			body: () => `STIM_WORKTREE_REMOVAL_IN_PROGRESS
   A managed remote start found that \`stim worktree remove\` owns the
   worktree lock. The start did not register the project or create a tunnel.
   Wait for removal to finish, then run \`stim start --remote\` again.`
-			},
-			STIM_REMOTE_START_REQUIRED: {
-				summary: "a running server cannot gain a remote tunnel; stop, then start --remote, or metro.publicUrl",
-				body: () => `STIM_REMOTE_START_REQUIRED
+		},
+		STIM_REMOTE_START_REQUIRED: {
+			summary: "a running server cannot gain a remote tunnel; stop, then start --remote, or metro.publicUrl",
+			body: () => `STIM_REMOTE_START_REQUIRED
   A healthy bare or Expo server was started without its required remote
   tunnel. A running server cannot gain that option. For a Stim supervisor,
   run \`stim stop\`, then \`stim start --remote\`. For an external server,
   configure metro.publicUrl or let Stim supervise the server.`
-			},
-			STIM_BARE_DEPS: {
-				summary: "the supervisor cannot host Metro from the project's node_modules; the @stim-cli/metro capture note",
-				aliases: ["STIM_BARE_LOAD", "STIM_BARE_API"],
-				body: () => `STIM_BARE_DEPS / STIM_BARE_LOAD / STIM_BARE_API  (bare RN)
+		},
+		STIM_BARE_DEPS: {
+			summary: "the supervisor cannot host Metro from the project's node_modules; the @stim-cli/metro capture note",
+			aliases: ["STIM_BARE_LOAD", "STIM_BARE_API"],
+			body: () => `STIM_BARE_DEPS / STIM_BARE_LOAD / STIM_BARE_API  (bare RN)
   The supervisor hosts Metro out of the PROJECT's node_modules, so metro,
   @react-native/dev-middleware and @react-native-community/cli-server-api must
   be installed there and must match the project's React Native. DEPS = not
@@ -2064,25 +2224,25 @@ captured"  (in metro.ndjson, bare RN)
   The dev server is serving; only capture is missing, so \`logs\` would report
   a quiet timeline for a broken build. Install \`@stim-cli/metro\` as a
   devDependency of the project.`
-			},
-			STIM_EXPO_BIN: {
-				summary: "node_modules/.bin/expo is missing; install dependencies",
-				body: () => `STIM_EXPO_BIN  (Expo)
+		},
+		STIM_EXPO_BIN: {
+			summary: "node_modules/.bin/expo is missing; install dependencies",
+			body: () => `STIM_EXPO_BIN  (Expo)
   node_modules/.bin/expo does not exist. Install the project's dependencies.`
-			},
-			STIM_METRO_TIMEOUT: {
-				summary: "the supervisor is alive but Metro or the tunnel was not ready within the wait; --wait 180",
-				body: () => `STIM_METRO_TIMEOUT
+		},
+		STIM_METRO_TIMEOUT: {
+			summary: "the supervisor is alive but Metro or the tunnel was not ready within the wait; --wait 180",
+			body: () => `STIM_METRO_TIMEOUT
   "The dev server did not answer on port <n> within <s>s."
   The supervisor is alive, but Metro or its requested Expo tunnel is not ready.
   \`start\` has already
   printed the last lines of the global workspace logs/supervisor.log above this -- read
   them. A cold Metro on a large graph can genuinely need more than the default
   60s: re-run with \`--wait 180\`. Otherwise \`stim stop\`, then \`start\`.`
-			},
-			STIM_SUPERVISOR_EXITED: {
-				summary: "the dev server failed outright; the quoted supervisor.log tail is the real error",
-				body: () => `STIM_SUPERVISOR_EXITED
+		},
+		STIM_SUPERVISOR_EXITED: {
+			summary: "the dev server failed outright; the quoted supervisor.log tail is the real error",
+			body: () => `STIM_SUPERVISOR_EXITED
   "The supervisor exited (<code|signal>) before the dev server came up"
   The dev server failed outright, and the quoted evidence is the real error:
   the supervisor.log tail if it wrote one, plus this attempt's error records
@@ -2097,11 +2257,11 @@ captured"  (in metro.ndjson, bare RN)
   Stim's processes. For a legacy record, stop the server with the tool that
   started it before retrying. Never reconstruct ownership from a process
   name, port, or wall-clock timestamp.`
-			},
-			STIM_BAD_ARG: {
-				summary: "an argument, setting, directory, flavor, or device name refused before anything starts",
-				aliases: ["STIM_NO_PROJECT"],
-				body: () => `STIM_BAD_ARG / STIM_NO_PROJECT
+		},
+		STIM_BAD_ARG: {
+			summary: "an argument, setting, directory, flavor, or device name refused before anything starts",
+			aliases: ["STIM_NO_PROJECT"],
+			body: () => `STIM_BAD_ARG / STIM_NO_PROJECT
   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
@@ -2127,16 +2287,25 @@ captured"  (in metro.ndjson, bare RN)
   or android.systemImage 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.
+  \`gc --json --cache <name>\` refuses with STIM_BAD_ARG when no shared cache
+  carries the name; the remedy names the caches on this machine. \`gc\`
+  refuses --cache together with --worktrees the same way.
+  A working directory with no package.json above it gets the same
+  STIM_NO_PROJECT refusal from \`start\`, \`ios\`, \`android\`, \`stop\`,
+  \`reload\`, \`logs\`, \`doctor\` and \`device lock|unlock\`. With \`--json\` the { code, message, remedy } object
+  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.
   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) runs only when
   a name was actually given, and a listing that fails is reported as
   STIM_NO_DEVICE naming the tool, never as a crash.`
-			},
-			STIM_LOCK_REFUSED: {
-				summary: "a directory lock is held by a removal, which is never waited out",
-				separator: "--- COORDINATION CODES (any command that shares a resource) ---",
-				body: () => `STIM_LOCK_REFUSED
+		},
+		STIM_LOCK_REFUSED: {
+			summary: "a directory lock is held by a removal, which is never waited out",
+			separator: "--- COORDINATION CODES (any command that shares a resource) ---",
+			body: () => `STIM_LOCK_REFUSED
   A directory lock that serialises two commands over the same thing -- this
   workspace's managed tunnel, its managed remote worktree, the machine's EAS
   project ledger -- is held by a REMOVAL, and a removal is never waited out:
@@ -2145,10 +2314,10 @@ captured"  (in metro.ndjson, bare RN)
   \`workspace removal\` -- both are \`stim worktree remove\`). Let it finish,
   then run the command again. \`start --remote\` reports this same case as
   STIM_WORKTREE_REMOVAL_IN_PROGRESS instead.`
-			},
-			STIM_LOCK_TIMEOUT: {
-				summary: "a lock held past the wait; workspace-process and short directory locks",
-				body: () => `STIM_LOCK_TIMEOUT
+		},
+		STIM_LOCK_TIMEOUT: {
+			summary: "a lock held past the wait; workspace-process and short directory locks",
+			body: () => `STIM_LOCK_TIMEOUT
   The same locks, held by an ordinary command that is still running, for
   longer than the wait -- 60s by default, 4 minutes for the remote-session and
   EAS project locks, and ~90 minutes for the \`worktree warm\` lock, which one
@@ -2180,11 +2349,11 @@ captured"  (in metro.ndjson, bare RN)
   These paths still time out; verify that no holder is running before removing
   only the named directory. Standalone Metro and Expo cache packages use the
   same core protocol and do not require the Stim CLI.`
-			},
-			teardown: {
-				summary: "an unmanaged port, an unverified supervisor, and a failed device teardown",
-				separator: "--- TEARDOWN AND WORKSPACE REFUSALS ---",
-				body: () => `"metro       refusing to kill port <n>: ... runs from <dir>, outside
+		},
+		teardown: {
+			summary: "an unmanaged port, an unverified supervisor, and a failed device teardown",
+			separator: "--- TEARDOWN AND WORKSPACE REFUSALS ---",
+			body: () => `"metro       refusing to kill port <n>: ... runs from <dir>, outside
 <project>"  (stop)
   Stim only signals processes it launched and whose saved identity still
   matches. Stop an externally started server with the tool that started it.
@@ -2204,14 +2373,22 @@ captured"  (in metro.ndjson, bare RN)
   reserved. Re-run \`stop\`, or signal it yourself: kill -9 -<n> (note the
   minus -- it is a process group).
 
+"metro       refusing to signal it: the identity of dev server pid <n> left by
+the supervisor could not be verified"  (stop)
+"metro       dev server pid <n> left by the supervisor did not exit"  (stop)
+  The supervisor is gone but the dev server it started may still run. Stim
+  signals it only while its saved identity matches, and on macOS and Linux
+  never escalates to SIGKILL. The record and the port reservation are KEPT for a retry. Check
+  \`ps -p <n>\`, stop it yourself if it is still running, then re-run \`stop\`.
+
 "teardown failed: <reason>"
   Stim could not release the owned device and keeps its record for a retry.
   \`worktree remove\` exits 1 without removing the worktree while the device is
   still tracked. Fix the reported cause and re-run.`
-			},
-			remove: {
-				summary: "worktree remove refused a dirty tree: what it restores itself and what --force discards",
-				body: () => `"Refusing to remove <path>: uncommitted changes / untracked files / commits
+		},
+		remove: {
+			summary: "worktree remove refused a dirty tree: what it restores itself and what --force discards",
+			body: () => `"Refusing to remove <path>: uncommitted changes / untracked files / commits
 not on any remote"  (worktree remove)
   A native build rewrites tracked files, and Stim now RESTORES the one class
   it can prove is not work: when the only dirt left is \`pod install\` churn
@@ -2231,10 +2408,10 @@ not on any remote"  (worktree remove)
   refusal actually named.
   Use --force only when you genuinely intend to discard work; it deletes
   uncommitted and untracked files permanently.`
-			},
-			STIM_MAIN_DIRTY: {
-				summary: "warm --refresh will not move a source checkout with local work or an operation in progress",
-				body: () => `STIM_MAIN_DIRTY
+		},
+		STIM_MAIN_DIRTY: {
+			summary: "warm --refresh will not move a source checkout with local work or an operation in progress",
+			body: () => `STIM_MAIN_DIRTY
   \`worktree warm --refresh\` writes to the SOURCE CHECKOUT, and it refuses one
   it cannot move: tracked files with uncommitted changes (the refusal names
   them), or a rebase or merge in progress. Untracked files are not a reason to
@@ -2244,28 +2421,28 @@ not on any remote"  (worktree remove)
   or \`git -C <source-checkout> rebase --abort\`. Nothing was installed or
   copied. Plain \`stim worktree warm\` does not care: it copies from a dirty
   source checkout exactly as it always has.`
-			},
-			STIM_MAIN_DETACHED: {
-				summary: "warm --refresh needs a branch to fast-forward, not a detached HEAD",
-				body: () => `STIM_MAIN_DETACHED
+		},
+		STIM_MAIN_DETACHED: {
+			summary: "warm --refresh needs a branch to fast-forward, not a detached HEAD",
+			body: () => `STIM_MAIN_DETACHED
   The source checkout's HEAD is detached, so there is no branch to fast-forward
   and no upstream to fast-forward it to. Run
   \`git -C <source-checkout> checkout <branch>\` and warm again. \`--refresh\`
   never picks a branch for you; a checkout whose job is to seed worktrees
   should sit on a branch someone chose.`
-			},
-			STIM_MAIN_DIVERGED: {
-				summary: "the source checkout is both ahead of and behind its upstream; warm --refresh will not merge",
-				body: () => `STIM_MAIN_DIVERGED
+		},
+		STIM_MAIN_DIVERGED: {
+			summary: "the source checkout is both ahead of and behind its upstream; warm --refresh will not merge",
+			body: () => `STIM_MAIN_DIVERGED
   The source checkout's branch has commits its upstream does not, AND its
   upstream has commits it does not. A fast-forward is impossible, and
   \`--refresh\` will not merge or reset someone else's checkout to make one:
   that decision is yours. Rebase or merge it yourself, then warm again. The
   message reports both counts. Nothing was installed or copied.`
-			},
-			STIM_DEPS_INCOMPLETE: {
-				summary: "the last install recorded for the lockfile on disk now did not finish, so warm will not copy it",
-				body: () => `STIM_DEPS_INCOMPLETE
+		},
+		STIM_DEPS_INCOMPLETE: {
+			summary: "the last install recorded for the lockfile on disk now did not finish, so warm will not copy it",
+			body: () => `STIM_DEPS_INCOMPLETE
   \`worktree warm\` refuses to copy dependencies the source checkout never
   finished installing. \`--refresh\` records a COMPLETED install of the lockfile
   it read under ~/.stim/warm-installs; an install that failed, or whose process
@@ -2283,20 +2460,20 @@ not on any remote"  (worktree remove)
   repository before its first \`--refresh\` -- copies as it always has.
   In a monorepo the record is keyed on the directory that owns the lockfile,
   which is usually the repository root, so every app of it reads the same one.`
-			},
-			warm: {
-				summary: "worktree warm claim storage refusals and recovery",
-				body: () => `Both plain warm and --refresh require an ownership claim.
+		},
+		warm: {
+			summary: "worktree warm claim storage refusals and recovery",
+			body: () => `Both plain warm and --refresh require an ownership claim.
   Permission-denied or read-only claim storage reports STIM_CLAIM_UNAVAILABLE
   and names the path. Restore access to the existing claim store and retry.
   A non-directory claim ancestor reports STIM_CLAIM_REFUSED and names the
   blocking file. Inspect it and use the printed move-aside command to preserve
   its contents before retrying. See guide errors STIM_CLAIM_UNAVAILABLE and
   guide errors STIM_CLAIM_REFUSED for the recovery details.`
-			},
-			carry: {
-				summary: "worktree warm copy results, lockfile mismatches, and remedies",
-				body: () => `"carry       incomplete: ... ignored entries copied, ... kept, ... failed"
+		},
+		carry: {
+			summary: "worktree warm copy results, lockfile mismatches, and remedies",
+			body: () => `"carry       incomplete: ... ignored entries copied, ... kept, ... failed"
 (worktree warm)
   At least one entry could not be copied. The command exits 1 and names each
   failure. Existing entries stay untouched; any files already published remain.
@@ -2325,11 +2502,11 @@ not on any remote"  (worktree remove)
   the app is ready, unless \`--refresh\` installed them in the SOURCE CHECKOUT
   first; even then the copy can still carry a lockfile this branch does not
   have, which is exactly what these carry warnings report.`
-			},
-			environment: {
-				summary: "npx registry E401/E404, the Node floor, no free Metro port, the reservation race",
-				separator: "--- ENVIRONMENT ---",
-				body: () => `"npm error code E401 / E404" while \`npx\` resolves the stim package
+		},
+		environment: {
+			summary: "npx registry E401/E404, the Node floor, no free Metro port, the reservation race",
+			separator: "--- ENVIRONMENT ---",
+			body: () => `"npm error code E401 / E404" while \`npx\` resolves the stim package
   The repo probably pins a private registry in \`.npmrc\`, so \`npx\` looked for
   the package there instead of on npm. Use the public registry for this command:
 
@@ -2350,10 +2527,10 @@ not on any remote"  (worktree remove)
 "Could not reserve a Metro port after 5 attempts"
   Several commands raced for the same ports and each one lost. Nothing is
   wrong; retry.`
-			},
-			sandbox: {
-				summary: "running under a sandboxing harness: EPERM under STIM_HOME, CoreSimulatorService, adb",
-				body: () => `RUNNING UNDER A SANDBOX
+		},
+		sandbox: {
+			summary: "running under a sandboxing harness: EPERM under STIM_HOME, CoreSimulatorService, adb",
+			body: () => `RUNNING UNDER A SANDBOX
 
   An agent harness that sandboxes shell commands typically permits writes
   inside the project and blocks the rest. Three things Stim needs sit outside
@@ -2400,21 +2577,37 @@ not on any remote"  (worktree remove)
 
   A git credential helper is often blocked too. It prints \`failed to store\`
   on a fetch that otherwise succeeded, and is safe to ignore.`
-			},
-			STIM_CONFIG_CORRUPT: {
-				summary: "~/.stim/config.json is not valid JSON and Stim never resets it",
-				body: () => `STIM_CONFIG_CORRUPT  ("Stim config at <path> is not valid JSON")
+		},
+		STIM_CONFIG_CORRUPT: {
+			summary: "~/.stim/config.json is not a valid JSON object and Stim never resets it",
+			body: () => `STIM_CONFIG_CORRUPT  ("Stim config at <path> is not valid JSON",
+                     "... is not a JSON object",
+                     "... has a projects that is not an object",
+                     "... has a projects entry "<key>" that is not an object")
   Any command can raise it: every command reads ~/.stim/config.json first.
-  The file holding every owned-device record will not parse, and Stim never
+  The file holding every owned-device record will not parse into an object,
+  or its projects or repos registry or one of their entries is not an object
+  (a bare [], null or number counts as corrupt, not empty), and Stim never
   resets it for you -- a silent reset would orphan every simulator it names.
   Repair the file, or move it aside (\`mv <path> <path>.broken\`) and accept
   that the devices it recorded become orphans you delete by hand.`
-			}
+		},
+		STIM_RELATIVE_PATH: {
+			summary: "STIM_HOME, STIM_BUILD_CACHE or STIM_METRO_CACHE is set to a relative path",
+			body: () => `STIM_RELATIVE_PATH  ("<NAME>=<value> is not an absolute path")
+  Any command refuses before it reads or writes state. A relative value would
+  resolve against each process's working directory, so the CLI, Metro and the
+  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.`
 		}
-	},
-	lifecycle: {
-		summary: "The full worktree -> start -> ios/android -> logs -> teardown flow, with sections for builds, devices and flags",
-		preamble: () => `ENVIRONMENT LIFECYCLE
+	}
+};
+//#endregion
+//#region src/guide/lifecycle.ts
+const lifecycle = {
+	summary: "The full worktree -> start -> ios/android -> logs -> teardown flow, with sections for builds, devices and flags",
+	preamble: () => `ENVIRONMENT LIFECYCLE
 
 Two workflows share steps 2 through 6.
 
@@ -2588,8 +2781,10 @@ Permanent local deletion lives in exactly TWO commands: \`worktree remove\`
 (the workspace you name) and \`gc --delete\` (the machine). For a local device,
 \`stop\` shuts it down and never deletes it. For a recorded EAS session,
 \`stop\` irreversibly ends the session. Externally started servers are left
-alone, even when they use the reserved port. There is no \`--delete\` flag on
-\`stop\`.
+alone, even when they use the reserved port, and the reservation is kept while
+one answers from the project. A dev server whose supervisor died is stopped
+only when its recorded process identity still matches. There is no
+\`--delete\` flag on \`stop\`.
 
 CAPACITY
   A booted iOS sim is roughly 1-2 GB of RAM, an Android emulator 2-3 GB. On a
@@ -2598,14 +2793,25 @@ CAPACITY
   machine, not just this one.
 
 TWO REPORTS, TWO QUESTIONS
-  "What is running" is \`stim status\`: live state, right now. "How much the
+  "What is running" is \`stim status\`: live state, right now, including
+  each running ios or android build's phase and time left (see
+  \`guide facts status\`). "How much the
   cache saved" is \`stim stats\`: aggregate counters for this project and for
   the machine, with a hit rate and an estimate of the time saved (see
-  \`guide facts stats\`).`,
-		sections: {
-			eas: {
-				summary: "download a matching EAS development build; explicit profile, costs, cache and miss remedies",
-				body: () => `EAS DEVELOPMENT BUILDS
+  \`guide facts stats\`).
+
+WAITING FOR A CHANGE
+  To wait for a device, a build or a dev server instead of polling, run
+  \`stim status --watch --json\`. It keeps running and prints one complete
+  status payload per line: one at once, then one each time the payload
+  changes, never two identical ones in a row. It reacts to Stim state files,
+  the EAS session ledger, adb device arrivals and departures, and simulator
+  state, and recomputes every 30 seconds as a fallback. Ctrl+C, SIGTERM or
+  closing its stdout ends it with exit 0. 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",
+			body: () => `EAS DEVELOPMENT BUILDS
 
   stim ios --eas-profile ios-simulator
   stim android --eas-profile development
@@ -2678,10 +2884,10 @@ flag exists, and Stim never starts a cloud build or falls back to local
 compilation in this mode. Authentication, network, invalid output or download
 failures produce STIM_EAS_UNAVAILABLE, with the failed EAS command to inspect.
 If another run holds the artifact claim, wait for it to finish and retry.`
-			},
-			readiness: {
-				summary: "implement optional pending/ready app logs, deadlines, errors, and platform isolation",
-				body: () => `OPTIONAL APP READINESS
+		},
+		readiness: {
+			summary: "implement optional pending/ready app logs, deadlines, errors, and platform isolation",
+			body: () => `OPTIONAL APP READINESS
 
 No package or SDK is needed. This applies to debug ios/android launches with
 Metro verification enabled, not release builds or --no-metro-check.
@@ -2741,10 +2947,10 @@ including when device logs are unavailable, the default check applies.
 The app declares readiness; Stim does not inspect a rendered frame. This does
 not change launched JSON semantics or the need to inspect the expected UI and
 stim logs --errors. A reload request does not run this launch check.`
-			},
-			verification: {
-				summary: "reproduce the affected behavior, verify the change on the reported device, and retain proof",
-				body: () => `VERIFY THE CHANGE
+		},
+		verification: {
+			summary: "reproduce the affected behavior, verify the change on the reported device, and retain proof",
+			body: () => `VERIFY THE CHANGE
 
 For a UI change or bug fix, decide what observable result would prove the task
 is complete. A successful build, a live process, or an empty log query does
@@ -2774,10 +2980,10 @@ not prove that result.
 
 For a change without a UI effect, use the relevant runtime output or test
 result as proof instead of requiring an unrelated screenshot.`
-			},
-			progress: {
-				summary: "phase lines, the label set, heartbeats and their ~ estimate, what warm, start, stop and remove print",
-				body: () => `PROGRESS ON A LONG RUN
+		},
+		progress: {
+			summary: "phase lines, the label set, heartbeats and their ~ estimate, what warm, start, stop and remove print",
+			body: () => `PROGRESS ON A LONG RUN
   Native build progress goes to stderr. In \`--json\` mode, stdout carries only
   the result payload. Plain \`start\` also prints progress on stdout. Every
   progress line has the same shape -- two spaces, a label padded to eleven
@@ -2897,10 +3103,10 @@ result as proof instead of requiring an unrelated screenshot.`
   until it returns; the next heartbeat then lands on the grid, which is why an
   elapsed value can jump. Read the phase lines, not the wall clock, before
   killing a run.`
-			},
-			pool: {
-				summary: "parked and adopted simulators: what park and adoption clear or keep, the model and runtime match",
-				body: () => `  THE SIMULATOR POOL
+		},
+		pool: {
+			summary: "parked and adopted simulators: what park and adoption clear or keep, the model and runtime match",
+			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. A simulator that has booted before boots in about 9s; a freshly
@@ -3021,10 +3227,10 @@ result as proof instead of requiring an unrelated screenshot.`
   Set the Android bound to 0 when a project needs a fresh device. Status lists
   parked Android emulators; GC reports their system image, age and disk size.
 `
-			},
-			builds: {
-				summary: "optional cache warm-up, build optimizations, fingerprints, .fingerprintignore, install unchanged, runtime state",
-				body: () => `OPTIONAL CACHE WARM-UP FOR REPEATED NATIVE WORK
+		},
+		builds: {
+			summary: "optional cache warm-up, build optimizations, fingerprints, .fingerprintignore, install unchanged, 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
   build for one-off or JavaScript-only work. For local simulator or emulator
@@ -3091,7 +3297,9 @@ 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; nothing per run is kept there.
+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
+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
 sources, and pod install can update Podfile.lock. Review those changes before
@@ -3320,10 +3528,10 @@ WHAT MAKES THE CACHE ACTUALLY HIT: .FINGERPRINTIGNORE
   mismatch naming the differing sources. Untracked, non-gitignored files under
   ios/ or android/ count too -- they are hashed like any other source, so a
   stray file there moves the key on your machine and nowhere else.`
-			},
-			concurrency: {
-				summary: "waiting on another workspace's build, --no-build-cache, concurrency.maxBuilds and maxDevices",
-				body: () => `ONE COMPILE PER FINGERPRINT, ACROSS EVERY WORKSPACE
+		},
+		concurrency: {
+			summary: "waiting on another workspace's build, --no-build-cache, concurrency.maxBuilds and maxDevices",
+			body: () => `ONE COMPILE PER FINGERPRINT, ACROSS EVERY WORKSPACE
   The cache makes the SECOND workspace on a commit free -- but only once the
   first has finished. Three agents starting within the same minute all miss it,
   and without this all three compile the same app at once, fighting for the
@@ -3347,10 +3555,15 @@ WHAT MAKES THE CACHE ACTUALLY HIT: .FINGERPRINTIGNORE
   Nothing can deadlock on it. The lock records the holder's process IDENTITY,
   so a builder that crashes, is killed, or whose build simply fails frees it:
   the waiters see a released lock with no artifact, and one of them takes over
-  and builds. A recycled pid reads as a gone builder, and a builder busy in a
-  long synchronous tool call reads as live -- age is never a reason to take a
-  lock. The one state that cannot be decided (a truncated claim, an identity
-  token that does not decode) is STIM_CLAIM_REFUSED: Stim names the claim and
+  and builds. The xcodebuild, Gradle, pod install or expo prebuild it spawned
+  is recorded on the lock, its build slot and the workspace's native run, so a
+  builder killed while that tool keeps running (SIGTERM to the stim pid alone)
+  frees them only when the tool exits. A recycled builder pid reads as a gone
+  builder, and a builder busy in a long synchronous tool call reads as live --
+  age is never a reason to take a lock. A state that cannot be decided (a
+  truncated claim, an identity token that does not decode, a builder killed
+  between spawning its build tool and recording it, a recorded build tool
+  whose pid was since reused) is STIM_CLAIM_REFUSED: Stim names the claim and
   the command that removes it rather than guessing. A process whose own identity
   cannot be captured takes no lock and no slot, and refuses with
   STIM_CLAIM_UNAVAILABLE rather than building unprotected. The
@@ -3394,26 +3607,28 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
 
   \`stim doctor\` prints one note echoing the caps and the current live count,
   but ONLY when a cap is set. \`stim gc\` reports stale build slots the way it
-  reports stale build locks, and \`gc --delete\` clears them. There is no
-  \`stim config\` command: set these by editing ~/.stim/config.json or via
-  the two env vars (see \`guide settings\`).`
-			},
-			options: {
-				summary: "every flag per command, Android variants and flavors, the per-run simulator model, runtime and system image",
-				body: () => `THE OPTION SURFACE, IN FULL
+  reports stale build locks, and \`gc --delete\` clears them. Set the caps
+  with \`stim settings set concurrency.maxBuilds 2\`, by editing
+  ~/.stim/config.json, or via the two env vars (see \`guide settings\`).`
+		},
+		options: {
+			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 --no-metro-check --no-build-cache --scheme <name> --configuration <name> --device-type <name> --runtime <version> --simulator-app <xcode|siniulator> --device [udid] --wait <seconds> --no-wait --remote <proxy|eas>
+  ios             --slot <name> --json --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 --no-metro-check --no-build-cache --variant <name> --system-image <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
   logs            --slot <name> --source --level --since --grep --tail --follow --errors --json
   stop            --slot <name> --json
-  status          --json          (already machine-wide)
+  status          --json --watch  (already machine-wide)
   stats           --json          (this project and machine-wide)
+  settings        --json; get <key> --scope <layer> --json;
+                  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>
+  gc              --delete --older-than <days> --cache <name|all|workspaces> --worktrees --json
   worktree warm    --refresh; remove [path] --force
 
   DEVICE SLOTS
@@ -3424,7 +3639,7 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   the workspace's existing assignment.
 
     stim ios --slot phone
-    stim ios --slot tablet --device-type "iPad Pro 13-inch (M4)"
+    stim ios --slot tablet --device-type "iPad Pro 13-inch (M5)"
     stim ios --slot hardware --device <udid>
     stim android --slot second-phone
     stim logs --slot tablet --source device
@@ -3459,6 +3674,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.
 
+  \`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
+  default one -- only once the repository has at least one linked worktree. A
+  single-checkout session is never told that its own branch is a problem.
+
   \`--refresh\` WRITES TO THE SOURCE CHECKOUT before the copy, which is why it
   is opt-in: it checks the upstream, fetches changes when needed, and fast-forwards
   whatever branch is checked out there to its \`@{upstream}\`, and installs
@@ -3588,8 +3809,8 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
 
   \`ios --device-type <name>\` and \`ios --runtime <version>\` choose the
   MODEL and the iOS version of the simulator this workspace owns --
-  \`--device-type "iPad Pro 13-inch (M4)" --runtime 18.5\` is how a ticket that
-  says "happens on iPad on iOS 18.5" gets reproduced without writing a
+  \`--device-type "iPad Pro 13-inch (M5)" --runtime 26.5\` is how a ticket that
+  says "happens on iPad on iOS 26.5" gets reproduced without writing a
   \`.stim.json\`. \`android --system-image <id>\` is the Android half, taking
   the sdkmanager package id
   ("system-images;android-36;google_apis;arm64-v8a"). Each overrides its
@@ -3620,10 +3841,10 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   version it was made with. The --json payload reports what was actually
   used: \`deviceType\` and \`runtime\` on iOS, \`systemImage\` on Android,
   read from the device itself, so a settings-driven run reports them too.`
-			},
-			devices: {
-				summary: "ios --device and android --device on a phone: what the run skips, signing, the LAN wiring, the collector",
-				body: () => `  \`android --device [serial]\` installs and launches on a physical device
+		},
+		devices: {
+			summary: "ios --device and android --device on a phone: what the run skips, signing, the LAN wiring, the collector",
+			body: () => `  \`android --device [serial]\` installs and launches on a physical device
   connected to this machine instead of this workspace's owned emulator. With
   no serial it takes the first device it can lease (\`guide lifecycle lease\`).
   It cannot be combined with --remote.
@@ -3648,6 +3869,24 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   \`android --device\`, it leases the phone for the run
   (\`guide lifecycle lease\`).
 
+  AN IPHONE PAIRED OVER WI-FI is a device too: devicectl reports its
+  transportType as localNetwork. Only a physical iPhone or iPad counts
+  (devicectl platform iOS, reality physical); an Apple TV, a Vision Pro, a
+  simulator, or a paired phone devicectl reports unavailable is never picked.
+  A UDID that names a Wi-Fi phone is accepted. With no UDID, a healthy
+  cabled iPhone always wins, and a busy one is waited for; a Wi-Fi one is
+  taken only when no cabled one is paired with Developer Mode on, and a busy
+  refusal names any free Wi-Fi phone so \`--device <udid>\` can take it.
+  The transport is read again just before the install, so a cable pulled
+  during the build still gets Wi-Fi treatment, and the run prints one
+  \`device\` line saying the install and launch go over Wi-Fi. Over Wi-Fi
+  each devicectl install step may take 15 minutes instead of 5 and the launch
+  120 seconds instead of 45; the lease is raised before each step, including
+  the uninstall and reinstall of a signer conflict. A Wi-Fi install or launch
+  that times out or loses the phone fails with STIM_DEVICE_WIRELESS_FAILED,
+  and the remedy is the cable. Metro is unaffected: a Debug app reaches it
+  over the LAN either way.
+
   \`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;
@@ -3729,10 +3968,10 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   by hashing the installed container; there is no cheap equivalent through
   devicectl, so a device run always installs. It is an upgrade install: the
   app's data, and the Local Network permission the phone granted it, survive.`
-			},
-			lease: {
-				summary: "run-scoped leases, --wait and --no-wait, device lock and unlock, which phone an id-less --device picks",
-				body: () => `THE DEVICE LEASE ON A \`--device\` RUN
+		},
+		lease: {
+			summary: "run-scoped leases, --wait and --no-wait, device lock and unlock, which phone an id-less --device picks",
+			body: () => `THE DEVICE LEASE ON A \`--device\` RUN
   A physical device is shared, so a \`--device\` run takes a lease on it. The
   lease step sits AFTER the build (a build touches no device) and before the
   install, and the run releases what it took when the command exits: on
@@ -3800,13 +4039,15 @@ HOLDING A DEVICE ACROSS RUNS
 
 THE POOL: WHICH DEVICE AN ID-LESS \`--device\` PICKS
   Candidates are the connected devices the resolver already accepts: on iOS,
-  wired, paired, with Developer Mode on; on Android, every serial adb reports
-  in the \`device\` state that is not an emulator, TCP serials included. Then,
-  in order:
+  paired, with Developer Mode on, over a cable or Wi-Fi; on Android, every
+  serial adb reports in the \`device\` state that is not an emulator, TCP
+  serials included. Then, in order:
 
     1. the device this workspace already leases, when it is among them;
     2. otherwise the first one not leased -- or leased and EXPIRED -- in
-       case-folded id order.
+       case-folded id order. On iOS a Wi-Fi iPhone is considered only when
+       no cabled candidate is connected: a busy cabled phone is waited for,
+       not skipped for a Wi-Fi one.
 
   Ids are sorted on, never names: adb has no name without one \`getprop\` per
   serial, and models repeat.
@@ -3826,10 +4067,10 @@ THE POOL: WHICH DEVICE AN ID-LESS \`--device\` PICKS
   The chosen device is on the phase line and in \`--json\` (\`udid\` or
   \`serial\`, plus \`deviceName\`), so an agent can hand the same id to its
   device tool.`
-			},
-			release: {
-				summary: "Release configurations and ...Release variants: Metro skipped, process-proven launch, the JS swap",
-				body: () => `  A VARIANT WHOSE NAME ENDS IN "Release" IS A RELEASE BUILD (\`release\`,
+		},
+		release: {
+			summary: "Release configurations and ...Release variants: Metro skipped, process-proven launch, the JS swap",
+			body: () => `  A VARIANT WHOSE NAME ENDS IN "Release" IS A RELEASE BUILD (\`release\`,
   \`productionRelease\`), and that is the whole opt-in -- there is no second
   flag. It is the Android half of \`ios --configuration Release\` and behaves
   the same way: AGP's bundle task embeds the JS, so Metro is skipped ENTIRELY
@@ -3902,10 +4143,10 @@ THE POOL: WHICH DEVICE AN ID-LESS \`--device\` PICKS
   builds the \`iphoneos\` slice for a cabled iPhone and keys its cache
   \`-device\` instead of \`-sim\`, but does not install it yet. Archives,
   \`.ipa\` export, store signing and distribution stay out of scope.`
-			},
-			simslim: {
-				summary: "recommended SimSlim profiles and recovery from host memory pressure",
-				body: () => `SIMSLIM FOR PARALLEL IOS WORK
+		},
+		simslim: {
+			summary: "recommended SimSlim profiles and recovery from host memory pressure",
+			body: () => `SIMSLIM FOR PARALLEL IOS WORK
   SimSlim is recommended as an optional way to reduce simulator background
   services and memory use, especially with several workspaces. Review which
   services your app and tests need; a slim profile can disable those features.
@@ -3952,8 +4193,9 @@ HOST MEMORY PRESSURE AND STALLED SIMULATORS
   a final boot-state query can take 30 seconds. After boot, Stim opens the owned
   simulator in the selected Xcode's Device Hub on Xcode 27, or Simulator on
   older Xcode. Top-level iosSimulatorApp in the machine config can select
-  Siniulator instead; see guide settings. Override it for one local run with
-  \`stim ios --simulator-app siniulator\` or \`--simulator-app xcode\`. This also
+  Siniulator or Stim Desktop instead; see guide settings. Override it for one
+  local run with \`stim ios --simulator-app siniulator\`,
+  \`--simulator-app stim-desktop\`, or \`--simulator-app xcode\`. This also
   opens an already running owned simulator without rebooting it or saving the
   preference. The flag refuses physical and remote targets, including ios.remote.
   Opening the window is best-effort
@@ -3974,12 +4216,14 @@ HOST MEMORY PRESSURE AND STALLED SIMULATORS
   agents' simulators or heavy apps. Rebooting a simulator under the same pressure
   can repeat the stall. Consider fewer concurrent builds/devices (guide lifecycle
   concurrency) and a reviewed SimSlim profile for future runs.`
-			}
 		}
-	},
-	cleanup: {
-		summary: "Where simulators come from, and how they get reclaimed",
-		preamble: () => `DEVICE SLOTS
+	}
+};
+//#endregion
+//#region src/guide/cleanup.ts
+const cleanup = {
+	summary: "Where simulators come from, and how they get reclaimed",
+	preamble: () => `DEVICE SLOTS
 
 Cleanup enumerates every slot. stop --slot <name> keeps the shared server and
 other slots; plain stop and worktree remove handle the whole workspace.
@@ -3997,11 +4241,17 @@ WHAT RECLAIMS AN OWNED DEVICE
   stim gc --delete        sweeps stim-* devices no project references, and
                             clears verified parked simulators and emulators
   stim gc --delete --older-than <days>
-                            also reaps the device of a project nothing has
-                            touched in that long, even though the project is
-                            still on disk
-
-Those are the only two commands that delete. \`stim stop\` shuts a device
+                            also reaps the device of a workspace no Stim
+                            command has used in that long, even though the
+                            project is still on disk
+  stim gc --delete --worktrees
+                            runs \`stim worktree remove\` on every clean, idle,
+                            Stim-managed linked worktree (\`guide cleanup gc\`)
+
+\`worktree remove\` and \`gc --delete\` are the only two commands that delete;
+\`gc --delete --worktrees\` deletes only through \`worktree remove\`. \`gc
+--delete\` also clears workspace build outputs (\`guide cleanup disk\`) and
+orphaned workspace directories, never a checkout. \`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.
 
@@ -4021,17 +4271,65 @@ start the counters over. A file this version cannot read -- unparseable, or
 written by a newer Stim -- costs one dim line on stderr and is otherwise left
 alone; only the next \`ios\` or \`android\` run moves an unparseable one aside
 to stats.json.corrupt-<unix ms> and starts a new one.`,
-		sections: {
-			gc: {
-				summary: "what gc and worktree remove delete, keep and refuse: orphans, stale records, locks, leases, EAS sessions",
-				body: () => `LINKED WORKTREES
+	sections: {
+		gc: {
+			summary: "what gc and worktree remove delete, keep and refuse: orphans, stale records, locks, leases, EAS sessions",
+			body: () => `LINKED WORKTREES
   \`stim worktree remove\` works with any linked worktree, warmed or not.
   Git registration identifies the worktree; a Stim registry entry is not
-  required. The command reclaims any owned resources it finds, checks for
-  uncommitted and unpushed work, and removes the linked checkout. Git-created
+  required. Before it reclaims anything, the command refuses a worktree git
+  has locked (unlock it first; --force does not override) and, without
+  --force, uncommitted or unpushed work and initialized submodules. It then
+  reclaims any owned resources it finds and removes the linked checkout.
+  When git still refuses the removal, the kept ownership record no longer
+  names the devices that were parked or deleted. A workspace that is in use
+  (see IN USE below) keeps its directory, devices and registry entry, and the
+  command reports why. Git-created
   branches stay. A branch with an existing Stim ownership record is deleted
   only when it has no unique commits.
 
+IN USE
+  gc and worktree remove never delete a workspace's directory, build outputs
+  or checkout while it is in use: its dev server supervisor is running or
+  cannot be verified, a \`stim ios\`, \`stim android\` or \`stim stop\` run
+  holds its native-run.lock, a live or unresolvable build lock or slot names it,
+  or its managed tunnel or managed remote lock is held. The deletion holds
+  native-run.lock itself, so no native run can start partway through. A lock
+  that names no workspace blocks nothing, because every build also holds its
+  own workspace's native-run.lock; gc lists it with the command that removes
+  it. \`worktree remove\` re-checks uncommitted and unpushed work under its
+  removal locks, just before it reclaims anything. A project root whose
+  existence cannot be read (a permission error) is never treated as deleted.
+
+SWEEPING FINISHED WORKTREES
+  \`gc --worktrees\` is opt-in; no cache or age flag implies it. It looks at
+  every registered project root and every workspace.json root, grouped by
+  git worktree, and reports each worktree with the reason it is kept:
+  source checkout, bare, locked, in use, dirty (untracked files count; pod
+  install churn alone does not), unpushed (commits no remote-tracking ref or
+  other local branch reaches), initialized submodules, or recently used.
+  Idle means no recorded use for --older-than days, 7 without it; a worktree
+  whose last use is unknown is kept. --cache with --worktrees is refused with
+  STIM_BAD_ARG; run them separately.
+    stim gc --worktrees --older-than 3            # report only
+    stim gc --delete --worktrees --older-than 3   # remove the clean idle ones
+  With --delete it runs the \`stim worktree remove\` pipeline, never --force,
+  on each removable worktree. That pipeline re-inspects the worktree and
+  re-checks use and idleness under the removal locks, then parks devices and
+  handles the branch exactly as a manual \`stim worktree remove\`. A worktree
+  that became busy or recently used since the report is kept with the reason.
+  A worktree that fails is reported, gc exits 1, and the sweep continues.
+
+ORPHANED WORKSPACE DIRECTORIES
+  A worktree deleted with \`git worktree remove\`, \`rm -rf\` or a /tmp wipe
+  leaves its $STIM_HOME/workspaces/<name> directory behind with no registry
+  entry. \`gc\` reads each directory's workspace.json and reports it under
+  "Orphaned workspace directories" when the recorded project root is gone,
+  its volume is mounted, no registry key equals it or sits under it, and the
+  workspace is not in use. \`gc --delete\` re-checks each one, then removes
+  it. A directory with a missing or unparseable workspace.json, or a root on
+  an unmounted volume, is reported under Skipped and never deleted.
+
 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
@@ -4095,7 +4393,8 @@ A device leaks when a project is abandoned WITHOUT either delete path -- the
 sim survives with nothing pointing at it. \`stim gc\` (no flag, writes
 nothing, always safe) reports those; \`gc --delete\` reaps them, and in the same
 run drops the dead config ENTRIES those projects left behind and frees their
-Metro ports.
+Metro ports. \`stim gc --json\` prints the same report as one payload
+(\`guide facts gc\`); show the user its sections before \`gc --delete\`.
 
 REMOTE EAS SESSIONS
   Plain \`stim gc\` is a dry run. \`gc --delete\` can stop active stim-* EAS
@@ -4131,10 +4430,10 @@ THE ONE CASE GC WILL NOT REAP
   it found, so you can judge. Delete them yourself:
     xcrun simctl delete <udid>
     avdmanager delete avd -n <name>`
-			},
-			collector: {
-				summary: "log collector reaping: an unproven collector pid, and why the app on a phone closed",
-				body: () => `WHAT ELSE STOP REAPS
+		},
+		collector: {
+			summary: "log collector reaping: an unproven collector pid, and why the app on a phone closed",
+			body: () => `WHAT ELSE STOP REAPS
   The device-log collectors (\`simctl log stream\` / \`adb logcat\`) that
   \`ios\` / \`android\` attach after launch. They are recorded in
   the global workspace state.json, and nothing outside this workspace can name them,
@@ -4188,12 +4487,14 @@ 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.`
-			},
-			disk: {
-				summary: "disk usage, AVD and build-log sizes, the data partition, trimming the shared caches",
-				body: () => `DISK
+		},
+		disk: {
+			summary: "disk usage, workspace build outputs, 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. Gradle retains its normal
+  directory, and \`worktree remove\` reclaims them. \`gc --delete\` clears the
+  build outputs of workspaces nobody is using (WORKSPACE BUILD OUTPUTS
+  below) and keeps the rest. Gradle retains its normal
   project build directories while sharing task outputs through its build cache.
 
   Android AVDs normally live under ~/.android/avd, and a booted owned AVD can
@@ -4235,6 +4536,28 @@ project needs another size. Android userdata grows but does not shrink, so the
 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
+  \`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.
+    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,
+  supervisor.startedAt and the mtimes under logs/, so a dev server that keeps
+  logging keeps its workspace in use.
+  The same time decides \`--older-than\` device reaping, and a workspace with
+  no evidence of use keeps its device.
+  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.
+
 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,
@@ -4253,24 +4576,68 @@ SHARED BUILD CACHES
   The Gradle build cache under GRADLE_USER_HOME (default ~/.gradle) is
   report-only because every Gradle build shares it. Stim reports its size
   but never prunes or empties it, including with --older-than or --cache all.
+
   Trim rather than empty. Emptying costs the next build in every project the
   time the cache was saving.`
-			}
 		}
-	},
+	}
+};
+const SETTINGS_SCHEMA_URL = `https://unpkg.com/stim/dist/settings.schema.json`;
+//#endregion
+//#region src/guide/index.ts
+const TOPICS = {
+	agent: agent_default,
+	facts,
+	metro: metro_default,
+	ports: ports_default,
+	logs: logs_default,
+	errors,
+	lifecycle,
+	cleanup,
 	settings: {
 		summary: "Settings Stim reads, and where they can live",
 		body: () => `SETTINGS
 
-There is no \`stim config\` command. Settings are JSON files, edited by
-hand or committed; command-line selectors override their matching settings.
+Settings are JSON: machine layers in ~/.stim/config.json and a committed
+.stim.json. Command-line selectors override their matching settings.
+
+  stim settings --json            every setting: effective value, origin
+                                  (workspace, repo, committed, machine, env,
+                                  default), and each layer's value
+  stim settings get <key> [--scope <layer>] [--json]
+  stim settings set <key> <value> --scope <layer> [--json]
+  stim settings unset <key> --scope <layer> [--json]
+
+<layer> is machine, workspace (this project's entry), repo (this repository's
+git common dir), or committed (.stim.json). Each key accepts only the layers
+Stim reads it from; --scope may be omitted when a key has one layer. Strings
+and choices are passed as-is; booleans, numbers, arrays, and objects as JSON
+(\`'["node_modules"]'\`). A value of the wrong shape, a layer the key is not
+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
+repository. worktree.exclude and worktree.defaultBranch are read only from
+the repo layer and the repository root's .stim.json.
+
+android.keystorePassword is sensitive: its value prints as ******** in every
+output, and a committed .stim.json takes only an \`env:\` or \`file:\`
+reference, never the password itself.
+
+The JSON Schema for .stim.json ships in the stim package as
+dist/settings.schema.json. Point an editor at it with a top-level
+"$schema": "${SETTINGS_SCHEMA_URL}"; Stim ignores
+that key. $defs.machine describes the machine settings, and every setting
+carries its dotted key, layers, and environment override under "x-stim".
 
 Resolution order, first match wins:
-  1. project layer   ~/.stim/config.json, under this project's entry
-  2. repo layer      ~/.stim/config.json, under this repo's git common dir
+  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 defaults  ~/.stim/config.json, top-level optimizations only
+  4. machine         ~/.stim/config.json, top-level optimizations only
   5. Stim default
+An environment override, where a setting has one, wins over every layer.
 
 The committed file is plain JSON and travels with the app. Each monorepo app
 reads its own file, never an ancestor's runtime settings. A single-app repository
@@ -4291,8 +4658,7 @@ An app's .stim.json can contain:
       "runtime": "26.2",
       "simslimProfile": ".simslim/dev.json"
     },
-    "android": { "variant": "productionDebug" },
-    "caches": ["~/.myapp-metro-cache"]
+    "android": { "variant": "productionDebug" }
   }
 
 KEYS STIM READS
@@ -4496,16 +4862,21 @@ ${ANDROID_AVD_CONFIG_HELP.map((line) => `                          ${line}`).joi
                         store Stim injects for you (bare in-process, or the
                         Expo config override) stays local-only.
   cache.options         free-form object handed to that module's factory. It
-                        merges key by key across settings layers. Keep secrets
-                        out of the committed file: read them from the
-                        environment or the machine layers.
-  caches                extra shared-cache paths for \`gc\` to report. A JSON
-                        array; every path is treated as a flat store.
+                        merges key by key from the layer that names the
+                        provider, higher layers that name none, and lower
+                        layers that name the same provider resolved from the
+                        same directory. Options in a layer naming another
+                        provider, or in a lower layer naming none, are
+                        ignored. Keep secrets out of the committed file: read
+                        them from the environment or the machine layers.
 
 Each setting takes its documented type: string, array of strings, number,
-boolean, or object. A value of the wrong type is
-refused by name on every command that resolves settings, so a wrong shape never
-falls back to a default silently. \`stim doctor\` reports it as a finding
+boolean, or object. ios.remote, android.remote, metro.tunnel,
+optimizations.android.compilerCache and optimizations.android.pch take only
+their listed choices. A value of the wrong
+type or outside those choices is refused by name on every command that resolves
+settings, \`stim ios\` included, so a wrong shape never falls back to a default
+silently. \`stim doctor\` reports it as a finding
 instead of refusing. The exception is \`optimizations.android.casToolchain\`:
 an invalid value warns and falls back to ccache, or no compiler cache when
 \`compilerCache\` is \`none\`. \`doctor\` also reports the invalid setting.
@@ -4519,19 +4890,22 @@ removed -- check this list rather than assuming it still applies.
 problem. It reports, as notes naming the key, the file it came from, and the
 line that clears it: a setting whose path no longer exists, a setting that needs
 a companion the config does not supply, a key Stim no longer reads, and a
-config file that is not valid JSON. It skips the \`projects\` registry, where an
-entry for a deleted checkout is normal and \`gc\` owns the cleanup.
+config file that is not a valid JSON object. It skips the \`projects\`
+registry, where an entry for a deleted checkout is normal and \`gc\` owns the
+cleanup.
 
 CONCURRENCY LIMITS ARE MACHINE-LEVEL, NOT A PER-PROJECT SETTING
 The caps above are not in the layered settings -- they are not per-project,
 because the resource they share (cores, RAM, booted simulators) is the whole
 machine's. They live under a top-level \`concurrency\` key in
-~/.stim/config.json, edited by hand:
+~/.stim/config.json, set with \`stim settings set\` or by hand:
 
   {
     "concurrency": { "maxBuilds": 2, "maxDevices": 3 }
   }
 
+The keys are concurrency.maxBuilds and concurrency.maxDevices.
+
 or via the environment, which overrides the file:
 
   STIM_MAX_BUILDS=2 STIM_MAX_DEVICES=3 stim ios
@@ -4548,16 +4922,24 @@ or Simulator on older Xcode. To use an installed Siniulator instead:
 
   { "iosSimulatorApp": "siniulator" }
 
+To show the booted simulator in Stim Desktop and open no simulator window:
+
+  { "iosSimulatorApp": "stim-desktop" }
+
+Stim Desktop selects the workspace that owns the simulator and focuses that
+device. It only displays the simulator; it never boots or shuts it down.
+
 Override the preference for one local launch with
-\`stim ios --simulator-app siniulator\` or \`stim ios --simulator-app xcode\`.
+\`stim ios --simulator-app siniulator\`, \`stim ios --simulator-app stim-desktop\`,
+or \`stim ios --simulator-app xcode\`.
 The flag also opens an already running owned simulator without rebooting it.
 It leaves the saved preference unchanged and refuses physical or remote targets.
 
 Stim still creates and boots its owned simulator. An invalid value refuses
-before boot. Opening a window remains best-effort, so install Siniulator before
-selecting it. By default, closing a Siniulator device window shuts down that
-simulator. Enable "Leave simulator running after window is closed" in Siniulator
-Settings if Stim should keep it running. See \`guide lifecycle simslim\` for
+before boot. Opening a window remains best-effort, so install Siniulator or
+Stim Desktop before selecting it. By default, closing a Siniulator device
+window shuts down that simulator. Enable "Leave simulator running after window
+is closed" in Siniulator Settings if Stim should keep it running. See \`guide lifecycle simslim\` for
 window behavior.
 
 THE DEVICE POOL BOUNDS ARE MACHINE-LEVEL TOO
@@ -4713,7 +5095,8 @@ The example shows the defaults. Full setting names and behavior:
     auto keeps library/project policy, with PCH off by default when Stim supplies
     ccache. on/off overrides Gradle CMAKE_DISABLE_PRECOMPILE_HEADERS arguments;
     CMake target-level overrides still win. on does not fix stock ccache's
-    cross-worktree PCH limitations.
+    cross-worktree PCH limitations. A value outside auto|on|off is refused by
+    name.
   optimizations.android.gradleBuildCache
     false passes --no-build-cache to Gradle, overriding org.gradle.caching=true.
   optimizations.android.targetAbiOnly
@@ -4747,9 +5130,10 @@ swaps, and the doctor fingerprint checkout select a writable directory on the
 relevant filesystem. App/APK preparation uses the artifact volume. Worktree
 warm copies directly to the destination and does not use temporary storage.
 A system temporary directory on that
-volume is preferred, then a writable ancestor of the relevant path. Staging
-is private and outside Git working trees, so ignored secrets cannot enter
-Git status or git add. If no safe location exists, the operation refuses.
+volume is preferred, then a writable ancestor of the relevant path outside
+the shared build cache. Staging is private and outside Git working trees, so
+ignored secrets cannot enter Git status or git add. If no safe location
+exists, the operation refuses.
 
 Set STIM_TMPDIR or top-level tempDir in $STIM_HOME/config.json (default
 ~/.stim/config.json) to override placement. STIM_TMPDIR takes precedence.
@@ -4775,16 +5159,22 @@ cp -c can silently fall back to copying and exit successfully.
 CACHE LOCATIONS ARE MACHINE-LEVEL TOO
 The shared build cache and Metro transform cache default to living under
 ~/.stim. To relocate them (say, to an external disk), set a top-level
-\`caches\` key in ~/.stim/config.json, edited by hand -- absolute paths:
+\`caches\` key in ~/.stim/config.json (\`stim settings set caches.buildCache
+<path>\`, or by hand) -- absolute paths:
 
   {
     "caches": { "buildCache": "/Volumes/SSD/stim/build-cache",
                 "metroCache": "/Volumes/SSD/stim/metro-cache" }
   }
 
-STIM_BUILD_CACHE / STIM_METRO_CACHE in the environment override the file.
+caches.buildCache and caches.metroCache are the keys; STIM_BUILD_CACHE /
+STIM_METRO_CACHE in the environment override the file.
 The CLI and both cache packages resolve these identically, so every process
-finds the same store regardless of shell profile. A relative path is ignored.
+finds the same store regardless of shell profile. A relative path in the file
+is ignored. A relative STIM_HOME, STIM_BUILD_CACHE or STIM_METRO_CACHE makes
+every command refuse with STIM_RELATIVE_PATH; Metro and the Expo build-cache
+provider, which must not break the bundler, ignore it with a warning and use
+the next source.
 The Metro value is a PARENT root. The sanitized package name is appended below
 it, so apps remain separately reportable and prunable. Earlier releases used an
 overridden Metro root as one flat store. A new registration replaces that legacy
@@ -4794,7 +5184,7 @@ A marked store that later becomes another override parent remains visible but is
 report-only while its marked child exists. Root-level legacy files remain
 untouched for manual cleanup.
 
-PREFER SELF-REGISTRATION OVER THE 'caches' SETTING
+REGISTER A CACHE WITH GC
 There is no 'cache' command. A cache registers itself from code instead, once,
 and every 'gc' report shows it from then on, tagged (registered):