stim 1.9.0 → 1.10.0

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

@@ -1,11 +1,14 @@
-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 { o as findProjectRoot } from "./project-BXZzOABt.mjs";
+import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-DOugPlPz.mjs";
+import { t as guideStatus } from "./guide-status-CWvti2Lg.mjs";
+import { SETTINGS_SCHEMA_URL } from "@stim-cli/core/state";
 import chalk from "chalk";
-//#region src/guide/agent.ts
-var agent_default = {
-	summary: "The normal coding-agent workflow, safety rules, and topic routing",
-	body: () => `AGENT WORKFLOW
+//#endregion
+//#region src/guide/index.ts
+const TOPICS = {
+	agent: {
+		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
@@ -119,8 +122,10 @@ RULES DURING THE LOOP
 - Put runtime .stim.json beside that app's package.json. Monorepo apps do not
   inherit a repository-root runtime file. Keep repository-wide worktree-copy
   rules at the source checkout root; see guide settings for the two scopes.
-- Run start before a debug ios or android build. If it returns STIM_NO_METRO,
-  run stim start and retry.
+- A debug ios or android run starts this workspace's dev server when it is
+  not running, including after it stopped itself for an hour with no use
+  (guide metro). Running start first is optional; it lets Metro warm up while
+  you do other work.
 - Run ios or android again after a native input changes. A JavaScript-only
   change does not need one.
 - For stale Metro transforms or file-map state, use stim start --reset-cache.
@@ -211,8 +216,9 @@ 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 and clears the build
-  outputs of every workspace not in use. Run stim gc --json first and show
+- gc --delete, because it deletes orphaned resources, removes clean linked
+  worktrees whose branch is merged, 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
@@ -224,6 +230,14 @@ Ask the user before these actions:
   delete it. An explicit stop shuts down a Stim-owned simulator even when
   another process uses it. It never shuts down an unowned simulator.
 
+LEAVE THE MACHINE CLEAN
+
+Run stim stop when you pause or finish a task, and stim worktree remove once
+it is merged or abandoned. Never create a simulator or emulator by hand;
+every device comes from Stim. Before starting a new workspace, check stim
+status for an idle workspace to reuse and confirm capacity headroom instead of
+adding another.
+
 SANDBOXES
 
 An agent harness that sandboxes shell commands usually permits writes inside
@@ -250,6 +264,7 @@ Read the matching guide before acting in these situations:
 | Remote device, custom Metro, or tunnel                | stim guide metro                 |
 | Cache miss, bypass, or fingerprint exclusions         | stim guide lifecycle builds      |
 | Capacity limits                                       | stim guide lifecycle concurrency |
+| budget lines, reclaimed field, or low disk            | stim guide lifecycle budget      |
 | 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     |
@@ -283,6 +298,7 @@ FULL TOPIC LIST
   stim guide lifecycle readiness  # add optional app readiness logs; no package required
   stim guide lifecycle builds     # build optimizations, optional cache warm-up, fingerprints
   stim guide lifecycle concurrency # shared builds, wait timeouts, capacity limits
+  stim guide lifecycle budget     # disk and memory budgets, automatic reclaim
   stim guide lifecycle options    # every flag, Android variants, --device-type, --system-image
   stim guide lifecycle devices    # ios --device and android --device on a physical phone
   stim guide lifecycle release    # Release configurations and ...Release variants
@@ -294,12 +310,10 @@ 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`
-};
-//#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
+	},
+	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.
@@ -313,8 +327,15 @@ stdout for \`--json\`. Every other line goes to stderr, so it is always safe
 to pipe. \`logs --json\` is the one exception: it is NDJSON, one record per
 line by design (see \`guide logs\`), not this single-payload contract.
 
-status's unprovisionedWorktrees lists this repository's linked worktrees with
-no Stim environment. \`worktree warm\` does not create one; \`start\`, \`ios\`,
+status's unprovisionedWorktrees lists the linked worktrees with no Stim
+environment in every repository with a registered environment, plus the
+repository status runs from. A worktree counts as having an
+environment when one is registered at it or inside it. Each entry is
+{ path, branch, repository }; repository is the main checkout, or the git
+directory of a bare repository. status reads git's own worktree records and
+never opens the worktree directories, so a worktree under a macOS-protected
+folder such as ~/Documents is listed without a privacy prompt.
+\`worktree warm\` does not create an environment; \`start\`, \`ios\`,
 \`android\` and \`doctor\` register it.
 
 status's remoteDevices lists each environment's recorded EAS Simulator
@@ -335,10 +356,10 @@ is still running.
 
 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
+		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
@@ -543,6 +564,20 @@ per session, with the preview URL.`,
                   error, and this field is separate from cacheHit
   logs            the workspace log directory
   durationMs      wall time for the whole run
+  reclaimed       present only when the run was over its disk or memory
+                  budget and reclaimed first (\`start\`, \`ios\` and
+                  \`android\`, on success and failure alike). One entry per
+                  step that acted, in order:
+                    { step, targets, failures, freedMb }
+                  step is "idle-devices", "idle-dev-servers",
+                  "workspace-outputs" or "stale-cache-entries"; targets names
+                  the devices, workspaces or caches it acted on; freedMb is the
+                  free disk the step added. See \`guide lifecycle budget\`
+  devServer       present only when this run started the workspace's dev
+                  server because none was running (\`ios\` and \`android\`):
+                    { started: true, reason }
+                  reason is "not running" or "stopped (idle)" when the
+                  supervisor had stopped it after metro.idleStopMinutes
 
   stim reload [ios|android] --json
 
@@ -581,6 +616,14 @@ per session, with the preview URL.`,
                   PATH and the version each reports. resolvedIsOlder is true
                   only when that first executable is below the highest version
                   available from this invocation or PATH
+  budget          { budget, volumes, memory, plan } or null when a budget
+                  setting is invalid. budget echoes minFreeDiskGb,
+                  hardFloorDiskGb, maxCommittedMemoryGb and maxLiveWorkspaces;
+                  volumes is { volume, freeGb } for the volumes holding the app
+                  and $STIM_HOME; memory is { committedGb, liveWorkspaces } or
+                  null when off; plan lists what the next start, ios or
+                  android would reclaim, in the \`reclaimed\` shape without
+                  freedMb, and is empty while under budget
   findings        the diagnostic findings; a lower resolved Stim is a
                   costs-time finding with a PATH or installation remedy
 
@@ -588,12 +631,14 @@ ON FAILURE
   \`start\`, \`ios\` and \`android\` all print the error contract instead,
   still one line on stdout, and exit 1:
 
-    { "code": "STIM_NO_METRO", "message": "...", "remedy": "..." }
+    { "code": "STIM_METRO_TIMEOUT", "message": "...", "remedy": "..." }
 
   If a native build returned before the failure, this payload also carries
   \`ccache\` (Android) or \`compilationCache\` (iOS), with the status and
   counters described above. This includes failed builds and later install
   or launch failures. The field is absent when no native build returned.
+  \`reclaimed\` is present the same way as on success when the run reclaimed
+  before failing, including a STIM_LOW_DISK refusal.
 
   Branch on \`code\`, never on the message text. \`guide errors\` enumerates
   every code.
@@ -615,10 +660,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
@@ -709,11 +754,11 @@ RULES
   developer trust, has no API at all and is always the user's.
   \`guide errors unverified\` has the signature and the
   full commands.`
-		},
-		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
+			},
+			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] [--idle <duration>] --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
@@ -722,16 +767,18 @@ RULES
   \`stim gc --json\` again to see what is left.
 
   mode            "dry-run" | "delete"
+  idle            the --idle duration in milliseconds, or null
   cacheScope      the --cache name, or null. When set, devices, project
                   entries and locks were not inspected and their sections
                   are empty
   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
+                  the default 7 because --older-than was not given. Merged
+                  worktrees are swept either way
   actionable      true when --delete with the same flags reclaims something
-  failures        null on a dry run; under --delete, the entries it could
-                  not delete
+  failures        null on a dry run without --idle; otherwise the entries it
+                  could not delete or shut down
   sections        one array per report section, in the text order. Every key
                   is present, empty when there is nothing to report:
     deadProjects            { path }
@@ -739,16 +786,31 @@ RULES
     orphanedPorts           { project, label, port }
     orphanedWorkspaces      { dir, projectRoot, bytes }  --delete removes the
                               whole workspace directory
-    linkedWorktrees         { path, idleDays, willRemove, reason, detail }
-                              only with --worktrees
+    linkedWorktrees         { path, idleDays, mergedInto, willRemove,
+                              reason, detail }  mergedInto is the default
+                              branch HEAD is merged into ("origin/main"),
+                              or null; detail says why it is removed
+                              ("merged into origin/main", "idle 9d") or kept.
+                              Without --worktrees, the source checkout and
+                              roots outside git are left out
     parkedSimulators        { udid, name, model, runtime, parkedAt, bytes,
-                              listed }
+                              listed }  with --older-than, only those parked
+                              at least that long
     parkedEmulators         { name, systemImage, parkedAt, bytes, listed }
+                              likewise
     orphanedDevices         { kind, id, name, bytes, directory }
+    unverifiedDevices       { kind, id, name, command }  stim-* devices Stim
+                              has no record of creating; never deleted, run
+                              command yourself
     staleDevices            { kind, id, name, project, slot, idleDays,
                               bytes }  only with --older-than
     staleDeviceRecords      { kind, id, project, slot }  --delete clears
                               the record only
+    idleDevices             { kind, id, name, project, slot, lastActivityAt,
+                              idleForMs, buildInProgress }  booted owned
+                              devices whose status activity is "idle";
+                              --idle shuts down those idle long enough,
+                              --delete never touches them
     orphanedEasSessions     { id, name, platform, status, projectScope }
     staleBuildLocks         { path, platform, key, pid, projectRoot }
     staleBuildSlots         { path, index, pid, projectRoot }
@@ -776,13 +838,15 @@ RULES
 
   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.
+  A linked worktree's detail is never null.
     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
+                            not-merged | merge-unknown | last-use-unknown |
+                            recently-used
 
   These print the error contract instead and exit 1:
 
@@ -790,13 +854,49 @@ RULES
 
   - 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
+  - --cache together with --worktrees or --idle`
+			},
+			status: {
+				summary: "the status payload's build and device activity fields: a running build, its estimate, and who drives each device",
+				body: () => `  stim status --json
+
+  Each booted simulator and detected emulator in environments (and in
+  slots) carries activity; a shut-down or physical device has none:
+
+  activity  { state, driver?, lastActivityAt?, basis }
+
+  state            "driven"   a live claim or driver holds the device now
+                   "active"   no driver, but activity in the last 10 minutes
+                   "idle"     no driver and no activity for 10 minutes or more
+                   "unknown"  a claim or driver check could not be read;
+                              never treated as idle
+  driver           { tool, pid, since } for "driven": agent-device, stim device
+                   lock, xcodebuild, idb, maestro, appium, simctl,
+                   uiautomator or instrumentation; pid and since are null when
+                   the claim does not record them
+  lastActivityAt   the newest of this device's app log records, this
+                   platform's Metro bundle requests and the workspace's last
+                   Stim run; absent when none is recorded
+  basis            the evidence behind state, strongest first:
+                   agent-device-claim, agent-device-lease  agent-device state,
+                     read only; live only when every recorded process is alive
+                     with its recorded start time, so a reused pid is dead
+                   device-lock          an unexpired \`stim device lock\` lease
+                   driver-process       a host process naming the UDID or serial
+                   instrumentation      an on-device uiautomator or androidx.test
+                                        process (one adb shell ps per emulator)
+                   device-log, metro-bundle, workspace-use   recency
+
+  Plain \`stim status\` appends it to each device line: "driven by
+  agent-device for 12m", "active", "idle 3h", or "activity unknown (...)".
+  \`gc --idle <duration>\` shuts down owned devices idle that long
+  (\`guide cleanup gc\`).
+
+  An environment's metro carries idleStop { reason: "idle", at, idleMinutes }
+  when its supervisor stopped the dev server for idleness and nothing serves
+  the port since; plain \`status\` prints "stopped (idle)" (\`guide metro\`).
+
+  Each entry of environments also carries build: null, or the ios or android
   run that holds this workspace's native-run.lock:
 
   build   { platform, slot, state, phase, startedAt, phaseStartedAt,
@@ -828,10 +928,10 @@ RULES
 
   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
+			},
+			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>,
@@ -885,14 +985,12 @@ 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.`
+			}
 		}
-	}
-};
-//#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
+	},
+	metro: {
+		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
@@ -952,11 +1050,12 @@ REMOTE DEVICE BACKENDS
   requires AGENT_DEVICE_DAEMON_BASE_URL and
   AGENT_DEVICE_DAEMON_AUTH_TOKEN. Stim creates no remote session for it.
 
-  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. \`stim status\` lists each
-  recorded session with its preview URL (see \`guide facts\`).
+  The EAS backend needs eas-cli 21.6.0 or later 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.
+  \`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
@@ -995,6 +1094,31 @@ WHAT THE SUPERVISOR IS
   the device-log collectors, shuts the owned device down (never deletes it)
   and frees the port.
 
+  IDLE STOP: the supervisor stops its dev server after metro.idleStopMinutes
+  (default 60; 0 never stops) with no bundle request, no client log record
+  (in-app console logs; for Expo, any stdout line of the Expo CLI) and no Stim
+  command in the workspace (start, ios, android, reload, worktree warm). It
+  checks once a minute. It keeps running while a bundle response is in
+  flight, while a build in the workspace is in progress, while a stim ios,
+  android or stop run holds the workspace's native-run lock, while the
+  workspace holds an unexpired device lease (\`stim device lock\` or a
+  --device run, physical devices included), while one of the workspace's
+  devices is driven or its activity is unknown (\`guide facts status\`; on
+  Windows, which has no ps, the host driver-process probe is skipped), and
+  while a \`stim start\` holds the workspace's metro-start lock. It checks
+  all of this again under the native-run and metro-start locks before it
+  stops the server. A Fast Refresh update is not a bundle request:
+  an open app that only hot-reloads and logs nothing counts as idle, and a
+  connected app alone does not keep the server. It records a
+  supervisor_idle_stopped line in metro.ndjson and devServerStop in
+  state.json, so \`status\` shows "stopped (idle)" rather than a crash.
+  Devices stay booted. The next \`stim start\` starts it again and clears the
+  record, also when it reuses a dev server that another process started. A
+  Debug \`ios\` or \`android\` run starts it the same way and reports
+  devServer.reason "stopped (idle)". The setting
+  is read when \`start\` spawns the supervisor; a value that is not a whole
+  number of 0 or more is refused, as \`stim settings set\` refuses it.
+
   ENVIRONMENT: the supervisor -- and through it the dev server, including a
   metro.config.js evaluated inside the expo child -- inherits the environment
   of the \`start\` call that SPAWNED it. A later \`start\` that finds a healthy
@@ -1038,12 +1162,10 @@ STARTING YOUR OWN BUNDLER STILL WORKS
   \`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
+	},
+	ports: {
+		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.
 
@@ -1095,12 +1217,10 @@ 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.`
-};
-//#endregion
-//#region src/guide/logs.ts
-var logs_default = {
-	summary: "Querying the merged NDJSON timeline, and what --errors means",
-	body: () => `LOGS
+	},
+	logs: {
+		summary: "Querying the merged NDJSON timeline, and what --errors means",
+		body: () => `LOGS
 
   stim logs [filters]
 
@@ -1386,41 +1506,40 @@ WHAT WRITES WHAT
 
   A collector is killed and replaced on the next \`ios\` / \`android\` run for
   that platform, and reaped by \`stop\`.`
-};
-//#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
+	},
+	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
+		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
-  EAS CLI is unavailable, a profile/fingerprint/list/download operation failed,
-  the response could not be validated, or another run holds the artifact claim.
+			},
+			STIM_EAS_UNAVAILABLE: {
+				summary: "EAS lookup/download failed, or another run holds the artifact claim",
+				body: () => `STIM_EAS_UNAVAILABLE
+  EAS CLI is unavailable or older than 18.9.0, 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
@@ -1428,44 +1547,47 @@ Branch on the 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
-  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
-  compiling an app that could not load a bundle. Run \`stim start\` first.
-  \`--no-metro-check\` overrides it and wires the app to the reservation (or to
-  8081 when there is none). A non-Debug \`ios --configuration\` never emits
-  this: a release-shaped build embeds its JS, so the gate does not run at all.
-  A port held by SOMETHING ELSE reports what: usually a bundler started from
-  the wrong directory (the repo root instead of the app dir in a monorepo), or
-  another repo's Metro. Restart it from inside the project, or free the port
-  and run \`stim start\` to get a fresh reservation.
-
+			},
+			STIM_NO_METRO: {
+				summary: "the recorded launch's port is not this workspace's live dev server (reload)",
+				body: () => `STIM_NO_METRO
   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
+  Metro. It refuses a missing, changed, unresponsive, or foreign port. Run
+  \`stim start\`, or run \`ios\` or \`android\` again.
+
+  \`ios\` and \`android\` do not emit this code. A Debug run with no healthy
+  dev server on the reserved port starts one, as \`stim start\` would, and
+  refuses only when that start fails, with the start's code
+  (STIM_METRO_TIMEOUT, STIM_SUPERVISOR_EXITED, ...). A port held by SOMETHING
+  ELSE, usually a bundler started from the wrong directory or another repo's
+  Metro, gets a fresh reservation.`
+			},
+			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
-  \`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_PREBUILD_FAILED: {
+				summary: "expo prebuild could not generate or regenerate the native directory",
+				body: () => `STIM_PREBUILD_FAILED
+  \`expo prebuild\` could not generate the missing native directory, or
+  regenerate a stale one. The extracted output is above the code; the
+  transcript is in the global workspace logs/build-<platform>.ndjson file.
+  The same code refuses a native directory that the fingerprint leaves out of
+  the cache key while git tracks its files, or when git cannot answer: Stim
+  cannot show those files came from the current app config, and will not
+  delete tracked files with \`expo prebuild --clean\`. Stop excluding the
+  directory from the fingerprint (.fingerprintignore), or gitignore and
+  untrack it so Stim regenerates it. When git itself is failing, fix the
+  checkout first.`
+			},
+			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.
@@ -1493,10 +1615,10 @@ Branch on the 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:
@@ -1527,10 +1649,10 @@ Branch on the 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
@@ -1546,10 +1668,10 @@ Branch on the 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
@@ -1615,10 +1737,10 @@ Branch on the 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.
@@ -1627,10 +1749,10 @@ Branch on the 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.
@@ -1668,10 +1790,10 @@ Branch on the code, never on the message.`,
   Legacy inline \`deletionClaim\` fields in config.json have no process
   identity and require separate manual inspection; \`stim guide lifecycle pool\`
   describes their field-only recovery.`
-		},
-		STIM_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
@@ -1691,10 +1813,10 @@ Branch on the 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.
@@ -1712,11 +1834,14 @@ Branch on the code, never on the message.`,
   installed -- the built APK's applicationId, which on a flavored project is
   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
+  that is a cache hit: one install, no build.
+  On a REMOTE device (\`--remote\`) agent-device refused the upload or install.
+  With \`--remote eas\` the EAS Simulator session stays up and billed; the
+  remedy names it. Rerun to reuse it, or run \`stim stop\` to end it.`
+			},
+			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
@@ -1733,26 +1858,28 @@ Branch on the code, never on the message.`,
   VPN & Device Management, tap the developer profile under DEVELOPER APP, tap
   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
+  signer-conflict retry performs.
+  With \`--remote eas\` the remedy names the EAS Simulator session that is
+  still running, as for STIM_INSTALL_FAILED.`
+			},
+			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
   \`openssl smime\` could not decode the one it has. The first means the build
   produced an unsigned app -- almost always a simulator-sliced artifact.
@@ -1761,14 +1888,14 @@ spending a build or a bundle, that the check can succeed.`,
   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;
@@ -1782,14 +1909,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
@@ -1797,14 +1924,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
@@ -1812,14 +1939,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.
@@ -1828,13 +1955,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
@@ -1844,12 +1971,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
@@ -1935,11 +2062,11 @@ 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
@@ -1996,10 +2123,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
@@ -2013,10 +2140,10 @@ 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_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
+			},
+			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
@@ -2028,10 +2155,10 @@ so a Debug run on one is wired to a LAN origin instead of localhost.`,
   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
+			},
+			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.
@@ -2039,10 +2166,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
@@ -2053,10 +2180,34 @@ 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_LOW_DISK: {
+				summary: "free disk stayed below budget.hardFloorDiskGb after reclaiming",
+				body: () => `STIM_LOW_DISK
+  \`start\`, \`ios\` and \`android\` check free disk on the volumes holding
+  the app and $STIM_HOME before they build or boot anything. Below
+  budget.minFreeDiskGb (20 GB by default) they first reclaim what Stim can
+  prove idle (\`guide lifecycle budget\`). This code means a volume was still
+  below budget.hardFloorDiskGb (5 GB by default) afterwards, so the run
+  stopped instead of filling the disk. Nothing was built or booted.
+
+  The message names the free space and the largest uses it could measure:
+  Stim state, the shared build cache, simulators, Xcode DerivedData and
+  Android emulators. The \`--json\` payload lists what was already reclaimed
+  under \`reclaimed\`. To free more:
+
+    stim gc                            # what else Stim can reclaim
+    stim gc --delete                   # clear idle workspace outputs, dead entries
+    stim gc --delete --cache all       # empty the shared caches
+    stim gc --delete --worktrees       # remove clean, idle worktrees
+
+  Ask before deleting anything outside Stim, such as Xcode DerivedData or
+  simulators Stim did not create. Lowering budget.hardFloorDiskGb (0 never
+  refuses) only removes the protection.`
+			},
+			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
@@ -2070,50 +2221,54 @@ 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
-  \`--remote eas\` requires eas-cli. Proxy environment variables do not change
+			},
+			STIM_REMOTE_EAS_UNAVAILABLE: {
+				summary: "--remote eas needs eas-cli 21.6.0 or later",
+				body: () => `STIM_REMOTE_EAS_UNAVAILABLE
+  \`--remote eas\` requires eas-cli 21.6.0 or later, the first release with
+  the \`eas simulator:*\` commands Stim runs. Stim reads \`eas --version\` and
+  refuses before any build or session work when eas-cli is missing, older, or
+  reports no version. Upgrade it (\`npm install --global eas-cli@latest\`, or
+  the project's eas-cli dependency). 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.
@@ -2122,10 +2277,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.
@@ -2134,39 +2289,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.
 
@@ -2192,27 +2347,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
@@ -2224,25 +2379,27 @@ 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
+  A Debug \`ios\` or \`android\` run that starts the dev server reports the
+  same refusal after the default 60s; re-running it waits for the same
+  supervisor again, and \`stim start --wait 180\` waits longer. \`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
@@ -2257,11 +2414,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
@@ -2301,11 +2458,11 @@ captured"  (in metro.ndjson, bare RN)
   (\`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:
@@ -2314,10 +2471,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
@@ -2349,11 +2506,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.
@@ -2385,10 +2542,10 @@ the supervisor could not be verified"  (stop)
   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
@@ -2408,10 +2565,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
@@ -2421,28 +2578,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
@@ -2460,20 +2617,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.
@@ -2492,9 +2649,21 @@ not on any remote"  (worktree remove)
   Warm copied Pods but the destination has no Podfile.lock. Follow the printed
   pod-install command before building.
 
+"carry       carried [<dir>/]node_modules was installed from a different <lockfile> than ..."
+  The carried node_modules records the lockfile it was installed from (npm
+  node_modules/.package-lock.json, pnpm node_modules/.pnpm/lock.yaml, Yarn
+  node_modules/.yarn-integrity or node_modules/.yarn-state.yml), and it
+  differs from this worktree's lockfile. This fires even when both checkouts
+  share the lockfile, because the source checkout itself was not reinstalled
+  after it changed. Run the printed install command before building;
+  otherwise pod install and native builds resolve the old package versions.
+  A pnpm source checkout installed with --filter or --prod also reads as a
+  mismatch, because pnpm records only what it installed.
+
 "carry       carried dependencies may be stale: they do not match ..."
-  The source checkout's lockfile differs from this branch's lockfile. Run the
-  printed package-manager command before building. A carry whose lockfile
+  node_modules records no install state Stim can read (Bun, or no record),
+  and the source checkout's lockfile differs from this branch's lockfile. Run
+  the printed package-manager command before building. A carry whose lockfile
   matches is silent; the warning means a real difference.
 
   If the source checkout has no dependencies to copy, use this project's
@@ -2502,11 +2671,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:
 
@@ -2527,10 +2696,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
@@ -2577,10 +2746,10 @@ 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 a valid JSON object 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")
@@ -2591,23 +2760,21 @@ not on any remote"  (worktree remove)
   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")
+			},
+			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.`
+			}
 		}
-	}
-};
-//#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
+	},
+	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.
 
@@ -2638,8 +2805,9 @@ a seed belongs to this workflow.
     deps        source /w/main: pnpm-lock.yaml changed -> pnpm install (41s)
     pods        source /w/main/apps/mobile: ios/Podfile.lock unchanged -> skipped
 
-  # 2. The dev server, under a detached supervisor. Blocks until it is
-  #    verifiably THIS project's, then hands your shell back.
+  # 2. Optional: the dev server, under a detached supervisor. Blocks until it
+  #    is verifiably THIS project's, then hands your shell back. Step 3 runs
+  #    this same start when the dev server is not running.
   stim start
     port       8082 (reserved)
     supervisor pid 41233
@@ -2683,10 +2851,17 @@ a seed belongs to this workflow.
   #    unwarmed worktrees with no Stim registry entry. Git-created branches stay.
   stim worktree remove
 
-Steps 2 and 3 are ordered, not interchangeable: \`ios\` and \`android\` never
-start the bundler, and refuse with STIM_NO_METRO when nothing holds the
-reserved port. That refusal costs a second; the alternative costs four minutes
-and produces an app that cannot load a bundle.
+A Debug \`ios\` or \`android\` run checks the reserved port before the device
+or the build. When no healthy dev server of this workspace answers there, it
+runs the same start as step 2: a dev server started outside Stim is reused, a
+reservation held by a foreign process moves to a free port, and the budgets
+apply. The run then reports \`devServer: { started: true, reason }\` in its
+JSON, with reason "not running" or "stopped (idle)". When that start fails,
+the run refuses with the start's own code (STIM_METRO_TIMEOUT,
+STIM_SUPERVISOR_EXITED, ...) before any build work. Release builds and
+\`--no-metro-check\` neither check nor start the dev server. \`--remote\`
+starts it the way \`stim start --remote\` does. Step 2 remains useful to warm
+Metro while other work happens.
 
 Repeat step 3 whenever a NATIVE input changes. A JS-only edit needs nothing --
 that is what Fast Refresh over the running dev server is for. \`stim reload\` is
@@ -2771,7 +2946,7 @@ ANDROID EMULATOR RESTARTS
   wait windows, diagnostics, and recovery steps.
 
 DESTRUCTIVE COMMANDS -- ask the user first
-  gc --delete             deletes orphaned stim-* devices, tens of GB
+  gc --delete             deletes orphaned devices Stim created, tens of GB
   gc --delete --cache all empties the shared build caches every project uses
   gc --delete --cache <name>
                           empties only the caches that carry <name>
@@ -2808,10 +2983,10 @@ WAITING FOR A CHANGE
   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
+		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
@@ -2883,11 +3058,14 @@ cloud build. Once it completes, retry the same Stim command. No build-on-miss
 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.
+An eas-cli older than 18.9.0 cannot run build:download --build-id; Stim reads
+eas --version first and refuses with STIM_EAS_UNAVAILABLE and the upgrade
+command before any EAS lookup. stim doctor reports it in a project with eas.json.
 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.
@@ -2947,10 +3125,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
@@ -2980,10 +3158,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
@@ -2994,8 +3172,8 @@ result as proof instead of requiring an unrelated screenshot.`
   The labels are a closed set, and nothing else is ever printed in that
   column:
 
-    branch      build       cache       caches      carry       checkout
-    deps        device
+    branch      budget      build       cache       caches      carry
+    checkout    deps        device
     devices     error       failed      findings    fingerprint gems
     install     installs    ip.txt      lan         launch      lease
     lock        log
@@ -3077,6 +3255,23 @@ result as proof instead of requiring an unrelated screenshot.`
     device      shut down stim-e2e-2
     port        released 8084
 
+  \`stop\` verifies the outcome instead of trusting that the shutdown command
+  ran: for a simulator it waits for the Shutdown state the same way park does
+  (\`guide lifecycle pool\`), and for an emulator it waits for the AVD's
+  process lock to clear. A device that never gets there is reported as
+  FAILED, not shut down, and the run's exit code reflects it; \`--json\`
+  carries the same outcome in \`device.<platform>.status\` ("failed") plus a
+  \`remedy\` field naming the manual command and \`stim gc --delete\` as the
+  fallback:
+
+    device      failed to shut down stim-e2e-2: simulator 9C1F.. is still
+                Booted after 2 shutdown attempts and 30s of waiting
+                check it with \`xcrun simctl list devices\`, then \`xcrun
+                simctl shutdown 9C1F..\` yourself -- if it will not respond,
+                \`stim gc --delete\` reclaims it
+
+  \`stop\` still never deletes the device itself, even on this failure path.
+
   \`worktree remove\` reports itself the same way: the branch decision, the
   owned device, any released device lease, and this workspace's own state
   directory, each on its own line. Nothing prints on stdout; even the removed
@@ -3103,29 +3298,32 @@ 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
-  created one costs about 30s, and \`simctl erase\` puts most of that back, so
-  a parked simulator keeps its app installed and is cleaned in pieces:
+  ADOPTS it. Adoption reuses the simulator but not its contents:
 
-    at park       shut down, the app's data cleared on disk (Documents,
-                  Library, tmp, SystemData: NSUserDefaults, AsyncStorage,
-                  SQLite), renamed \`stim-parked (<model> <runtime>) <4 hex>\`
+    at park       shut down, \`simctl erase\` (apps, app data, keychain,
+                  privacy grants, pasteboard, photos, settings), renamed
+                  \`stim-parked (<model> <runtime>) <4 hex>\`
     at adoption   renamed for the adopting workspace, then, inside the boot
                   the run pays anyway, \`simctl privacy reset all\` and
-                  \`simctl keychain reset\`; at install, every OTHER app the
-                  previous workspace left is uninstalled
+                  \`simctl keychain reset\`; at install, any other app is
+                  uninstalled
 
-  A parked simulator KEEPS its system state: pasteboard, Safari data, photos,
-  contacts, calendars, installed profiles, Simulator settings, app-group
-  containers, and device-level defaults. Isolation covers the app's data, the
-  privacy grants, the keychain and the installed apps -- not a clean system
-  image. Set the bound to 0 when a project needs one.
+  An erased simulator takes about 18 MB on disk instead of the gigabytes a used
+  one holds. Its first boot after the erase takes about 15s instead of a warm
+  boot's few seconds, and the app is always installed again. A SimSlim
+  profile survives the erase.
+
+  Park erases only a simulator that reports Shutdown. It waits up to 15s for
+  the shutdown to settle, retries the shutdown once, and waits up to 15s more.
+  A simulator that is still booted after that is deleted instead, and
+  \`worktree remove\` prints
+  \`could not park <name>: ... -- deleted it instead\`.
 
   Adoption matches the device type AND the runtime EXACTLY: a ticket that asks
   for an iPad never gets an iPhone, and a request for iOS 18.5 never gets 26.5.
@@ -3133,8 +3331,7 @@ result as proof instead of requiring an unrelated screenshot.`
   parked simulators on the old runtime are never adopted; they leave by
   eviction or \`gc --delete\`.
 
-  The pool targets at most \`pool.iosParkedMax\` simulators (default 3, about
-  2.5 GB each). Past that the oldest parked one is deleted:
+  The pool targets at most \`pool.iosParkedMax\` simulators (default 3). Past that the oldest parked one is deleted:
 
     device      parked stim-parked (iPhone 17 26.5) 9c1f (9C1F..)
     device      deleted stim-parked (iPhone 17 26.5) 4b02 (pool over 3)
@@ -3161,9 +3358,10 @@ result as proof instead of requiring an unrelated screenshot.`
 
   and an adopting run says so where a plain boot would say \`booted\`:
 
-    device      stim-app-412 (iPhone 17 26.5) (9C1F..) adopted (11s)
+    device      stim-app-412 (iPhone 17 26.5) (9C1F..) adopted (17s)
 
-  That time includes the two resets, so it runs longer than a plain boot.
+  That time includes the first boot after the erase and the two resets, so it
+  runs longer than a plain boot.
   \`stim status\` prints one line while the pool is not empty:
 
     pool: 2 parked iOS simulators (max 3)
@@ -3171,10 +3369,13 @@ result as proof instead of requiring an unrelated screenshot.`
   \`stim gc\` reports the pool, and \`stim gc --delete\` empties every entry
   it can re-verify:
 
-    Parked simulators (2, 5.1 GB):
-      ios stim-parked (iPhone 17 26.5) 9c1f (9C1F..) iPhone 17 26.5 parked 3d ago 2.6 GB
+    Parked simulators (2, 36 MB):
+      ios stim-parked (iPhone 17 26.5) 9c1f (9C1F..) iPhone 17 26.5 parked 3d ago 18 MB
                   --delete attempts every parked simulator and keeps failures.
 
+  \`gc --older-than <days>\` reports and deletes only the devices parked at
+  least that long; one parked at an unknown time stays.
+
   If simulator listing or deletion fails, \`gc --delete\` reports the failure
   and keeps that entry. It never turns an unverified absence into a dropped
   ownership record.
@@ -3190,12 +3391,15 @@ result as proof instead of requiring an unrelated screenshot.`
   \`pool.androidParkedMax\` (default 3) or STIM_POOL_ANDROID_PARKED_MAX.
   A redirected STIM_HOME disables parking unless that environment override
   is set. Zero disables parking and adoption. \`stop\` keeps the assignment;
-  \`worktree remove\` parks eligible AVDs, and \`gc --delete\` empties the pool.
+  \`worktree remove\` parks eligible AVDs, and \`gc --delete\` empties the pool
+  (with --older-than, only the AVDs parked that long).
 
   Adoption matches the system image, data partition size, and the creation
   settings from android.avdConfig / android.avdConfigFile. The AVD keeps its
-  original stim-<label> name so its Quick Boot snapshot can survive reuse.
-  Normal desktop boots allow Quick Boot; headless Linux disables snapshots.
+  original stim-<label> name. Parking wipes its user data, cache and
+  encryption-key images and its snapshots, the files the emulator recreates
+  on the next boot, so a parked AVD takes a few MB and adoption pays a cold
+  boot (about 20s) and a fresh install.
   Incompatible AVDs stay parked until eviction or GC. AVDs created by older
   versions without a recorded creation configuration are deleted at removal.
 
@@ -3211,9 +3415,10 @@ result as proof instead of requiring an unrelated screenshot.`
   manually clearing a claim, and keep the AVD data while its process state
   cannot be verified.
 
-  Android cleanup happens AFTER boot, before install or launch: \`adb shell
-  pm clear\` clears the adopting app's data while retaining its APK, and
-  other third-party apps are uninstalled. If ADB goes offline or closes the
+  Android cleanup happens AFTER boot, before install or launch, for AVDs
+  parked with their data by older versions: \`adb shell pm clear\` clears
+  the adopting app's data while retaining its APK, and other third-party apps
+  are uninstalled. If ADB goes offline or closes the
   connection, Stim waits for boot readiness and retries cleanup for up to 30
   seconds, verifying the same owned AVD before each destructive command.
   Failed cleanup blocks launch and remains pending for a retry. The installed APK's SHA-256 must match the
@@ -3222,15 +3427,15 @@ result as proof instead of requiring an unrelated screenshot.`
   If the retained APK has a conflicting signer or version, adoption uninstalls
   it and retries installation. Adoption stays pending until installation succeeds.
 
-  Parked AVDs retain app data until adoption. System apps, shared storage,
-  accounts and device settings also remain: this is not a factory reset.
-  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.
+  The wipe resets apps, accounts, device settings and the shared storage
+  inside the data partition; the AVD's creation settings and any separate
+  SD card image remain. Status lists parked Android emulators; GC
+  reports their system image, 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
@@ -3475,6 +3680,25 @@ THE BUILD CACHE HAS THREE LEVELS
   of compiling beside it. No second line means nothing was found there and the
   run compiles.
 
+  A GITIGNORED (CNG) ios/ OR android/ IS NOT IN THE KEY: @expo/fingerprint
+  hashes the app config instead, so the directory must come from that config.
+  Stim records the fingerprint each of its prebuilds produced in the
+  workspace state. On a miss, an existing CNG directory with no matching
+  record -- the app config, a config plugin or a dependency changed since, or
+  someone else generated it -- is regenerated with \`expo prebuild --clean\`
+  before pods and the compile, so a stale directory is never built and stored
+  under the new key:
+
+    prebuild    ios/ not generated from this fingerprint -> regenerated with --clean (9s)
+
+  Regeneration discards hand edits under a gitignored ios/ or android/ (for
+  example a signing team set in Xcode); put them in the app config, such as
+  ios.appleTeamId, or a config plugin. A committed native directory is hashed
+  into the key and never regenerated. The record only covers prebuilds Stim
+  ran: after a manual \`expo prebuild\` with a different config, run
+  \`expo prebuild --clean\` yourself or delete the directory so the next build
+  regenerates it.
+
   If the iOS fingerprint after prebuild or pod install is unavailable, Stim
   installs the build but skips local storage and remote uploads. fingerprint
   and cacheKey are null in the result and lastBuild; the old key is not reused.
@@ -3528,10 +3752,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
@@ -3610,10 +3834,67 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   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
+			},
+			budget: {
+				summary: "disk and memory budgets: what start, ios and android reclaim first, and STIM_LOW_DISK",
+				body: () => `DISK AND MEMORY BUDGETS (ON BY DEFAULT)
+  Before \`start\`, \`ios\` and \`android\` build or boot anything, they
+  compare the machine against four MACHINE-level settings:
+
+    budget.minFreeDiskGb         free disk on the volumes holding the app and
+                                 $STIM_HOME. Default 20. Below it, Stim reclaims.
+    budget.hardFloorDiskGb       default 5. Still below it after reclaiming,
+                                 the run refuses with STIM_LOW_DISK.
+    budget.maxCommittedMemoryGb  the rough memory of live environments, the
+                                 figure \`stim status\` prints (a booted
+                                 simulator 1.5 GB, an emulator 2.5 GB, a dev
+                                 server 0.7 GB). Default 60% of physical memory.
+    budget.maxLiveWorkspaces     workspaces with a booted device or running dev
+                                 server. Unset by default.
+
+  0 turns a check off; with budget.minFreeDiskGb at 0, Stim still reclaims
+  below the hard floor before refusing. A \`start\` whose dev server already
+  answers checks nothing; \`start --reset-cache\` checks before it stops the
+  server.
+
+  Over budget, Stim reclaims in this order and stops as soon as it is back
+  under budget. Each step prints a \`budget\` line on stderr, and the \`--json\`
+  payload lists the steps that acted under \`reclaimed\`:
+
+    1. shut down idle owned devices in other workspaces: booted, no driver,
+       no Stim or agent-device lock, no activity for 10 minutes, and no build
+       in progress (\`gc --idle\` semantics; shut down, never deleted)
+    2. stop idle dev servers in other workspaces: a Stim supervisor with no
+       bundle request, device log, Stim command or supervisor start for 10
+       minutes, no build in progress, and no device in that workspace that is
+       driven, active, or of unknown activity. Stim rechecks under that
+       workspace's native-run and metro-start locks before it stops the
+       server, and skips the step when simulators cannot be listed. The next
+       \`start\`, \`ios\` or \`android\` there brings it back
+    3. clear the build outputs of workspaces not in use and idle for 10
+       minutes, least recently used first, re-measuring after each
+       (\`gc --delete\` semantics; the next build installs from the shared
+       cache). A workspace whose last use is unknown is kept
+    4. trim shared cache entries nothing has used for 14 days
+       (\`gc --delete --older-than 14\` for the caches)
+
+  Steps 3 and 4 run only for disk. Memory and workspace limits never refuse;
+  a run still over them prints one \`budget\` warning and continues. The
+  current workspace is never reclaimed.
+
+  With STIM_HOME set, the budget is off unless its environment variable is
+  set (STIM_BUDGET_MIN_FREE_DISK_GB, STIM_BUDGET_HARD_FLOOR_DISK_GB,
+  STIM_BUDGET_MAX_COMMITTED_MEMORY_GB, STIM_BUDGET_MAX_LIVE_WORKSPACES), and
+  step 1 never runs because devices are machine-global.
+
+  \`stim doctor\` prints a \`budget\` line with the free disk and committed
+  memory against the budget, and a finding with the reclaim plan when over it.
+  Change a limit with \`stim settings set budget.minFreeDiskGb 30\`.
+  See \`guide errors STIM_LOW_DISK\`.`
+			},
+			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|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>
@@ -3841,10 +4122,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.
@@ -3968,10 +4249,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
@@ -4067,10 +4348,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
@@ -4143,10 +4424,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.
@@ -4216,14 +4497,12 @@ 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.`
+			}
 		}
-	}
-};
-//#endregion
-//#region src/guide/cleanup.ts
-const cleanup = {
-	summary: "Where simulators come from, and how they get reclaimed",
-	preamble: () => `DEVICE SLOTS
+	},
+	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.
@@ -4238,18 +4517,26 @@ WHAT RECLAIMS AN OWNED DEVICE
   stim worktree remove    parks eligible owned simulators and emulators
                             (\`guide lifecycle pool\`); deletes them when
                             parking is disabled or their setup cannot be verified
-  stim gc --delete        sweeps stim-* devices no project references, and
-                            clears verified parked simulators and emulators
+  stim gc --delete        sweeps devices Stim created that no project
+                            references (\`guide cleanup gc\`), clears
+                            verified parked simulators and emulators, and
+                            runs \`stim worktree remove\` on every clean,
+                            Stim-managed linked worktree whose branch is merged
   stim gc --delete --older-than <days>
                             also reaps the device of a workspace no Stim
                             command has used in that long, even though the
-                            project is still on disk
+                            project is still on disk, and clears only the
+                            devices parked at least that long
   stim gc --delete --worktrees
-                            runs \`stim worktree remove\` on every clean, idle,
-                            Stim-managed linked worktree (\`guide cleanup gc\`)
+                            also runs \`stim worktree remove\` on every clean,
+                            idle, Stim-managed linked worktree
+                            (\`guide cleanup gc\`)
+  stim gc --idle <duration>
+                            shuts DOWN (never deletes) owned devices with no
+                            driver, claim or activity for that long
 
 \`worktree remove\` and \`gc --delete\` are the only two commands that delete;
-\`gc --delete --worktrees\` deletes only through \`worktree remove\`. \`gc
+\`gc --delete\` deletes worktrees 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
@@ -4271,10 +4558,10 @@ 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. Before it reclaims anything, the command refuses a worktree git
@@ -4302,23 +4589,67 @@ IN USE
   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
+  Every \`gc\` without --cache looks at every registered project root and
+  every workspace.json root, grouped by git worktree, and reports each linked
+  worktree with the reason it is removed or kept. A worktree is finished when
+  its branch is merged into the default branch. \`--worktrees\` also removes
+  one that is idle: no recorded use for --older-than days, 7 without it; a
+  worktree whose last use is unknown is kept. Both need the same clean state;
+  a worktree is kept when it is the source checkout, bare, locked, in use,
+  dirty (untracked files count; pod install churn alone does not), unpushed
+  (commits no remote-tracking ref or other local branch reaches), or has
+  initialized submodules. Without --worktrees, the report leaves out the
+  source checkout and roots outside git.
+
+  MERGED means, with the default branch taken from origin/HEAD, after a
+  \`git fetch origin <default>\` per repository (30s timeout, no credential
+  prompt; skipped when that checkout fetched in the last 10 minutes):
+  - HEAD is reachable from origin/<default> through a merge commit, and the
+    branch's reflog shows a commit made on it that HEAD contains. A branch
+    with no commit of its own -- fresh, cut from another branch, or reset
+    onto one -- is not merged.
+  - the branch changes the tree, and either it has no merge commits and every
+    commit since the merge base has the same \`git patch-id --verbatim\` as a
+    commit on the default branch (a rebase merge), or its whole diff since the
+    merge base has the same verbatim patch id as a commit there, compared on
+    the files the branch changes (a squash merge).
+  Merge state comes from git alone, not from a hosting service. A squash
+  merge whose content changed during the merge (a conflict resolution, a
+  suggested edit, even whitespace) does not match and is kept, and so is a
+  fast-forwarded branch. When origin/HEAD is not set, the fetch fails, or git
+  cannot answer, the state is unknown and never counts as merged (reason
+  merge-unknown, with the remedy); with --worktrees an idle worktree is still
+  removed. A squash- or rebase-merged branch whose upstream is gone (deleted
+  after the merge and pruned locally) has commits only it reaches; they do
+  not block removal, because their change is on the default branch, and the
+  branch is kept.
+    stim gc                                        # report merged worktrees
+    stim gc --delete                               # remove them
+    stim gc --delete --worktrees --older-than 3    # also the clean idle ones
+  --cache with --worktrees is refused with STIM_BAD_ARG; run them separately.
   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.
+  re-checks use under the removal locks, and idleness for an idle worktree
+  or an unchanged HEAD for a merged one, then parks devices and handles the
+  branch exactly as a manual \`stim worktree remove\`, which keeps the
+  checkout when its HEAD moves while devices are reclaimed. A worktree that
+  changed since the report is kept with the reason. A worktree that fails is
+  reported, gc exits 1, and the sweep continues.
+
+IDLE DEVICES
+  Plain \`gc\` lists booted owned simulators and emulators whose \`status\`
+  activity is idle (\`guide facts status\`), with how long. \`gc --idle
+  <duration>\` (30m, 2h, 1d) shuts down each one idle at least that long
+  through the same teardown as \`stim stop\`: ownership is re-checked, the
+  device and its record stay, and the next \`ios\` or \`android\` run boots
+  it again. It acts without --delete and never deletes. It skips a device
+  that is driven (agent-device, a device lock, a test runner), whose
+  activity is unknown, whose idle time is unknown, or whose workspace has a
+  build in progress, and re-checks each device just before shutting it down.
+  Physical and remote devices are out of scope. --cache with --idle is
+  refused with STIM_BAD_ARG.
+    stim gc                 # lists idle devices
+    stim gc --idle 2h       # shuts down those idle 2 hours or more
 
 ORPHANED WORKSPACE DIRECTORIES
   A worktree deleted with \`git worktree remove\`, \`rm -rf\` or a /tmp wipe
@@ -4358,6 +4689,19 @@ If a delete fails, the device's config record is KEPT and the command reports
 it. A record is what makes the device findable again, so it outlives a failed
 teardown rather than turning it into an orphan.
 
+WHICH stim-* DEVICES gc DELETES
+  A \`stim-\` prefix alone is not proof that Stim made a device. gc deletes an
+  unreferenced device only when Stim created it: the device is listed in
+  $STIM_HOME/created-devices.json, where Stim records every simulator and AVD
+  it creates, or it predates that ledger and matches Stim's own format
+  exactly -- an iOS name \`stim-<label> (<model> <runtime>)\`, or an AVD
+  named \`stim-<label>\` whose config.ini holds the byte-valued
+  disk.dataPartition.size Stim writes. gc lists any other stim-* device under
+  "Unrecognized stim-* devices" with the command that deletes it
+  (\`xcrun simctl delete <udid>\` or \`avdmanager delete avd -n <name>\`), and
+  never runs it. Boot, shutdown and teardown re-check ownership by the same
+  rule, so a device that stops matching is left alone.
+
 ANDROID DATA WITHOUT A REGISTRATION
   \`gc\` also reports stim-*.avd directories whose .ini registration is
   gone. \`gc --delete\` rechecks the directory, emulator process locks, and
@@ -4430,10 +4774,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,
@@ -4487,10 +4831,10 @@ 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, workspace build outputs, 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. \`gc --delete\` clears the
   build outputs of workspaces nobody is using (WORKSPACE BUILD OUTPUTS
@@ -4498,16 +4842,17 @@ THE ONE CASE GC WILL NOT REAP
   project build directories while sharing task outputs through its build cache.
 
   Android AVDs normally live under ~/.android/avd, and a booted owned AVD can
-  use several GB. \`worktree remove\` deletes the workspace's owned AVD; plain
-  \`stop\` only shuts it down for reuse. Stim uses Android's default Quick Boot
+  use several GB. \`worktree remove\` parks the workspace's owned AVD with its
+  user data and snapshots wiped, or deletes it when the pool is off or full;
+  plain \`stop\` only shuts it down for reuse. Stim uses Android's default Quick Boot
   unless displayless Linux requires software rendering, where snapshots are
   disabled. The first boot and a boot after the emulator, system image, or AVD
   settings change are cold, while later supported boots load the one automatic
   snapshot saved on exit. \`stop\` waits for the emulator process and, when
   enabled, the snapshot save to finish.
   New owned AVDs default to an 8 GiB data partition, though project settings can
-  change it. When enabled, Quick Boot keeps one automatic snapshot, and \`worktree remove\`
-  deletes the whole AVD.
+  change it. When enabled, Quick Boot keeps one automatic snapshot until the AVD is
+  parked or deleted.
   \`gc\` prints the on-disk size beside an orphaned or stale owned Android AVD
   when its content directory can be read.
 
@@ -4579,21 +4924,9 @@ SHARED BUILD CACHES
 
   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
@@ -4829,6 +5162,14 @@ ${ANDROID_AVD_CONFIG_HELP.map((line) => `                          ${line}`).joi
                         validates the shape and platform but cannot discover
                         runtime entry-point or dev-menu overrides or auto-fix
                         them. See \`guide metro\` for warmup behavior.
+  metro.idleStopMinutes minutes without a bundle request, client log record or
+                        Stim command before the supervisor stops the dev
+                        server (default 60). 0 never stops it. Never during a
+                        build or bundle response, while the workspace holds
+                        a device lock, or while a workspace device is
+                        driven. Read
+                        when \`start\` spawns the supervisor; see
+                        \`guide metro\`.
   worktree.exclude      ignored-path skip list for worktree warm. Settings
                         come from the source checkout's repository-root
                         .stim.json. A nonempty .worktreeexclude in the source
@@ -4914,6 +5255,19 @@ Unset, 0, or any non-positive value means NO enforcement -- the default, where
 Stim limits nothing. See \`guide lifecycle concurrency\` for what each cap
 does.
 
+DISK AND MEMORY BUDGETS ARE MACHINE-LEVEL AND ON BY DEFAULT
+Top-level \`budget\` in ~/.stim/config.json, or the environment, which
+overrides the file:
+
+  budget.minFreeDiskGb          STIM_BUDGET_MIN_FREE_DISK_GB         default 20
+  budget.hardFloorDiskGb        STIM_BUDGET_HARD_FLOOR_DISK_GB       default 5
+  budget.maxCommittedMemoryGb   STIM_BUDGET_MAX_COMMITTED_MEMORY_GB  60% of RAM
+  budget.maxLiveWorkspaces      STIM_BUDGET_MAX_LIVE_WORKSPACES      unset
+
+0 turns a check off. With STIM_HOME set and no environment variable, the
+budget is off. A value of the wrong shape refuses start, ios and android with
+STIM_BAD_ARG. See \`guide lifecycle budget\` for what each limit reclaims.
+
 THE IOS SIMULATOR APP IS MACHINE-LEVEL
 Top-level \`iosSimulatorApp\` in ~/.stim/config.json selects the macOS app that
 displays Stim's owned local iOS simulator after boot. It is not a project
@@ -4945,7 +5299,7 @@ window behavior.
 THE DEVICE POOL BOUNDS ARE MACHINE-LEVEL TOO
 \`pool.iosParkedMax\` caps how many parked simulators \`worktree remove\` may
 leave behind for a later workspace to adopt. It is machine-level for the same
-reason: the disk they sit on is the whole machine's, about 2.5 GB each.
+reason: the disk they sit on is the whole machine's, about 18 MB each once erased.
 
   {
     "pool": { "iosParkedMax": 3 }