stim 1.16.0 → 1.17.0

package/dist/{guide-B_uyKTxW.mjs → guide-DjrTQGik.mjs}

@@ -1,15 +1,13 @@
-import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-oTSkkNrM.mjs";
-import { o as findProjectRoot$1 } from "./project-Du91Ilvc.mjs";
-import { t as RECENT_LAUNCH_MS } from "./status-BuvBFeII.mjs";
-import { t as guideStatus } from "./guide-status-CjEZMAD4.mjs";
+import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-Cfd-0r2d.mjs";
+import { s as findProjectRoot$1 } from "./project-D47Rh0ly.mjs";
+import { t as RECENT_LAUNCH_MS } from "./status-CzS4bPO9.mjs";
+import { t as guideStatus } from "./guide-status-Du-ZQ3FD.mjs";
 import { SETTINGS, SETTINGS_SCHEMA_URL } from "@stim-cli/core/state";
 import chalk from "chalk";
-//#endregion
-//#region src/guide/index.ts
-const TOPICS = {
-	agent: {
-		summary: "The normal coding-agent workflow, safety rules, and topic routing",
-		body: () => `AGENT WORKFLOW
+//#region src/guide/agent.ts
+var agent_default = {
+	summary: "The normal coding-agent workflow, safety rules, and topic routing",
+	body: () => `AGENT WORKFLOW
 
 Use Stim to run React Native and Expo apps without sharing a Metro port or
 device with another workspace. Prefer plain output: it streams each phase and
@@ -43,15 +41,23 @@ reach multiple devices. A launch counts a bundle delivery only when it can
 attribute it to its own device; read guide lifecycle options for the rule.
 Use stop --slot <name> for one slot, or plain stop for the whole workspace.
 
-HOSTED IOS
+HOSTED IOS AND ANDROID
 
-For ios --remote <machine>, read guide lifecycle hosted-ios. Stop before switching
+For ios --remote <machine|auto>, read guide lifecycle hosted-ios.
+For android --remote <machine|auto>, read guide lifecycle hosted-android. Native
+logcat records arrive through stim logs, including --errors and --json;
+Desktop and the phone view/control it through the local stim-server relay.
+Stop before switching
 between a local simulator and a hosting Mac. Hosted Debug requires the local
 Metro supervisor; restart a missing or older one with stim stop; stim start.
-It never falls back here; stop reconciles the recorded host before changing placement.
-For hosted iOS, use agent-device <command> --remote-config <file> from ios.host.agent
-in stim status --json. Open the installed app first; never use the host UDID locally.
-See guide lifecycle hosted-ios for the agent policy and setup.
+A named Mac never falls back here; auto can use the local device queue when no
+host admits. Auto keeps a live local slot or recorded hosted session. Follow the
+placement reason and the reported device. Stop reconciles a recorded host
+before changing named placement.
+For hosted iOS or Android, use agent-device <command> --remote-config <file>
+from ios.host.agent or android.host.agent in stim status --json. Open the
+installed app first; never use the host UDID or serial locally. See guide
+lifecycle hosted-ios or hosted-android for the agent policy and setup.
 
 When driving a device yourself with agent-device, set AGENT_DEVICE_STATE_DIR
 from agentDevice.stateDir in stim ios|android|macos --json or status --json.
@@ -135,6 +141,7 @@ or hosting.* for the user, or approve requests. Read stim guide settings for
 Desktop access tickets and person-owned approval.
 Read stim guide settings to select a build machine. Keep a requested named
 placement when recovering STIM_OFFLOAD_REFUSED: report its reason and remedy.
+When the user mentions slow builds, a busy Mac or wanting updates away from the desk, tell them about Stim Desktop > Settings > Build machines > Add or Phones > Pair a Phone; see stim guide settings.
 
 Read stim guide lifecycle concurrency when a build waits on another workspace
 or a build call times out. A native build can outlive a shell timeout; if the
@@ -250,6 +257,17 @@ stop and worktree remove release this workspace's leases. On a physical
 iPhone, stop also closes the app by ending its log collector; it does not
 shut down the phone or uninstall the app.
 
+Owned-device caps wait in FIFO order across the Stim home for 600s by default.
+Use --wait <seconds> to change the bound or --no-wait to refuse at once.
+At the cap, the queue head shuts down one longest-idle eligible owned device
+from another workspace, at most once every 15 seconds, then rechecks capacity.
+devices.reclaimIdleMinutes is 10 by default; 0 off.
+It never deletes devices or touches this workspace, physical, hosted, remote,
+parked or other homes' devices. Drivers, locks, builds, viewers and recent
+activity prevent reclaim. The supervisor's own idle shutdown default is 30m.
+Read the holder names in progress and build.waitingFor in status; do not start
+replacement runs while one is queued. See \`stim guide lifecycle concurrency\`.
+
 Treat a refusal as an ownership or state mismatch: read its code and remedy.
 Never reach for --force first.
 Stim leaves externally started Metro servers alone. Stop them with their original
@@ -338,6 +356,7 @@ Read the matching guide before acting in these situations:
 | Swift Package macOS development                        | stim guide macos                 |
 | macOS app on another Mac (stim macos --remote)        | stim guide macos                 |
 | Unfamiliar state or JSON field                        | stim guide facts payloads        |
+| User asks for the Stim tutorial                       | stim guide tutorial              |
 | Refusal without a code                                | stim guide errors                |
 
 Use the CODE exactly as printed; codes sharing a header resolve to the same
@@ -373,11 +392,15 @@ 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 cleanup memory       # watchman and Gradle daemon memory; gc --cache watchman
+  stim guide tutorial             # tutorial sections and manual commands
+  stim guide tutorial run         # create the app and build in a tour worktree
   stim guide settings             # configuration files and supported keys`
-	},
-	facts: {
-		summary: "The --json payloads: `start`, `ios`, `android`, `web`, `ios|android --plan`, `reload`, `stop`, `status`, `doctor`, `device lock`/`unlock`, `gc`, and the error contract",
-		preamble: () => `SLOTS
+};
+//#endregion
+//#region src/guide/facts.ts
+const facts = {
+	summary: "The --json payloads: `start`, `ios`, `android`, `web`, `ios|android --plan`, `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.
@@ -395,6 +418,14 @@ status adds archived (newest first, bounded by archive.maxCount) and
 archivedUsage { count, bytes, byKind: { logs, recordings, agentActions, record } }.
 Each archive carries id, projectRoot, project, workspace, worktree facts,
 removedAt, removedBy, lastUsedAt, builds, agents, bytes, expires and version.
+When the worktree folder was already gone, as when gc prunes a dead project,
+the worktree facts come from the pull request cache of that gone worktree
+when Stim cached one: branch, head and pullRequest, with merged true only when
+that pull request merged and null otherwise; repository and subject are null.
+Without a cached entry every worktree fact is null.
+Archive builds is a summary { count, last, lastErrorCount }. With read access,
+server archive.detail { archive: id } returns live-shaped builds and recordings
+{ platform, slot, spans } for each retained recording slot with footage.
 replacedBy is the live environment path when its canonical root matches.
 Older producers may omit both fields.
 Plain status prints Archived: <count> workspace(s), <size> when count is positive;
@@ -529,10 +560,10 @@ workspace leases no physical device.
 
 Plain status prints "ios: Old iPhone (physical, iPhone 12 Pro) connected --
 leased until <time>" for each one.`,
-		sections: {
-			payloads: {
-				summary: "every field of the start, ios, android, macos, web and reload payloads, the error contract, the device rules",
-				body: () => `  stim start --json
+	sections: {
+		payloads: {
+			summary: "every field of the start, ios, android, macos, web and reload payloads, the error contract, the device rules",
+			body: () => `  stim start --json
 
   port            the Metro port RESERVED for this workspace
   supervisorPid   the detached supervisor's pid, or NULL when a dev server was
@@ -969,10 +1000,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
@@ -1097,10 +1128,10 @@ 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, results, inventory, and the gc refusals",
-				body: () => `  stim gc [--delete] [--older-than <days>] [--cache <name|all|workspaces|recordings|parked>]
+		},
+		gc: {
+			summary: "the gc report payload: mode, sections, reasons, failures, results, inventory, and the gc refusals",
+			body: () => `  stim gc [--delete] [--older-than <days>] [--cache <name|all|workspaces|recordings|parked>]
           [--worktrees] [--idle <duration>] --json
 
   The report the text prints, as one payload. Show the user its sections
@@ -1127,7 +1158,8 @@ RULES
                   id, bytes, detail } per entry it acted on; empty on a dry
                   run. status is "done", "kept" (left alone, detail says
                   why) or "failed" (detail says why and what to retry).
-                  kind: device, parkedDevice, idleDevice, deviceRecord,
+                  kind: device, parkedDevice, parkedHostedDevice, idleDevice,
+                  deviceRecord,
                   workspaceOutputs, recording, workspaceDirectory, project,
                   buildLock, buildSlot, deviceLease, easSession, worktree,
                   cache.
@@ -1199,6 +1231,14 @@ RULES
     parkedEmulators         { name, systemImage, deviceProfile, parkedAt, app,
                               bytes, listed }  app is the package name;
                               likewise
+    parkedHostedDevices     { session, client, platform, id, name, parkedAt,
+                              listed }  parked iOS/Android sessions
+                              on this host; client is its registry id, id is
+                              the UDID or AVD name, name is the device label.
+                              listed means its private home ledger lists the
+                              device; false means already removed and is not
+                              actionable; null means unreadable. --older-than
+                              filters by parkedAt; --cache scopes leave this empty
     orphanedDevices         { kind, id, name, bytes, directory }
     unverifiedDevices       { kind, id, name, command }  stim-* devices this
                               Stim home has no record of creating; never
@@ -1318,10 +1358,10 @@ RULES
     caches on this machine
   - --cache together with --worktrees or --idle
   - --cache watchman or gradle-daemons together with --older-than`
-			},
-			status: {
-				summary: "the status payload's lifecycle phase and stage, issues and their codes, build and device activity fields: a running build, its estimate, each platform's last build, who drives each device, whether the app runs on it, and what uses CPU and memory now",
-				body: () => `  stim status --json
+		},
+		status: {
+			summary: "the status payload's lifecycle phase and stage, issues and their codes, build and device activity fields: a running build, its estimate, each platform's last build, who drives each device, whether the app runs on it, and what uses CPU and memory now",
+			body: () => `  stim status --json
 
   logs        { dir, errorsSinceMarker }, or null without a log directory
   agentDevice { stateDir }: absolute workspace agent-device state path on
@@ -1350,6 +1390,11 @@ RULES
               other route to web. macOS needs Package.swift, macos.product
               and macos.infoPlist. Detection reads config literals and
               files, never runs project scripts.
+  tutorial    { version }: present only when app.json sets
+              expo.extra.stimTutorial to a positive integer, the marker
+              of the Stim tutorial app (stim guide tutorial). Status
+              reports whatever version it finds; Desktop decides which
+              versions it supports. Static app.json only.
   recording   { enabled }: whether stim-server may record the workspace's
               device screens for replay, from recording.enabled
 
@@ -1502,9 +1547,10 @@ RULES
                    lock, argent, xcodebuild, idb, maestro, appium, simctl,
                    uiautomator or instrumentation; pid and since are null when
                    the claim does not record them
-  lastActivityAt   the newest of this device's app log records, this
-                   platform's Metro bundle requests, the workspace's last
-                   Stim run, while agent-device drives it the agent's last
+  lastActivityAt   the newest of this device's app log records, changes to
+                   the workspace's client.ndjson and device.ndjson logs,
+                   this platform's Metro bundle requests, the workspace's
+                   last Stim run, while agent-device drives it the agent's last
                    recorded action, and now while a stim-server client views
                    it, rounded down to the minute; absent when none is
                    recorded
@@ -1533,12 +1579,14 @@ RULES
   Plain \`stim status\` appends it to each device line: "driven by
   agent-device for 12m", "active", "idle 3h", or "activity unknown (...)".
 
-  An owned device that is not booted after its supervisor shut it down for
-  devices.idleShutdownMinutes carries idleShutdown, and plain \`status\`
+  An owned device that is not booted after supervisor idle shutdown or queue
+  reclaim carries idleShutdown, and plain \`status\`
   appends "shut down after 30m idle at <at>" to its line; the next \`ios\` or
   \`android\` run for that slot clears it (\`guide lifecycle budget\`):
 
-  idleShutdown  { at, idleMinutes }
+  idleShutdown  { at, idleMinutes, reason?: "idle" | "reclaimed for a waiting run" }
+  Absent reason or "idle" means supervisor idle shutdown; reclaim adds
+  "reclaimed for a waiting run" to plain status.
   \`gc --idle <duration>\` shuts down owned devices idle that long
   (\`guide cleanup gc\`).
 
@@ -1617,7 +1665,7 @@ RULES
             outcome, outcomeKnown, cacheLookupOutcome?, expectedMs, expectedPhaseMs,
             completedPhaseMs?, basis,
             plannedPhases, missReason?, missProvisional?, detail?, placement,
-            waitingOn? }
+            waitingOn?, waitingFor? }
 
   state            "running" while the run's own native-run claim is live;
                    "stale" when that claim was released or its process is
@@ -1647,7 +1695,7 @@ RULES
                    the project's most recent one
   cacheLookupOutcome  "hit" or "miss" once an actual cache lookup resolves;
                    absent before resolution and on runs that skip lookup,
-                   such as --eas-profile
+                   such as --eas-profile or --no-build-cache
   expectedMs       the median duration of this project's last successful
                    runs with that outcome on that platform, or null with
                    no history. The run estimates twice: when it starts,
@@ -1703,6 +1751,9 @@ RULES
                    startedAt is when the offload started and phaseStartedAt
                    when that step did. Meanwhile phase above follows it as
                    prebuild, pods or compile.
+  waitingFor       optional { kind: "build-slot" | "device-slot", inUse, max,
+                   since } for a slot wait, independently of phase. since is
+                   ISO. Overlapping waits show the first, then the remaining one.
   waitingOn        while phase is "wait" and the holder is known: { path },
                    the workspace whose build of the same artifact this run
                    waits for; absent otherwise. The lock is machine-wide, so
@@ -1720,7 +1771,7 @@ RULES
   lastBuilds   { ios?, android? }, each { platform, status, cacheHit,
                cacheSkipped, durationMs, fingerprint, startedAt, finishedAt,
                errorCode?, missReason?, buildMachine?, builtOn?, offloadedTo?, offloadFallback?,
-               diagnostics? }
+               diagnostics?, devicePlacement? }
 
   status       "ok" or "failed"
   cacheHit     "local" or "remote" for an app from that cache tier; false
@@ -1947,10 +1998,10 @@ RULES
   simulator is booted, no workspace is live and no build runs: status then
   runs neither. \`status --watch --json\` rereads both every 15 seconds while
   machine is not null, with no other subprocess.`
-			},
-			plan: {
-				summary: "the ios and android --plan payload: fingerprint, cacheHit, prebuild, missReason, expectedMs and basis",
-				body: () => `  stim ios --plan --json            # or: stim android --plan --json
+		},
+		plan: {
+			summary: "the ios and android --plan payload: fingerprint, cacheHit, prebuild, missReason, expectedMs and basis",
+			body: () => `  stim ios --plan --json            # or: stim android --plan --json
 
   { platform, slot?, fingerprint, cacheKey, cacheHit, provider,
     cacheSkipped, prebuild, outcome, expectedMs, basis, missReason?,
@@ -1989,10 +2040,10 @@ RULES
   STIM_NO_FINGERPRINT, STIM_EAS_UNAVAILABLE, or STIM_BAD_ARG for a flag that
   picks a device. When and why a plan and the run can differ: \`guide
   lifecycle builds\`.`
-			},
-			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>,
@@ -2002,6 +2053,8 @@ RULES
                  "machines": { "<machine>": { "today": <day>,
                                               "total": <totals> } },
                  "placements": [<placement>, ...] },
+    "capacityRefusals": [<capacityRefusal>, ...],
+    "capacityWaits": [<capacityWait>, ...],
     "agentDevice": <AgentDeviceUsage|null>,
     "swiftpmCache": <SwiftpmCacheUsage|null> }
 
@@ -2014,6 +2067,25 @@ RULES
   average, time saved and build estimates stay local. Milliseconds are
   integers.
 
+CAPACITY REFUSALS
+  capacityRefusals?: [{ at, kind: "device", platform: "ios" | "android",
+                       max, workspace }]
+  Only device refusals with STIM_AT_CAPACITY are recorded; build caps wait.
+  at is the ISO timestamp, max is concurrency.maxDevices, and workspace is
+  the workspace id used by status and Desktop. The list is newest first:
+  the last 50 from the last 7 days, omitted when empty. Desktop uses events
+  within 6 hours for its device-limit suggestion, including terminal runs.
+  Recording is best effort and does not change the refusal. Plain stats
+  output is unchanged.
+  capacityWaits?: [{ at, kind: "device-wait", platform: "ios" | "android",
+                    ms, max, workspace, reclaimed? }]
+  Each owned-device slot wait records its whole elapsed milliseconds,
+  including waits that time out or fail. It has the same 50-event, 7-day
+  retention, newest-first order, workspace id and best-effort recording.
+  reclaimed is the whole count of devices shut down for the waiting run,
+  omitted when zero. Plain stats reports waits with a positive reclaim count.
+  It is omitted when empty.
+
 AGENT-DEVICE DISK USAGE
   agentDevice: { version: 1, measuredAt, bytes, complete, stateDir,
                  runnerBuilds, workspaces, hosted }
@@ -2095,10 +2167,20 @@ HOW A RUN IS COUNTED (\`stats\`)
   ignores what it cannot read, so nothing about statistics can change a
   run's outcome.
 
+DEVICE PLACEMENT (\`ios|android --remote auto\`)
+  Auto runs include devicePlacement: { decision, reason, machine? } in the run
+  facts, lastBuilds and build history. decision is "local", "hosted" or
+  "waited-locally" (the local run actually waited for a device slot). The same
+  optional devicePlacement appears on the status device entry for each slot.
+  Hosted host facts include selected: "auto" or the named machine, and reason
+  for automatic placement. Plain status prints (auto: <reason>) after the host.
+  Old hosted records without selected still read as the machine name.
+
 BUILD PLACEMENT (\`offload\`)
   Every run that compiles records where it built and why, in a placement: { at, project, platform,
-  decision, reason, machine?, buildMs?, slotWaitMs?, localEstimateMs?, failed? }.
-  slotWaitMs is whole milliseconds waiting for a build slot, present only when positive.
+  decision, reason, machine?, buildMs?, slotWaitMs?, deviceSlotWaitMs?, localEstimateMs?, failed? }.
+  slotWaitMs and deviceSlotWaitMs are whole milliseconds waiting for build
+  and owned-device slots respectively, present only when positive.
   decision is "here", "offloaded", or "fell-back" (it tried a build machine
   and built here). reason is why: the run's \`placement:\` reason, such as
   "load 0.6/core, 1 of 3 build slots busy here" (auto keeps the build here
@@ -2117,12 +2199,14 @@ BUILD PLACEMENT (\`offload\`)
   machine was slower. \`offload.today\` counts the day's placements by
   decision. A fallback counts against a machine only when the run knows
   which one: the machine that failed, or the only one paired.`
-			}
 		}
-	},
-	metro: {
-		summary: "The dev server: `stim start`, the supervisor, and starting your own",
-		body: () => `THE DEV SERVER
+	}
+};
+//#endregion
+//#region src/guide/metro.ts
+var metro_default = {
+	summary: "The dev server: `stim start`, the supervisor, and starting your own",
+	body: () => `THE DEV SERVER
 
   stim start
   stim start --remote   # prepare Metro for a remote device
@@ -2156,9 +2240,10 @@ HOSTED IOS METRO
   Hosted Debug runs require the supervisor's private gateway support before
   reservation. --no-metro-check refuses; restart a missing or older supervisor
   with stim stop; stim start.
-  Native iOS logs are pulled from the host by stim logs, including --errors;
+  Native iOS and Android logs are pulled from the host by stim logs, including --errors;
   JavaScript logs still arrive through Metro. Stop pulls native logs before
-  deleting the simulator. Read guide lifecycle hosted-ios for placement and cleanup.
+  deleting the owned device and copies the final host tail afterwards. Read guide
+  lifecycle hosted-ios or hosted-android for placement and cleanup.
 
 TAILNET-ONLY METRO
   Install Tailscale and sign in on this machine and the remote device or
@@ -2207,6 +2292,13 @@ BUNDLE WARMUP
   waits for the app's own bundle response. With a bundler started outside Stim,
   device logs may prove a request, but bundle completion may stay unverified.
 
+HOSTED ANDROID
+  android --remote <machine> keeps Metro here through the private tailnet
+  gateway. The host reverses the client Metro port into its loopback bridge
+  on the exact owned emulator. Each run and reload restores that reverse;
+  no adb command for the host serial runs here. metro.tunnel and metro.publicUrl
+  are ignored. See guide lifecycle hosted-android.
+
 REMOTE DEVICE BACKENDS
   Metro exposure and device selection are separate:
 
@@ -2302,7 +2394,7 @@ WHAT THE SUPERVISOR IS
   connected app alone does not keep the server. It records a
   supervisor_idle_stopped line in metro.ndjson and devServerStop in
   state.json, so \`status\` shows "stopped (idle)" rather than a crash.
-  Devices stay booted, unless devices.idleShutdownMinutes is set: then the
+  Devices stay booted, unless devices.idleShutdownMinutes is above 0 (the default is 30): then the
   idle stop first shuts down the workspace's owned devices idle for the
   shorter of the two (\`guide lifecycle budget\`). The next \`stim start\`
   starts it again and clears the
@@ -2395,10 +2487,12 @@ 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.`
-	},
-	ports: {
-		summary: "Workspace ports for web and API servers that Stim does not manage",
-		body: () => `NAMED SERVER PORTS
+};
+//#endregion
+//#region src/guide/ports.ts
+var ports_default = {
+	summary: "Workspace ports for web and API servers that Stim does not manage",
+	body: () => `NAMED SERVER PORTS
 
 If Stim is not installed globally, replace stim with npx stim.
 
@@ -2466,10 +2560,12 @@ cleanup: versions without ports do not know about named allocations.
 
 A shared API does not get a shared reservation. Pass its port by environment
 instead of allocating a separate label in every worktree.`
-	},
-	logs: {
-		summary: "Querying the merged NDJSON timeline, and what --errors means",
-		body: () => `LOGS
+};
+//#endregion
+//#region src/guide/logs.ts
+var logs_default = {
+	summary: "Querying the merged NDJSON timeline, and what --errors means",
+	body: () => `LOGS
 
 If Stim is not installed globally, replace stim with npx stim.
 
@@ -2836,7 +2932,7 @@ WHAT WRITES WHAT
                        session records (~/.agent-device/sessions, or
                        AGENT_DEVICE_STATE_DIR, plus existing workspace
                        agent-device directories) for this workspace's owned
-                       simulators and emulators, read-only. An action is
+                       simulators, emulators and native Mac app, read-only. An action is
                        info (msg is agent-device's summary, e.g. "Tapped
                        (201, 731)"; event agent_action with command, session,
                        deviceId and details, and startedAt when agent-device
@@ -2847,7 +2943,13 @@ WHAT WRITES WHAT
                        match a simulator through their runner.log, Android
                        sessions only while agent-device's claim on the
                        emulator is live (released claims drop their
-                       actions from later queries). A session in an
+                       actions from later queries). A macOS session opened
+                       with explicit --surface app matches its isolated
+                       bundle ID and current launch (guide macos). App
+                       switches, unrecorded opens and rotated event logs
+                       clear that match; native screenshots are omitted
+                       because their surface is not in the event metadata.
+                       A session in an
                        unrecognized format yields one warn record
                        (agent_format_unknown) instead of its actions.
   build-ios.ndjson     the xcodebuild / gradle transcript at level debug, the
@@ -2863,57 +2965,65 @@ WHAT WRITES WHAT
 
   A collector is killed and replaced on the next \`ios\` / \`android\` run for
   that platform, and reaped by \`stop\`.`
-	},
-	errors: {
-		summary: "Every refusal Stim can print: an index of codes, and one section for each",
-		sectionHint: "<CODE>",
-		preamble: () => `WHAT STIM REFUSES, AND WHY
+};
+//#endregion
+//#region src/guide/errors.ts
+const errors = {
+	summary: "Every refusal Stim can print: an index of codes, and one section for each",
+	sectionHint: "<CODE>",
+	preamble: () => `WHAT STIM REFUSES, AND WHY
 
 Every refusal listed here carries a stable CODE, whichever command prints it.
 Branch on the code, never on the message.`,
-		sections: {
-			STIM_HOSTING_REFUSED: {
-				summary: "a named hosting Mac refused or could not confirm its iOS session; no local fallback",
-				body: () => `STIM_HOSTING_REFUSED
+	sections: {
+		STIM_HOSTING_REFUSED: {
+			summary: "a hosting Mac refused or could not confirm its native session; no fallback after reservation",
+			body: () => `STIM_HOSTING_REFUSED
   The message names the hosting Mac and its reason: unreachable or changed
-  tailnet node, no installed simulator choice, no capacity, elevated or unknown
+  tailnet node, no installed simulator or emulator choice, no capacity, elevated or unknown
   memory pressure, or an unresolved reservation or delivery. Stim boots nothing
-  locally and never tries another Mac. Check stim-server and Tailscale there,
-  then run stim doctor. Correct --device-type / --runtime when the offer names
+  locally and never tries another Mac after choosing a named host or creating a
+  hosted session. Auto skips declined offers before building, then uses the
+  local queue if none admits. A reserve refusal after an accepted offer fails
+  with this code and asks to retry; it does not re-place the built architecture.
+  Check stim-server and Tailscale there,
+  then run stim doctor. Correct --device-type / --runtime for iOS or
+  --system-image / --device-profile for Android when the offer names
   an unavailable choice. A session that exists stays recorded even if delivery
-  fails: retry stim ios --remote <machine>, or run stim stop to reconcile it.
+  fails: retry stim ios|android --remote <machine>, or run stim stop to reconcile it.
   An unreachable stop keeps the placement; rerun stim stop when the host answers.
   A failed build handoff uses upload instead. If native log queries are unavailable,
   logs prints a note on stderr and shows copied records. Update an older stim-server
-  on the host to enable iOS handoff and native logs (hello feature hosted-ios-data).
+  on the host to enable handoff and native logs (hello features hosted-ios-data
+  for iOS and hosted-android-data for Android).
   A name outside hosting.machines is STIM_BAD_ARG. Missing or pending hosting
   approval keeps the doctor --fix and stim-server devices grant remedies.`
-			},
-			STIM_EAS_BUILD_MISSING: {
-				summary: "no completed EAS development build matches; build only with session authorization",
-				separator: "--- EAS BUILD CODES (`ios --eas-profile` / `android --eas-profile`) ---",
-				body: () => `STIM_EAS_BUILD_MISSING
+		},
+		STIM_EAS_BUILD_MISSING: {
+			summary: "no completed EAS development build matches; build only with session authorization",
+			separator: "--- EAS BUILD CODES (`ios --eas-profile` / `android --eas-profile`) ---",
+			body: () => `STIM_EAS_BUILD_MISSING
   No compatible build matches the selected EAS project, profile, platform and
   native fingerprint. No device was acquired and no local or cloud build was
   started. The remedy prints the exact npx eas-cli build command. Check session
   authorization for its potential cost before running it, then retry Stim.
   See stim guide lifecycle eas.`
-			},
-			STIM_EAS_UNAVAILABLE: {
-				summary: "EAS lookup/download failed, or another run holds the artifact claim",
-				body: () => `STIM_EAS_UNAVAILABLE
+		},
+		STIM_EAS_UNAVAILABLE: {
+			summary: "EAS lookup/download failed, or another run holds the artifact claim",
+			body: () => `STIM_EAS_UNAVAILABLE
   EAS CLI is unavailable 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
@@ -2921,10 +3031,10 @@ 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: "the recorded launch's port is not this workspace's live dev server (reload)",
-				body: () => `STIM_NO_METRO
+		},
+		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. Run
   \`stim start\`, or run \`ios\` or \`android\` again.
@@ -2935,19 +3045,19 @@ Branch on the code, never on the message.`,
   (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
+		},
+		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 or regenerate the native directory",
-				body: () => `STIM_PREBUILD_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.
@@ -2958,10 +3068,10 @@ Branch on the code, never on the message.`,
   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
+		},
+		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.
@@ -2989,10 +3099,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 Android missing-SDK and APK refusals; a damaged compilation-cache object",
-				body: () => `STIM_BUILD_FAILED
+		},
+		STIM_BUILD_FAILED: {
+			summary: "xcodebuild or gradle failed; the Android missing-SDK and 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.
   Three Android refusals share this code without gradle itself failing:
@@ -3029,10 +3139,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
@@ -3048,10 +3158,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
@@ -3121,10 +3231,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.
@@ -3133,10 +3243,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.
@@ -3174,19 +3284,19 @@ Branch on the code, never on the message.`,
   Legacy inline \`deletionClaim\` fields in config.json have no process
   identity and require separate manual inspection; \`stim guide lifecycle pool\`
   describes their field-only recovery.`
-			},
-			STIM_MACOS_OWNER_UNVERIFIED: {
-				summary: "the macOS app owner cannot be verified; no signal is sent",
-				body: () => `STIM_MACOS_OWNER_UNVERIFIED
+		},
+		STIM_MACOS_OWNER_UNVERIFIED: {
+			summary: "the macOS app owner cannot be verified; no signal is sent",
+			body: () => `STIM_MACOS_OWNER_UNVERIFIED
   The recorded macOS process identity is unavailable or its workspace record
   is malformed. Stim sends no signal to an owner it cannot verify. Inspect the
   named process and workspace record before repairing it; do not replace a PID
   or token with another running app. Retry stim stop once identity inspection
   works. See stim guide macos.`
-			},
-			STIM_OFFLOAD_REFUSED: {
-				summary: "the selected build machine cannot build this app",
-				body: () => `STIM_OFFLOAD_REFUSED
+		},
+		STIM_OFFLOAD_REFUSED: {
+			summary: "the selected build machine cannot build this app",
+			body: () => `STIM_OFFLOAD_REFUSED
 
 A named --build-machine selection is strict. The message names the machine
 and why it cannot take or finish the build: not configured or paired, approval
@@ -3207,10 +3317,26 @@ or runs stim-server setup on the worker with its node, ticket and expiry
 Rerun with --build-machine auto for normal placement and local fallback, or
 --build-machine local to keep the build here.
 `
-			},
-			STIM_CLAIM_UNAVAILABLE: {
-				summary: "a process identity or warm claim store is unavailable, so the protected operation refuses",
-				body: () => `STIM_CLAIM_UNAVAILABLE
+		},
+		STIM_WORKTREE_SERVICE: {
+			summary: "worktree remove refuses a folder a stim-server service runs from",
+			body: () => `STIM_WORKTREE_SERVICE
+  A LaunchAgent that \`stim-server service install\` wrote (it carries a
+  StimService marker in ~/Library/LaunchAgents/<label>.plist, default label
+  dev.stim.server) runs a program from inside this worktree. Removing the
+  folder would delete the running server's code. The refusal also covers a
+  service that is installed but stopped, because launchd loads it again at the
+  next login, and a marked plist Stim could not read. \`--force\` does not
+  override it, and gc leaves the worktree in place.
+  Reinstall the service from another build (stim-server service install --label
+  <label> from a checkout that stays), or remove it with stim-server service
+  uninstall --label <label>, then run stim worktree remove again. Nothing was
+  reclaimed or removed. Other processes with their working directory in the
+  folder are not detected.`
+		},
+		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
@@ -3230,10 +3356,10 @@ Rerun with --build-machine auto for normal placement and local fallback, or
   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.
@@ -3255,10 +3381,10 @@ Rerun with --build-machine auto for normal placement and local fallback, or
   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
+		},
+		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
@@ -3278,25 +3404,25 @@ Rerun with --build-machine auto for normal placement and local fallback, or
   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_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.
@@ -3305,14 +3431,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;
@@ -3326,14 +3452,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
@@ -3341,14 +3467,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
@@ -3356,14 +3482,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.
@@ -3372,13 +3498,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
@@ -3388,12 +3514,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
@@ -3479,11 +3605,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
@@ -3495,6 +3621,10 @@ so a Debug run on one is wired to a LAN origin instead of localhost.`,
   reach a booted state. \`stim doctor\` checks the toolchain; \`stim status\` says what
   Stim thinks it owns. Re-running the command creates a fresh owned device
   when the recorded one is gone.
+  With concurrency.maxDevices set, it also means Stim could not count the
+  booted devices before a boot: a simctl or adb listing failed or timed out,
+  usually under heavy load, or other runs held the device-admission lock for
+  5 minutes. Retry once the load falls.
   If Android creation says an AVD already exists on disk but is not listed,
   run \`npx stim gc\` to inspect orphaned owned AVDs, then \`npx stim gc --delete\`
   to reclaim those safe to delete before retrying. Keep anything GC cannot
@@ -3552,10 +3682,10 @@ so a Debug run on one is wired to a LAN origin instead of localhost.`,
   The Android counterpart, from \`--device-profile\` or android.deviceProfile.
   Reap the AVD the same way, or pass \`--slot <name>\` to create the requested
   profile beside it.`
-			},
-			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
@@ -3569,10 +3699,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
@@ -3584,10 +3714,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.
@@ -3595,24 +3725,32 @@ 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
-  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
-  a queue -- \`ios\`/\`android\` are interactive-shaped, so Stim does not make
-  you wait at a prompt. The remedy is fixed: stop an environment
-  (\`stim stop\`) to free a device, or raise concurrency.maxDevices. A
-  workspace whose OWN device is already booted is never refused -- re-running
-  \`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_LOW_DISK: {
-				summary: "free disk stayed below budget.hardFloorDiskGb after reclaiming",
-				body: () => `STIM_LOW_DISK
+		},
+		STIM_AT_CAPACITY: {
+			summary: "owned-device slot wait timed out, or --no-wait reached the cap or queue",
+			body: () => `STIM_AT_CAPACITY
+  Only when concurrency.maxDevices is set (unset by default). New owned
+  devices queue in FIFO order across $STIM_HOME for 600 seconds by default.
+  This refusal means the wait expired, or \`--no-wait\` / \`--wait 0\`
+  found the cap full or another run queued. The message gives the current
+  count and, on timeout, how long it waited. iOS waits beside its build,
+  so a rerun can reuse the artifact. A workspace's own booted or booting
+  device bypasses the queue. At the cap, the FIFO head shuts down the
+  longest-idle eligible owned device from another workspace, one per attempt,
+  at most once every 15 seconds, then rechecks capacity.
+  devices.reclaimIdleMinutes defaults to 10; 0 off. The same idle checks as supervisor shutdown (default 30 minutes) protect drivers,
+  locks, builds, viewers and recent activity. Reclaim excludes this workspace,
+  physical, hosted, remote, parked and other homes' devices and never deletes.
+  A failed reclaim is logged and skipped; the run keeps waiting.
+  Stop an environment (\`stim stop\`), pass a longer \`--wait <seconds>\`,
+  or raise concurrency.maxDevices. Waiting prints holder names and elapsed
+  time; status JSON exposes build.waitingFor independently of phase.
+  Stats records capacityWaits for waits and capacityRefusals for this code.
+  See \`guide lifecycle concurrency\`.`
+		},
+		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
@@ -3633,10 +3771,10 @@ so a Debug run on one is wired to a LAN origin instead of localhost.`,
   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
+		},
+		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
@@ -3650,44 +3788,44 @@ 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 21.6.0 or later",
-				body: () => `STIM_REMOTE_EAS_UNAVAILABLE
+		},
+		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_DEVICE_MISMATCH: {
-				summary: "the recorded EAS session runs another model than --device-type asks for; stop, then rerun",
-				body: () => `STIM_REMOTE_DEVICE_MISMATCH
+		},
+		STIM_REMOTE_DEVICE_MISMATCH: {
+			summary: "the recorded EAS session runs another model than --device-type asks for; stop, then rerun",
+			body: () => `STIM_REMOTE_DEVICE_MISMATCH
   \`stim ios --remote eas --device-type <name>\` found this workspace's
   recorded EAS Simulator session still running another model, or the model
   EAS chose when no --device-type was given. EAS cannot change a running
@@ -3696,20 +3834,20 @@ so a Debug run on one is wired to a LAN origin instead of localhost.`,
   workspace, then rerun with the model you want. A recorded session that has
   already ended is replaced on the requested model instead, and without
   --device-type a live one is reused as it is. Nothing was created here.`
-			},
-			STIM_REMOTE_SESSION_STATE: {
-				summary: "the EAS session was created but its state could not be recorded, so Stim stopped it",
-				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.
@@ -3718,10 +3856,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.
@@ -3731,32 +3869,32 @@ 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: "more than one owned app or the owned Chrome is live; name the platform",
-				separator: "--- RELOAD CODES (`stim reload [ios|android|web]`) ---",
-				body: () => `STIM_RELOAD_AMBIGUOUS
+		},
+		STIM_RELOAD_AMBIGUOUS: {
+			summary: "more than one owned app or the owned Chrome is live; name the platform",
+			separator: "--- RELOAD CODES (`stim reload [ios|android|web]`) ---",
+			body: () => `STIM_RELOAD_AMBIGUOUS
   More than one of the owned iOS app, Android app and Chrome page is live.
   Name ios, android or web; 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. For web,
   STOPPED means no owned Chrome is running (run stim web) and PROBE_FAILED
@@ -3764,10 +3902,10 @@ so a Debug run on one is wired to a LAN origin instead of localhost.`,
   only when no native launch is recorded. 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.
 
@@ -3798,72 +3936,72 @@ 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_WEB_NO_CHROME: {
-				summary: "stim web found no installed Chrome or Chromium",
-				separator: "--- WEB CODES (`stim web`) ---",
-				body: () => `STIM_WEB_NO_CHROME
+		},
+		STIM_WEB_NO_CHROME: {
+			summary: "stim web found no installed Chrome or Chromium",
+			separator: "--- WEB CODES (`stim web`) ---",
+			body: () => `STIM_WEB_NO_CHROME
   stim web drives the installed Google Chrome (or Chromium) with a profile
   Stim creates. It looks in /Applications and ~/Applications on macOS, in
   Program Files on Windows, and for google-chrome or chromium on PATH. Stim
   never installs a browser. Install Chrome, then run stim doctor.`
-			},
-			STIM_WEB_NO_URL: {
-				summary: "not an Expo app and web.url is unset, so Stim does not know which page to open",
-				body: () => `STIM_WEB_NO_URL
+		},
+		STIM_WEB_NO_URL: {
+			summary: "not an Expo app and web.url is unset, so Stim does not know which page to open",
+			body: () => `STIM_WEB_NO_URL
   Only Expo serves web from Metro, so for any other app Stim needs web.url.
   stim web never starts a web server, for any framework. Start yours on a
   named port and point web.url at it:
     pnpm exec vite --port "$(stim ports get web)" --strictPort
     stim settings set web.url 'http://localhost:{port:web}/' --scope workspace
   See stim guide web.`
-			},
-			STIM_WEB_DEPS_MISSING: {
-				summary: "an Expo app without react-native-web cannot render on the web",
-				body: () => `STIM_WEB_DEPS_MISSING
+		},
+		STIM_WEB_DEPS_MISSING: {
+			summary: "an Expo app without react-native-web cannot render on the web",
+			body: () => `STIM_WEB_DEPS_MISSING
   The Expo app does not resolve react-native-web, so Metro cannot build a web
   bundle. Install the web dependencies, start Metro, then run stim web again:
     npx expo install react-dom react-native-web @expo/metro-runtime
     stim start`
-			},
-			STIM_WEB_BROWSER_HELD: {
-				summary: "the previous owned Chrome could not be stopped or verified; it was left running",
-				body: () => `STIM_WEB_BROWSER_HELD
+		},
+		STIM_WEB_BROWSER_HELD: {
+			summary: "the previous owned Chrome could not be stopped or verified; it was left running",
+			body: () => `STIM_WEB_BROWSER_HELD
   stim web replaces the workspace's owned Chrome when its options change, and
   the previous one could not be stopped: its supervisor or Chrome did not
   exit, or their process identities could not be verified. Stim never signals
   a process it cannot verify. Check stim status for browser-unverified, then
   follow stim guide errors teardown.`
-			},
-			STIM_WEB_LAUNCH_FAILED: {
-				summary: "the owned Chrome did not start or did not open DevTools on its reserved port",
-				body: () => `STIM_WEB_LAUNCH_FAILED
+		},
+		STIM_WEB_LAUNCH_FAILED: {
+			summary: "the owned Chrome did not start or did not open DevTools on its reserved port",
+			body: () => `STIM_WEB_LAUNCH_FAILED
   The browser supervisor exited before Chrome answered on its reserved
   DevTools port. The remedy names the supervisor log; web.ndjson carries the
   failure as web_browser_failed, and browser.log holds Chrome's own output.
   A port another process bound first also lands here: run stim web again to
   reserve a fresh one.`
-			},
-			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
@@ -3875,15 +4013,15 @@ 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.
   A Debug \`ios\` or \`android\` run that starts the dev server reports the
@@ -3892,10 +4030,10 @@ captured"  (in metro.ndjson, bare RN)
   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
@@ -3910,11 +4048,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
@@ -3932,8 +4070,9 @@ captured"  (in metro.ndjson, bare RN)
   on an eas/proxy run (\`--remote\` or ios.remote; that backend picks the
   iOS version), \`ios --device-type\` on the proxy backend or with an
   eas-cli older than 22.2.0 on the eas backend, \`android --system-image\` or
-  \`--device-profile\` on a remote run (\`--remote\` or android.remote), a
-  working directory
+  \`--device-profile\` on an eas/proxy run (\`--remote\` or android.remote), a
+  \`android --remote auto\`, a changed hosted placement, or hosted Debug
+  with \`--no-metro-check\` (see lifecycle hosted-android), a working directory
   with no package.json above it, or one whose nearest package.json does not
   parse or depends on neither react-native nor expo, so the directory is not
   an app (the refusal names that package.json and says which of the two it
@@ -3982,11 +4121,11 @@ captured"  (in metro.ndjson, bare RN)
   list device -c\`) 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:
@@ -3995,10 +4134,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_CANCELLED: {
-				summary: "an ios or android run was interrupted by `stim stop` or Ctrl-C before it finished",
-				body: () => `STIM_CANCELLED  (ios, android; exit 130)
+		},
+		STIM_CANCELLED: {
+			summary: "an ios or android run was interrupted by `stim stop` or Ctrl-C before it finished",
+			body: () => `STIM_CANCELLED  (ios, android; exit 130)
   "The ios run was cancelled by \`stim stop\` (pid <n>) before it finished."
   The run received SIGINT: from \`stim stop\`, which interrupts a build it
   leaves with nothing to deploy to, or from Ctrl-C. It forwarded the interrupt
@@ -4010,10 +4149,10 @@ captured"  (in metro.ndjson, bare RN)
   second SIGINT exits at once, and so does a run that holds a physical-device
   lease; those exits print no payload. Run the same command again when you want the
   app on a device.`
-			},
-			STIM_STOP_BLOCKED: {
-				summary: "`stop` could not interrupt the ios or android run holding this workspace; names its pid and claim",
-				body: () => `STIM_STOP_BLOCKED  (stop)
+		},
+		STIM_STOP_BLOCKED: {
+			summary: "`stop` could not interrupt the ios or android run holding this workspace; names its pid and claim",
+			body: () => `STIM_STOP_BLOCKED  (stop)
   \`stop\` found a live \`ios\` or \`android\` run holding this workspace's
   native-run claim and could not end it:
   - "... did not exit within 60s of SIGINT": the run was interrupted but is
@@ -4030,10 +4169,10 @@ captured"  (in metro.ndjson, bare RN)
   session never waits on a build. The JSON payload carries the session
   outcome under device.remote. Devices, collectors and the dev server are left
   as they were.`
-			},
-			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 lock
   and for \`gc\` deleting EAS sessions under the EAS project lock (its sweep
@@ -4078,11 +4217,11 @@ captured"  (in metro.ndjson, bare RN)
   using it: if none is running, remove the named directory with that command.
   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.
@@ -4140,10 +4279,10 @@ emulator process <pid> is still running"
   no process-table check and Stim signals nothing there: it waits for the pid
   in the AVD's process lock after \`adb emu kill\`, and refuses at once when
   adb cannot reach the emulator.`
-			},
-			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
@@ -4167,10 +4306,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
@@ -4180,28 +4319,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
@@ -4219,20 +4358,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.
@@ -4273,11 +4412,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:
 
@@ -4298,10 +4437,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
@@ -4348,10 +4487,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")
@@ -4362,19 +4501,19 @@ 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.`
-			},
-			STIM_NODE_UNSUPPORTED: {
-				summary: "stim or stim-server started on a Node older than 22.12.0, often a project pin",
-				body: () => `STIM_NODE_UNSUPPORTED  ("Stim needs Node <floor> or later; this is Node <version> at <path>")
+		},
+		STIM_NODE_UNSUPPORTED: {
+			summary: "stim or stim-server started on a Node older than 22.12.0, often a project pin",
+			body: () => `STIM_NODE_UNSUPPORTED  ("Stim needs Node <floor> or later; this is Node <version> at <path>")
   stim and stim-server refuse before loading anything else when the Node that
   runs them is older than their engines floor. Both start through
   \`#!/usr/bin/env node\`, so the working directory can choose that Node: asdf,
@@ -4395,12 +4534,14 @@ not on any remote"  (worktree remove)
   is set for command stim" instead of running Stim. When that version is
   older than 22.12.0, first install Stim with npm under a supported version.
   The tools Stim starts inherit the override.`
-			}
 		}
-	},
-	lifecycle: {
-		summary: "The full worktree -> start -> ios/android -> logs -> teardown flow, with sections for builds, devices and flags",
-		preamble: () => `ENVIRONMENT LIFECYCLE
+	}
+};
+//#endregion
+//#region src/guide/lifecycle.ts
+const lifecycle = {
+	summary: "The full worktree -> start -> ios/android -> logs -> teardown flow, with sections for builds, devices and flags",
+	preamble: () => `ENVIRONMENT LIFECYCLE
 
 Two workflows share steps 2 through 6.
 
@@ -4651,10 +4792,152 @@ WAITING FOR A CHANGE
   nothing changes, except a closed stdout pipe on Linux whose starter is
   still running, which it notices at the next change.
   Without --json it reprints the human view on change.`,
-		sections: {
-			"hosted-ios": {
-				summary: "iOS on a named approved Mac: strict placement, private Metro, status and stop",
-				body: () => `IOS ON A HOSTING MAC
+	sections: {
+		"hosted-android": {
+			summary: "Android on a named approved Mac: strict placement, private Metro, status and stop",
+			body: () => `ANDROID ON A HOSTING MAC
+
+If Stim is not installed globally, replace stim with npx stim.
+
+  stim settings set hosting.machines '["janics-mac-mini"]'
+  stim doctor --fix
+  stim doctor
+  stim android --remote janics-mac-mini --device-profile pixel_7
+  stim status --json
+  stim reload android
+  stim stop
+
+A person on the host approves device-host access, separately from build, read
+and control. The setup in hosted-ios also serves Android. android.remote sets
+a workspace default. eas and proxy remain backends. --remote auto or
+android.remote = auto places automatically; see hosted-ios for the shared
+policy. No flag or setting runs on this Mac.
+
+A named Mac is strict: refusal, unreachable, declined or failed preparation
+returns STIM_HOSTING_REFUSED without fallback. --device, a different recorded
+machine, a running local owned emulator in the slot, and --no-metro-check for
+hosted Debug refuse STIM_BAD_ARG. Run stim stop before switching placement.
+Unreadable android.host blocks only its slot; restore its recorded machine and
+session from the host before stopping that slot.
+
+--system-image and --device-profile select installed choices on the host.
+The build targets the offered ABI and --build-machine independently selects a
+compatible build worker. Stim builds before reserving, records the session as
+soon as it exists, then delivers one App.apk. The emulator boots headless;
+androidEmulatorApp is ignored with a note.
+
+Debug requires the local Metro supervisor. metro.publicUrl and metro.tunnel
+are ignored with a note. A private tailnet gateway reaches the host loopback
+bridge; the host reverses the client's Metro port into that bridge on its exact
+ledger-owned serial and sets debug_http_host to localhost:<clientMetroPort>.
+Each run and stim reload android restores the reverse, including after a host
+adb server restart. Reload broadcasts through the local Metro and never runs
+adb against the host serial on this Mac. Release variants skip Metro. Launch
+is true only with client bundle evidence or a live host release process;
+bundling requires a bundle request and unverified has no launch evidence.
+
+Status adds android.host { machine, session, selected, agent, device: { name,
+systemImage, api }, state } per slot. The public name is the profile and API
+level, never the host serial or AVD name. ready, stopped and unverified are
+session probe states; a conflicting local emulator remains visible with a
+warning. A recorded placement keeps the workspace in use and blocks idle stop.
+
+stop and worktree remove wait for device-host.stop, park the host's eligible owned
+emulator within pool.androidParkedMax (delete otherwise), close the gateway and clear placement. stop --json reports
+outcomes.device["android:host:<slot>"]. Forbidden or unknown-session also clears
+placement; an unreachable host keeps it and fails cleanup. A clean host restart
+parks eligible devices; a later reserve by the same client adopts a compatible
+parked emulator with all third-party apps removed. Running sessions left by a
+crash stay unknown until explicit stop; booted devices are never re-attached
+after restart. See hosted-ios for retention and eviction. JavaScript logs
+arrive through local Metro.
+
+AGENT CONTROL
+
+Set hosting.agentDriver to agent-device on the hosting Mac. Both Macs need
+agent-device 0.21.22 or later. The host advertises hosted-android-agent and
+starts one loopback daemon per installed Android session. Its policy allows
+only the exact ledger-owned emulator serial and denies device shutdown.
+The host verifies the policy digest and android-instance backend before granting
+control. An older host, missing binary or unsupported policy reports driver: none;
+the host's notice explains unavailable control.
+
+android.host.agent in stim status --json provides driver, remoteConfig and
+command, never its token. Each slot has a separate 0600 file under the workspace
+state directory at hosted-android/<slot>/agent-device-remote.json. Use that file:
+
+  agent-device open <packageId> --remote-config <file>
+  agent-device snapshot --remote-config <file>
+  agent-device click <ref> --remote-config <file>
+  agent-device screenshot --remote-config <file>
+
+The command shape is agent-device <command> --remote-config <file>. Open leases
+the emulator automatically with android-instance, the proxy provider and this
+session's tenant. devices is permitted for the client's open flow; inventory
+contains only this emulator. Never use its serial with a local agent-device.
+Allowed commands are devices, open, close, snapshot, diff, wait, find, get, is,
+click, fill, press, type, focus, scroll, screenshot, longpress, swipe, back, home,
+orientation, appstate, alert and batch. Stim installs; install, reinstall,
+uninstall, boot, shutdown, close --shutdown, record, logs, uploads and device-wide
+actions are refused. Other serials in commands, flags, inputs, nested batches or
+lease requests are refused. Ambient client paths and owner fields are stripped;
+the host pins platform, serial, tenant, runId, clientId, deviceKey and backend.
+Host paths and launch inputs are refused. Screenshots use only remote artifacts.
+
+Stop closes the matching agent-device connection and removes the slot file only
+once the host confirms stop or revocation. Reinstall, stop, revocation and server
+close stop the daemon before native work or device deletion. An unresolved
+proxy, daemon or helper retains the child-aware daemon claim and refuses
+replacement or deletion, including after a server restart. Agent-device uses
+one-shot Android snapshots without helper adb forwards; teardown stops its
+snapshot and IME helper processes only on the pinned serial. Helper APKs remain
+on the owned emulator until Stim deletes it. A daemon exit rotates only that
+session's grant; rerun stim android to refresh its config.
+
+Stim Desktop and the phone app view and control the emulator through this
+Mac's local stim-server relay, with an "on <machine>" label. Turn on Serve to
+phones in Desktop and pair the phone with this Mac, not the hosting Mac.
+frames.subscribe and control.begin address workspace, platform android and
+slot, including named slots. The host verifies its exact ledger-owned serial,
+AVD identity and ABI before capture or input; clients never use that serial
+locally. Capture uses the host's stim-frames helper and scrcpy server jar over
+adb; stopping capture removes its jar and forward before emulator teardown.
+Stopped sessions show a rerun remedy; unavailable hosts report why frames
+cannot arrive. Replay (at/rate), duoFrame and physical hosted targets are
+refused. Desktop hides local emulator windows, rotation, clipboard and emulator
+options; touch, text and hardware buttons use the relay. Rotation and posture
+are unavailable through the scrcpy path.
+
+Reruns send only missing manifest and APK digests from the session-scoped blob
+store. The host verifies reused bytes; each new attempt still installs the APK.
+When an Android build ran on the hosting Mac's pinned node, the host takes only
+the single App.apk matching the client's manifest. The build and hosting approvals
+must belong to the same tailnet node. Handoff failure falls back to upload,
+retrying a busy host for at most one minute.
+
+stim logs, including --errors and --json, pulls native logcat records as src: device.
+The host rechecks the exact ledger-owned serial and AVD name, resolves the app's
+pid on each collection and also drains its last observed pid after a crash or
+restart. A successful drain retires the exited pid. A failed pid lookup preserves
+the checkpoint without querying logcat, so the next collection can retry.
+If no pid was ever observed,
+native logs cannot be attributed to the app.
+PID-based logcat cannot distinguish historical reuse of an exited pid.
+Queries use bounded logcat -d -v epoch -T <epoch> --pid <pid> output, a ten-second
+budget, a persisted checkpoint and five-second overlap to deduplicate records.
+Logcat retains a finite buffer; records already evicted or persisted beyond the
+overlap may be unavailable. An oversized query retries the recent tail and writes
+a device warning naming any dropped interval. Followers share a child-aware log
+claim; install and stop cancel and settle the worker before native operations.
+Stop copies logs before and after the host's final collection and teardown, with
+each client drain bounded to 30 seconds and progress on stderr. Collected logs
+remain readable after stop. The host advertises hosted-android-data for Android
+handoff and native logs. Older hosts get a newer stim-server note, use upload
+and show records already copied here.`
+		},
+		"hosted-ios": {
+			summary: "iOS on a named approved Mac: strict placement, private Metro, status and stop",
+			body: () => `IOS ON A HOSTING MAC
 
 If Stim is not installed globally, replace stim with npx stim.
 
@@ -4671,9 +4954,36 @@ If Stim is not installed globally, replace stim with npx stim.
 The same setup serves macos --remote. Approval is separate from build, read
 and phone control. Set ios.remote to the machine name for a workspace default;
 no flag or setting runs here. eas and proxy keep their remote backend meanings.
-auto is accepted but refuses with STIM_BAD_ARG until automatic placement ships.
-Android --remote <machine> refuses with STIM_BAD_ARG: Android on a paired Mac
-is not available yet.
+--remote auto (or ios.remote = auto / android.remote = auto) stays here when
+there is a free concurrency.maxDevices slot (0 means unlimited), no device
+waiter ahead, normal host memory pressure, no budget shortfall,
+and 5-minute load per core below offload.maxLoadPerCore. Without hosting.machines,
+auto is local. An unknown local device count also stays local; boot admission
+still decides. The default without a flag or setting stays local.
+
+Otherwise Stim asks every approved hosting.machines host in parallel, with a
+3-second probe timeout and this run's model/runtime or image/profile selectors.
+A compatible choice, no declined reason, normal memory pressure and available
+capacity are required. With a free local slot, a host must report a lower load;
+with a full cap or a queue ahead, an admitted host with unknown load is allowed.
+Hosts rank by the build preference (flag > STIM_OFFLOAD_MACHINE > offload.machine)
+when it names a machine, then lowest load, most free memory and hosting.machines order. Automatic build
+offload resolves later, after the device architecture is known.
+
+When no host admits, auto runs here and may wait in the existing FIFO device
+slot queue; --no-wait and --wait 0 refuse with STIM_AT_CAPACITY. The placement
+line explains the decision and the skipped hosts. JSON progress goes to stderr.
+A recorded hosted session wins over load; a live local owned slot stays here.
+A stopped recorded session places again; unreachable or unknown sessions refuse.
+
+A reserve refusal after a successful offer can race with another run. It fails
+with STIM_HOSTING_REFUSED naming the host and asking to retry. Stim does not
+try the next host or local placement after the build has targeted that host's
+architecture, and never falls back once a hosted session exists. A named machine remains strict. --device
+cannot combine with auto. eas/proxy and macOS placement are unchanged.
+--simulator-app is honoured locally with auto and ignored with a note on a host.
+Placement measures budgets without reclaiming; only a new local run reclaims.
+Android --remote <machine> uses an owned emulator on that Mac; see hosted-android.
 
 A named Mac is strict: STIM_HOSTING_REFUSED names its reason; nothing boots
 here or elsewhere. --device cannot use a hosting Mac, and --simulator-app
@@ -4683,6 +4993,24 @@ refuses. The host boots headless and ignores this Mac's iosSimulatorApp setting.
 the offered simulator architecture, not this Mac's. --build-machine remains
 independent and selects a compatible build worker for a Debug cache miss.
 
+The host's own owned devices count toward concurrency.maxDevices.
+
+The host's person sees Hosted here rows in stim-server devices; --json adds
+hostedSessions beside devices. Rows show client, platform, device, installed
+app, state and since, newest first. Plain stopped sessions are omitted;
+parked and unknown sessions stay visible, with parked rows using the parking
+time. An unowned active session reads unknown on this server.
+Loopback device-host.sessions takes no params or {} and returns { sessions };
+rows carry id, client { id, name }, platform, device and app (nullable), state,
+parked, since (ISO), and workspace. device-host.sessions.stop takes { session }
+and returns { id, state: stopping | stopped }, stopping any client's session
+through the existing stop path. Both require an authenticated local Desktop
+control connection; read-only local connections, phones and tailnet clients
+get forbidden. An absent session id gets unknown-session; stopped is
+idempotent. The approved-client device-host.stop still stops only its own
+sessions.
+
+
 Stim builds or fetches before reserving, records the session immediately, then
 uploads the app on every run. Debug keeps Metro here; its supervisor owns a
 private gateway bound to this Mac's Tailscale address, pinned to the host peer
@@ -4703,10 +5031,12 @@ agent, state } per slot. A shutdown local simulator is replaced in status; a
 booted or unknown local simulator stays visible alongside ios.host with a warning.
 The default slot appears only in ios, never in slots[]. No host UDID or gateway secret enters local device state or
 status. Ready is normal; stopped has a rerun hint; unknown or unreachable is
-unverified. A host server restart stops its sessions.
+unverified. A clean host server restart stops its sessions and retains eligible
+parked devices. A running session left by a crash stays unknown until explicit
+stop; the restarted server never re-attaches to a booted device.
 
-stop and worktree remove wait for the host to stop, delete exactly its owned
-simulator without parking, close the gateway and clear placement. stop --json
+stop and worktree remove wait for the host to stop, park its eligible owned
+simulator within pool.iosParkedMax (delete otherwise), close the gateway and clear placement. stop --json
 reports each hosted slot under outcomes.device["ios:host:<slot>"], retaining
 local device outcomes and successful siblings when another slot fails. Revoked or
 missing sessions clear placement too. An unreachable host retains placement
@@ -4725,18 +5055,47 @@ ran on the hosting Mac's pinned node, it takes matching files from that build.
 A refused or timed-out handoff falls back to upload, retrying a still-busy host
 for at most one minute.
 
+HOSTED PARKING
+
+The host reads pool.iosParkedMax and pool.androidParkedMax from its own home,
+with STIM_POOL_IOS_PARKED_MAX and STIM_POOL_ANDROID_PARKED_MAX overrides.
+Each platform has a separate hosted limit across all clients; 0 disables parking.
+With STIM_HOME set, parking requires the explicit platform environment override.
+Only healthy devices of still-approved clients are parked. The journal reports
+stopped to clients, and the device stays ledger-owned in its session's private
+home, outside the host's local parked pool. Parked devices persist across a clean
+stim-server restart.
+
+A new reserve adopts the oldest compatible parked device of the same client.
+iOS matches resolved device type, runtime and architecture; Android matches
+system image, device profile and architecture. Adoption clears app data by
+removing every third-party app; iOS also resets privacy and keychain. Parking and
+adoption remove session app copies but keep the content-addressed upload store,
+so the first run after adoption uploads only changed files. Devices are never reused across clients.
+The oldest parked devices beyond the host's platform limit are deleted through
+owned-device teardown, also after a limit decrease. Adoption-time reconciliation
+retires missing, renamed, running or unowned candidates; failed retirement keeps
+the record. Revocation retires that client's parked devices.
+On the hosting Mac, unscoped \`stim gc\` lists parked hosted devices and
+\`stim gc --delete\` deletes them through their session homes under a session
+claim. Held claims and unverified ownership keep the device. Android deletion
+requires visibility from this shell's Android environment; otherwise run gc with
+the server's ANDROID_AVD_HOME/HOME. Records no longer listed in their session
+ledger are already removed and skipped. Reconciliation
+clears its parked marker after the session ledger becomes empty.
+
 stim logs and stim logs --errors pull native device records from bounded host
 queries. Concurrent followers share a collection, throttled per session, without
 blocking app delivery, viewing or control. Stop limits each log drain to 30 seconds with
 progress on stderr and a no-progress guard. The host collects a bounded final
-tail before deletion, including on revocation or server close; stop copies it
+tail before parking or deletion, including on revocation or server close; stop copies it
 back afterwards. If the final collection drops a backlog interval and eventually
 succeeds, a device warning record names that interval. A damaged collection checkpoint is ignored and
 rebuilt; it never blocks reading collected records. The client waits up to
 180 seconds for stop. The final collection and worker termination paths fit within
 that wait; an in-flight handoff copy and closing Metro or view transports are
 outside those worker bounds.
-Collected records remain in the session home after deletion;
+Collected records remain in the session home after parking or deletion;
 app blobs and materialized bundles are removed. Native queries read persisted
 entries, overlap by five seconds and de-duplicate; info-level or later-persisted
 entries may be unavailable. JavaScript logs arrive through Metro.
@@ -4811,10 +5170,10 @@ frames cannot arrive. Replay, duoFrame and physical targets are refused for
 hosted subscriptions. Desktop hides local Simulator.app, rotation, hardware
 buttons and simulator options; touch and text use the relay. The phone can also
 send the host's supported button, rotation and posture inputs.`
-			},
-			eas: {
-				summary: "download a matching EAS development build; explicit profile, costs, cache and miss remedies",
-				body: () => `EAS DEVELOPMENT BUILDS
+		},
+		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
@@ -4890,10 +5249,10 @@ 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.
@@ -4953,10 +5312,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
@@ -4986,10 +5345,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
@@ -5137,10 +5496,10 @@ result as proof instead of requiring an unrelated screenshot.`
   until it returns; the next heartbeat then lands on the grid, which is why an
   elapsed value can jump. Read the phase lines, not the wall clock, before
   killing a run.`
-			},
-			pool: {
-				summary: "parked and adopted simulators and emulators: what park and adoption clear or keep, the model and runtime match, emulator storage, gc erase",
-				body: () => `  THE SIMULATOR POOL
+		},
+		pool: {
+			summary: "parked and adopted simulators and emulators: what park and adoption clear or keep, the model and runtime match, emulator storage, gc erase",
+			body: () => `  THE SIMULATOR POOL
   \`worktree remove\` PARKS this workspace's owned simulator instead of
   deleting it, and the next workspace that wants the same model and runtime
   ADOPTS it. Adoption reuses the simulator and the app installed on it, but
@@ -5312,10 +5671,10 @@ result as proof instead of requiring an unrelated screenshot.`
   reports their system image, hardware profile, age, recorded app and disk
   size.
 `
-			},
-			builds: {
-				summary: "optional cache warm-up, build optimizations, fingerprints, .fingerprintignore, install unchanged, running app restart, runtime state",
-				body: () => `OPTIONAL CACHE WARM-UP FOR REPEATED NATIVE WORK
+		},
+		builds: {
+			summary: "optional cache warm-up, build optimizations, fingerprints, .fingerprintignore, install unchanged, running app restart, runtime state",
+			body: () => `OPTIONAL CACHE WARM-UP FOR REPEATED NATIVE WORK
   When several native worktrees are coming, build the source checkout once to
   seed the shared caches before warming the linked worktrees. Skip this extra
   build for one-off or JavaScript-only work. For local simulator or emulator
@@ -5466,7 +5825,7 @@ with machine or project optimization settings; see \`guide settings\`:
            no org.gradle.caching=true in gradle.properties. Debug builds also
            carry -PreactNativeArchitectures=<target ABI>, using the owned
            emulator system-image ABI or the physical device's primary ABI.
-           Unknown targets and Release builds stay universal.
+           Unknown targets and local Release builds stay universal.
   ccache   the same gradlew run carries an absolute
            CMAKE_C_COMPILER_LAUNCHER / CMAKE_CXX_COMPILER_LAUNCHER plus
            CCACHE_DIR, CCACHE_BASEDIR, CCACHE_NOHASHDIR, CCACHE_SLOPPINESS
@@ -5721,10 +6080,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
@@ -5790,12 +6149,50 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
                             lock does, and a dead builder frees its slot within
                             a poll (process identity, like the lock).
 
-    concurrency.maxDevices  how many Stim-owned devices are BOOTED at once. Checked
-                            at device time, before a sim is created or booted.
-                            At the cap, a NEW device is REFUSED with
-                            STIM_AT_CAPACITY (interactive-shaped: it does not
-                            queue). A workspace whose own device is already
-                            booted is never refused.
+    concurrency.maxDevices  how many Stim-owned devices are BOOTED at once,
+                            counting sims that are booting, emulators adb lists
+                            in any state, and devices other runs are booting.
+                            Admission and the boot claim are taken under one
+                            lock in $STIM_HOME. At the cap, a new owned device
+                            waits in FIFO order across this Stim home, for
+                            600 seconds by default. \`--wait <seconds>\` changes
+                            the bound; \`--no-wait\` or \`--wait 0\` refuses at
+                            once with STIM_AT_CAPACITY and cannot jump queued
+                            runs. A workspace's own booted or booting device
+                            bypasses the queue. iOS waits beside its build.
+                            Waiting prints the count, holder workspace names
+                            and elapsed time at once and about every 10s, then
+                            the queue position, head workspace name and
+                            $STIM_HOME/device-waits path. Timeout names the
+                            same head and path. Stop cancels a queued run and
+                            releases its ticket without booting its device.
+                            Status JSON adds build.waitingFor independently
+                            of phase: { kind: "device-slot" | "build-slot",
+                            inUse, max, since }. Overlapping waits show the
+                            one that started first, then the remaining wait.
+                            Positive deviceSlotWaitMs is recorded beside
+                            slotWaitMs in compiling run placements; every
+                            wait also records a capacityWaits event in stats,
+                            with reclaimed when one or more devices were
+                            shut down for it.
+                            While at the cap, only the queue head reclaims:
+                            it shuts down the longest-idle eligible owned
+                            device in another workspace of this Stim home,
+                            one per attempt, at most once every 15 seconds,
+                            then rechecks queue and capacity.
+                            devices.reclaimIdleMinutes defaults to 10; 0 off.
+                            The waiter's effective setting applies.
+                            Idle checks are the same as supervisor
+                            idle shutdown below: no driver, lock, build,
+                            viewer or recent activity. Physical, hosted,
+                            remote, parked and other homes' devices, and
+                            the waiting workspace itself, are excluded.
+                            Shutdown never deletes. Reclaim failures are
+                            logged and skipped without failing the run.
+                            A listing failure leaves the count unknown and
+                            admission refuses with STIM_NO_DEVICE. Unresolved
+                            wait or boot claims refuse with the claim code
+                            and the command to remove that exact claim.
                             See \`guide errors STIM_AT_CAPACITY\`.
 
   \`stim doctor\` prints one note echoing the caps and the current live count,
@@ -5803,10 +6200,10 @@ 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\`).`
-			},
-			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)
+		},
+		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:
 
@@ -5847,8 +6244,8 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
     4. trim shared cache entries nothing has used for 14 days
        (\`gc --delete --older-than 14\` for the caches)
 
-  IDLE SHUTDOWN (OFF BY DEFAULT): with devices.idleShutdownMinutes set, a
-  workspace's supervisor shuts down that workspace's owned simulators and
+  IDLE SHUTDOWN (30 MINUTES BY DEFAULT): with devices.idleShutdownMinutes above
+  0, a workspace's supervisor shuts down that workspace's owned simulators and
   emulators once they have been idle that long, without waiting for a run
   to go over budget. Idle is step 1 with that many minutes in place of 10:
   booted, no driver, no Stim or agent-device lock, no build in progress, and
@@ -5862,11 +6259,35 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   status\` shows "shut down after 30m idle" on the device until the next
   \`ios\` or \`android\` run boots it again. When metro.idleStopMinutes is
   shorter, the dev server's idle stop first shuts down the devices idle that
-  long, because no supervisor is left to check afterwards. Nothing checks
-  without a supervisor: release runs, and after \`stim stop\`. The setting
-  is read when the supervisor starts. Stim Desktop's simulator view is not a
-  stim-server client and does not count as a viewer. Turn it on with
-  \`stim settings set devices.idleShutdownMinutes 30 --scope machine\`.
+  long, because no supervisor is left to check afterwards. The supervisor
+  path does not check without a supervisor: release runs, and after
+  \`stim stop\`. The setting is read when the supervisor starts. Stim Desktop's simulator view is not a
+  stim-server client and does not count as a viewer. Change it with
+  \`stim settings set devices.idleShutdownMinutes <minutes> --scope machine\`;
+  0 turns it off, and an explicit 0 stays 0.
+
+  QUEUE RECLAIM (10 MINUTES BY DEFAULT): a run waiting at concurrency.maxDevices
+  uses devices.reclaimIdleMinutes from its own effective workspace settings.
+  Only the FIFO head shuts down the longest-idle eligible device across this
+  Stim home's other workspaces, one per attempt, at most once every 15 seconds,
+  rechecking capacity before another. 0 disables it. The supervisor's own idle
+  shutdown defaults to 30 minutes.
+  Reclaim uses the same idle check: no driver, Stim or agent-device lock,
+  build, device lock or viewer, and no Stim command, app or device log,
+  Metro bundle or agent action within that interval. It rechecks under the
+  target workspace's native-run lock and re-resolves ownership in centralized
+  teardown. It shuts down, never deletes, and excludes the waiting workspace,
+  physical, hosted, remote, parked and other homes' devices. Failed locks or
+  teardown are reported once per device and skipped for the rest of the wait.
+  Progress on stderr names the reclaimed
+  device and workspace; the target's status and device_idle_shutdown log
+  record "reclaimed for a waiting run", and the wait's stats carry reclaimed.
+  Any workspace of this Stim home with a device idle for
+  devices.reclaimIdleMinutes is eligible, even with no supervisor and even
+  when its own devices.idleShutdownMinutes is 0. Stim Desktop's simulator view
+  and manual input in Simulator.app do not count as activity.
+  \`stim settings set devices.reclaimIdleMinutes 0 --scope machine\` opts out
+  machine-wide; the waiter's effective setting decides.
 
   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
@@ -5881,13 +6302,18 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   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
+		},
+		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             --build-machine <auto|local|name> --slot <name> --json --plan --no-metro-check --no-build-cache --scheme <name> --configuration <name> --device-type <name> --runtime <version> --simulator-app <xcode|siniulator|stim-desktop> --device [udid] --wait <seconds> --no-wait --remote <eas|proxy|auto|machine>
   android         --build-machine <auto|local|name> --slot <name> --json --plan --no-metro-check --no-build-cache --variant <name> --system-image <id> --device-profile <id> --device [serial] --wait <seconds> --no-wait --remote <proxy|eas>
+  ios/android --wait bounds owned-device slot waits (default 600s), or physical
+  leases with --device (default 60s). Remote targets do not join this local
+  slot queue. --no-wait refuses a full/queued owned
+  slot at once; its existing physical lease bypass is unchanged.
+
   reload          [ios|android] --json
   device          lock <ios|android> [id] --slot <name> --for <duration> --wait <seconds> --json;
                   unlock [ios|android] --slot <name> --json
@@ -6140,9 +6566,9 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   A named hosting Mac uses both selectors and its installed choices instead;
   an unavailable choice is STIM_HOSTING_REFUSED. See hosted-ios.
   \`android --system-image\` and \`--device-profile\` refuse with
-  STIM_BAD_ARG on every remote run (\`--remote\` or the android.remote
-  setting), and a remote run ignores android.systemImage and
-  android.deviceProfile.
+  STIM_BAD_ARG on eas/proxy runs (\`--remote\` or the android.remote
+  setting), which ignore android.systemImage and android.deviceProfile.
+  A named hosting Mac honors both selectors; see hosted-android.
 
   These flags describe a device that does not exist yet. When this workspace
   ALREADY owns a simulator and \`--device-type\` names a different model, or
@@ -6164,10 +6590,10 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   The --json payload reports what was actually used: \`deviceType\` and
   \`runtime\` on iOS, \`systemImage\` and \`deviceProfile\` 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.
@@ -6306,10 +6732,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
@@ -6334,8 +6760,9 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   holder's running app, a different one means the launch only backgrounds it,
   and when Stim cannot read the holder's app id it says so rather than
   guessing. A free device is leased as usual under \`--no-wait\`. The two flags
-  together are STIM_BAD_ARG, and so is either one without \`--device\`, because
-  an owned simulator or emulator has no contention.
+  together are STIM_BAD_ARG. Without \`--device\`, they instead bound the
+  FIFO owned-device slot wait (default 600s); \`--no-wait\` refuses at once
+  when the cap is full or another run is queued. See \`guide lifecycle concurrency\`.
 
   A successful \`--device\` run reports \`lease: { kind, expiresAt }\` in its
   \`--json\`; a run that proceeded without one, or lost one after the install,
@@ -6411,10 +6838,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
@@ -6499,10 +6926,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.
@@ -6579,12 +7006,14 @@ HOST MEMORY PRESSURE AND STALLED SIMULATORS
   Rebooting a simulator under the same pressure
   can repeat the stall. Consider fewer concurrent builds/devices (guide lifecycle
   concurrency) and a reviewed SimSlim profile for future runs.`
-			}
 		}
-	},
-	cleanup: {
-		summary: "Where simulators come from, and how they get reclaimed",
-		preamble: () => `DEVICE SLOTS
+	}
+};
+//#endregion
+//#region src/guide/cleanup.ts
+const cleanup = {
+	summary: "Where simulators come from, and how they get reclaimed",
+	preamble: () => `DEVICE SLOTS
 
 Cleanup enumerates every slot. stop --slot <name> keeps the shared server and
 other slots; plain stop and worktree remove handle the whole workspace.
@@ -6595,7 +7024,7 @@ versions cannot reliably manage their assignments.
 
 ARCHIVE
 
-Linked-worktree removal and gc dead-project pruning keep history under
+Worktree removal and gc dead-project pruning keep history under
 $STIM_HOME/archive by default. See stim guide cleanup archive.
 
 MAINTENANCE
@@ -6711,20 +7140,27 @@ 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: {
-			archive: {
-				summary: "retained workspace history and explicit archive cleanup",
-				body: () => `ARCHIVE
-  Linked-worktree removal and gc pruning a registered root that is gone keep
+	sections: {
+		archive: {
+			summary: "retained workspace history and explicit archive cleanup",
+			body: () => `ARCHIVE
+  Worktree removal, including the environment reclaim of a source checkout, and
+  gc pruning a registered root that is gone keep
   state, ended agents, the error index, logs, closed recording segments and
   workspace-local agent-device sessions under $STIM_HOME/archive.
   Build outputs and open recording segments are deleted with the workspace.
   Archives have no checkout, devices, ports or running processes. A recreated
   path starts fresh; status links its earlier archives with replacedBy.
   Paired clients with read can select archived[].id with archive instead of
-  workspace for server log queries and replay. Archived log subscriptions send
-  retained records, then logs-ended. Archived frame subscriptions need at and
-  cannot be physical or go live. Replay ranges report recording disabled.
+  workspace for server log queries and replay.
+  archive.detail takes { archive: id } and returns { builds, recordings }:
+  live-shaped iOS/Android build history and { platform, slot, spans } for every
+  retained recording slot with spans. Missing state gives builds {}; no footage
+  gives recordings []. status keeps archive build summaries.
+  Older servers refuse archive.detail with unknown-method.
+  Archived log subscriptions send retained records, then logs-ended.
+  Archived frame subscriptions need at and cannot be physical or go live.
+  Replay ranges report recording disabled.
   Reads stay on this Mac.
   An updated server is required; older servers refuse with bad-request when
   workspace is omitted. There is no CLI archive log flag.
@@ -6758,10 +7194,23 @@ to stats.json.corrupt-<unix ms> and starts a new one.`,
   Directories are 0700 and files 0600. No redaction is applied; logs and agent
   actions can contain secrets. Use archive.enabled false for a sensitive repo.
   Archived logs and replay are not exposed through CLI or app readers yet.`
-			},
-			gc: {
-				summary: "what gc and worktree remove delete, keep and refuse: orphans, stale records, locks, leases, EAS sessions",
-				body: () => `AGENT-DEVICE (REPORT ONLY)
+		},
+		gc: {
+			summary: "what gc and worktree remove delete, keep and refuse: orphans, stale records, locks, leases, EAS sessions",
+			body: () => `PARKED HOSTED DEVICES
+On a hosting Mac, unscoped gc lists parked hosted iOS/Android devices by session,
+client id, device label, parked time and private-home ledger ownership.
+gc --delete takes each session claim and deletes through the packaged stop worker
+in that session's home; held claims, changed sessions and unverified ownership
+keep the device. Android deletion also requires the AVD to be visible from this
+shell; otherwise run gc with the server's ANDROID_AVD_HOME/HOME. Devices no longer
+listed in their session ledger are already removed and skipped. An unreadable
+journal keeps every hosted device. --older-than
+filters by parked time; --cache scopes omit hosted sessions. The CLI never writes
+the server journal: stim-server reconciliation clears the parked marker after
+successful deletion leaves the session ledger empty.
+
+AGENT-DEVICE (REPORT ONLY)
 Unscoped gc reports agent-device runner builds by platform and entry, last use,
 agent-device and Xcode versions, sessions, logs, other state, workspace state
 and hosted driver state. Stim never selects this state as a cache.
@@ -6806,7 +7255,9 @@ IN USE
   that names no workspace blocks nothing, because every build also holds its
   own workspace's native-run.lock; gc lists it with the command that removes
   it. \`worktree remove\` re-checks uncommitted and unpushed work under its
-  removal locks, just before it reclaims anything. A project root whose
+  removal locks, just before it reclaims anything. It refuses, even with
+  --force, a worktree that an installed stim-server service runs from
+  (STIM_WORKTREE_SERVICE; see guide errors). A project root whose
   existence cannot be read (a permission error) is never treated as deleted.
 
 SWEEPING FINISHED WORKTREES
@@ -6955,10 +7406,18 @@ ON THE SOURCE CHECKOUT
   (including nested monorepo app dirs) dropped, and the global workspace
   directory deleted. The tree itself is never touched, which is also why the
   dirty-tree and unpushed guards do not apply on that path.
+  Run from the checkout root it reclaims every registered project under the
+  checkout. Run from a subfolder (for example apps/mobile) it reclaims only
+  the nearest registered project at or above that folder and the projects nested
+  under it, leaves the other
+  projects' devices, ports and records alone, and refuses with exit 1 when no
+  project is registered at or above it.
   It ends with:
     Reclaimed the environment; the working tree stays (it is the source checkout).
   A registered project directory that is not a git repo at all gets the same
   environment reclaim -- there is nothing else remove could mean there.
+  Either reclaim archives each workspace it removes, as removal of a linked
+  worktree does.
 
 The delete paths and \`stop\` do not check simulator occupancy. An explicit
 \`stim stop\` shuts down this workspace's Stim-owned simulator, including a
@@ -7074,10 +7533,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,
@@ -7131,10 +7590,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.`
-			},
-			memory: {
-				summary: "watchman and Gradle and Kotlin daemon memory in gc, and when gc --delete --cache watchman or gradle-daemons stops them",
-				body: () => `MEMORY
+		},
+		memory: {
+			summary: "watchman and Gradle and Kotlin daemon memory in gc, and when gc --delete --cache watchman or gradle-daemons stops them",
+			body: () => `MEMORY
   Every \`gc\` without --cache, and \`gc --cache watchman\` or
   \`gc --cache gradle-daemons\`, reports the long-lived helpers that grow while
   they run: the shared watchman daemon, Gradle daemons and Kotlin compile
@@ -7187,10 +7646,10 @@ THE ONE CASE GC WILL NOT REAP
   --older-than does not apply to these kinds and is refused with
   STIM_BAD_ARG. With STIM_HOME set, gc skips them: they are machine-global.
   \`stim doctor\` notes a watchman footprint over 2 GiB.`
-			},
-			disk: {
-				summary: "disk usage, workspace build outputs, logs and device recordings, AVD and build-log sizes, the data partition, trimming the shared caches",
-				body: () => `DISK
+		},
+		disk: {
+			summary: "disk usage, workspace build outputs, logs and device recordings, AVD and build-log sizes, the data partition, trimming the shared caches",
+			body: () => `DISK
   Logs, state, pidfiles and Xcode DerivedData are under the global workspace
   directory, and \`worktree remove\` reclaims them. \`gc --delete\` clears the
   build outputs of workspaces nobody is using (WORKSPACE BUILD OUTPUTS
@@ -7331,12 +7790,14 @@ SHARED BUILD CACHES
 
   Trim rather than empty. Emptying costs the next build in every project the
   time the cache was saving.`
-			}
 		}
-	},
-	settings: {
-		summary: "Settings Stim reads, and where they can live",
-		body: () => `SETTINGS
+	}
+};
+//#endregion
+//#region src/guide/settings.ts
+var settings_default = {
+	summary: "Settings Stim reads, and where they can live",
+	body: () => `SETTINGS
 
 Settings are JSON: machine layers in ~/.stim/config.json and a committed
 .stim.json. Command-line selectors override their matching settings.
@@ -7379,8 +7840,8 @@ Resolution order, first match wins:
   3. committed       .stim.json beside the app's package.json or Package.swift
   4. machine         ~/.stim/config.json, top-level optimizations,
                      ios.deviceType, ios.runtime, android.systemImage,
-                     android.deviceProfile and devices.idleShutdownMinutes
-                     and archive.enabled
+                     android.deviceProfile, devices.idleShutdownMinutes,
+                     devices.reclaimIdleMinutes and archive.enabled
   5. Stim default
 An environment override, where a setting has one, wins over every layer.
 
@@ -7440,8 +7901,8 @@ KEYS STIM READS
                         flag overrides this per invocation. Unset means Debug.
   ios.remote            "proxy", "eas", or a named approved Mac from
                         hosting.machines, with the same meaning as --remote.
-                        "auto" is accepted but refuses until automatic placement
-                        ships. Unset runs here. See lifecycle hosted-ios.
+                        "auto" places on an approved Mac when this Mac is full or
+                        busy. Unset runs here. See lifecycle hosted-ios.
   ios.simslimProfile    a SimSlim JSON profile under the app directory,
                         at most 64 KiB. Install the
                         external tool once with
@@ -7581,7 +8042,10 @@ ${ANDROID_AVD_CONFIG_HELP.map((line) => `                          ${line}`).joi
                         committed .stim.json avoids carrying a secret; a
                         bare string is used as the literal password. Unset
                         means the debug keystore's fixed "android".
-  android.remote        "proxy" or "eas"; the Android half of ios.remote
+  android.remote        "proxy", "eas", or a named approved Mac in
+                        hosting.machines; "auto" places on an approved Mac when
+                        this Mac is full or busy. Unset runs here.
+                        See lifecycle hosted-android.
   metro.tunnel          selects how a remote device reaches this workspace's
                         Metro after remote intent exists. Plain \`start\` stays
                         local. For Expo and bare React Native, "auto" (default)
@@ -7652,9 +8116,17 @@ ${ANDROID_AVD_CONFIG_HELP.map((line) => `                          ${line}`).joi
                         minutes an owned simulator or emulator stays idle
                         (\`gc --idle\` conditions; an open stim-server viewer
                         counts as activity) before its workspace's supervisor
-                        shuts it down, never deletes it. Default 0, never.
+                        shuts it down, never deletes it. Default 30; 0 never.
                         Machine or project layers. Read when the supervisor
                         starts; see \`guide lifecycle budget\`.
+  devices.reclaimIdleMinutes
+                        minutes idle before the head of the device slot queue
+                        shuts down the longest-idle eligible owned device in
+                        another workspace of this Stim home. Default 10; 0 off.
+                        Machine or project layers, resolved for the waiting
+                        workspace on each poll. Same idle checks as supervisor
+                        shutdown, one device per poll, never deleted. See
+                        \`guide lifecycle concurrency\`.
   macos.product         the explicit Swift Package executable product built in
                         Debug by stim macos
   macos.infoPlist       development Info.plist relative to Package.swift,
@@ -7722,7 +8194,8 @@ ${ANDROID_AVD_CONFIG_HELP.map((line) => `                          ${line}`).joi
                         them from the environment or the machine layers.
 
 Each setting takes its documented type: string, array of strings, number,
-boolean, or object. android.remote, metro.tunnel, web.viewport,
+boolean, or object. ios.remote and android.remote accept backend names or
+tailnet machine names. metro.tunnel, web.viewport,
 optimizations.android.compilerCache and optimizations.android.pch take only
 their listed choices. A value of the wrong
 type or outside those choices is refused by name on every command that resolves
@@ -7878,6 +8351,13 @@ platform bounds. Android adoption matches the system image and AVD creation
 settings, preserves the APK, and clears app data before launch. See
 \`guide lifecycle pool\` for cleanup and the system state that remains.
 
+The host also uses these bounds for hosted iOS and Android parking on stop,
+separately from its local pool and across all hosted clients per platform.
+It adopts only a compatible device of the same client, clears app data and
+removes other apps. Parked devices persist across a clean stim-server restart;
+eviction, adoption-time reconciliation and revocation delete them through
+owned-device teardown. See guide lifecycle hosted-ios.
+
 When STIM_HOME is set, parking and adoption are OFF unless
 the corresponding STIM_POOL_IOS_PARKED_MAX or STIM_POOL_ANDROID_PARKED_MAX
 is set too. A redirected home is a scoped config --
@@ -7896,6 +8376,15 @@ ticket; matching hashes and approved credentials are preserved.
 Approved doctor entries under buildMachines and deviceHosts include host
 { name, screenRecording, accessibility } when the worker reports it.
 
+BUILD MACHINES AND PHONE APP
+When the user mentions slow builds, a busy Mac, a full disk or device limit, or
+wanting updates away from the desk, tell them about Stim Desktop > Settings >
+Build machines > Add (a Mac on the tailnet that builds or hosts simulators for
+this one) or Phones > Pair a Phone (the Stim phone app). Stim Desktop also
+suggests these itself, at most once a day and never during a build. Agents only
+tell the user: they never run \`stim-server setup\`, never edit \`offload.*\` or
+\`hosting.*\` for the user, and never approve requests.
+
 HOSTING MACHINES ARE MACHINE-LEVEL
 \`hosting.machines\` names Macs that may host owned simulator sessions,
 by MagicDNS name with an optional serve port (default 7443). Name each node
@@ -7915,9 +8404,22 @@ unless every chosen capability already has a matching approval. Desktop reuse
 requires an existing tailnet route. Ctrl-C or SIGTERM completes the journal,
 releases the setup claim and exits 1; a typed N also exits 1. Hosting grants
 include no read, control or build capability.
+On the hosting Mac, Stim Desktop > Settings > Phones > Hosted here lists the
+simulators, emulators and apps approved Macs run there, below Device hosting
+approvals. Stop asks for confirmation, ends the session and deletes or parks
+its device on that Mac. Parked sessions remain listed without Stop. The list
+refreshes every five seconds and stays hidden when the local server does not
+support it.
 $STIM_HOME/device-host-machines.json stores a private token and pinned tailnet
 node. Doctor never prints the token; it reports each machine under deviceHosts
-in JSON. Stim sends tokens only to the pinned node's own tailnet address,
+in JSON. Desktop uses placement set by config or agents, such as
+stim settings set ios.remote auto --scope workspace (or android.remote),
+or per run stim ios --remote auto / stim ios --remote <machine>.
+New Desktop runs pass no --remote flag; recorded hosted sessions keep their
+machine until stim stop. Only devices outside this Mac show "on <machine>"
+on tiles, workspace pages, viewer toolbars and sidebar rows, with the reason
+as hover text.
+Stim sends tokens only to the pinned node's own tailnet address,
 with its MagicDNS name for TLS and Host routing. A changed node refuses
 access, and uncertain replies or unreadable credentials preserve the pin.
 Invalid hosting settings report an error and preserve every saved credential.
@@ -7933,14 +8435,16 @@ Access (Accessibility on macOS 26 and earlier) for Stim Host, the app
 \`stim-server service install\` runs the server under.
 
 On a hosting Mac, \`hosting.agentDriver\` names the tool it starts so a
-client's coding agent can drive the macOS apps and iOS simulators it hosts for that client.
+client's coding agent can drive the macOS apps, iOS simulators and Android emulators it hosts for that client.
 The default, \`none\`, starts nothing. For macOS, \`agent-device\` starts its
 shared daemon only when that agent-device can lease a single app (its
 \`macos-app\` lease backend); otherwise agent control reports \`none\` with a
 notice, and no client is handed the Mac's desktop. STIM_AGENT_DEVICE_BIN in
 stim-server's environment names an agent-device binary to use instead of
 ~/.local/bin/agent-device. Hosted iOS uses one daemon per simulator, pinned by
-its UDID policy; both Macs need agent-device 0.21.20 or later. See guide lifecycle
+its UDID policy; both Macs need agent-device 0.21.20 or later. Hosted Android
+uses one daemon per emulator, pinned by its serial policy, with agent-device
+0.21.22 or later on both Macs. See guide lifecycle
 hosted-ios. \`doctor\` on that Mac notes an installed hosted app that runs while
 the setting is \`none\`.
 
@@ -8019,7 +8523,8 @@ emulator debug build or a stim macos SwiftPM Debug build compiles:
 Load per core is the 5-minute load average divided by the CPU count; a Mac's
 native builds are its Stim runs in prebuild, pods or compile on that Mac, not
 the ones it offloaded.
-\`offload.maxLoadPerCore\` (default 2) is the load per core at which a Mac
+\`offload.maxLoadPerCore\` (default 2) is also the busy threshold for
+automatic iOS and Android device placement. It is the load per core at which a Mac
 counts as saturated, both here and on a build machine.
 
 STIM_OFFLOAD_MODE overrides it for one command. Device, Release and
@@ -8170,7 +8675,7 @@ be setup steps are supplied by Stim on the command lines it composes itself:
                gradle.properties. Debug builds add
                -PreactNativeArchitectures=<target ABI> when the owned
                emulator system image or physical device proves the ABI;
-               unknown targets and Release builds stay universal. The same run
+               unknown targets and local Release builds stay universal. The same run
                carries the ccache launcher and CCACHE_BASEDIR /
                CCACHE_NOHASHDIR when ccache is on PATH -- so no
                externalNativeBuild cmake arguments in a committed
@@ -8284,8 +8789,8 @@ The example shows the defaults. Full setting names and behavior:
   optimizations.android.gradleBuildCache
     false passes --no-build-cache to Gradle, overriding org.gradle.caching=true.
   optimizations.android.targetAbiOnly
-    false stops narrowing Debug builds to the device ABI. Release is always
-    universal; project ABI filters still apply.
+    false stops narrowing Debug and hosted Android builds to the device ABI.
+    Local Release builds are universal; project ABI filters still apply.
 
 Android CAS, explicit PCH modes, and changed iOS compiler options use separate
 native artifact keys. Android ccache and none share an artifact key when their
@@ -8383,10 +8888,12 @@ platform instead of one entry. Pass prune: 'atomic' for a cache whose index
 references its own data (an LLVM CAS): it is then left alone by --older-than
 and emptied whole only by 'gc --delete --cache all'.
 Registration is idempotent and keyed on the directory.`
-	},
-	web: {
-		summary: "stim web: an owned headless Chrome per workspace, its logs, launched, and teardown",
-		body: () => `WEB: AN OWNED CHROME PER WORKSPACE
+};
+//#endregion
+//#region src/guide/web.ts
+var web_default = {
+	summary: "stim web: an owned headless Chrome per workspace, its logs, launched, and teardown",
+	body: () => `WEB: AN OWNED CHROME PER WORKSPACE
 
 If Stim is not installed globally, replace stim with npx stim.
 
@@ -8604,10 +9111,12 @@ LIMITS
 
 Chrome and Chromium only. The owned page is one tab: a page the app opens in
 a new window is not captured.`
-	},
-	macos: {
-		summary: "Swift Package macOS Debug apps: owned bundle, logs, local window viewing, and --remote on another Mac",
-		body: () => `MACOS: SWIFT PACKAGE DEVELOPMENT PROTOTYPE
+};
+//#endregion
+//#region src/guide/macos.ts
+var macos_default = {
+	summary: "Swift Package macOS Debug apps: owned bundle, logs, local window viewing, and --remote on another Mac",
+	body: () => `MACOS: SWIFT PACKAGE DEVELOPMENT PROTOTYPE
 
 If Stim is not installed globally, replace stim with npx stim.
 
@@ -8700,6 +9209,33 @@ carries buildMachine (selected) and builtOn (here or the machine, absent until
 a build runs), and errorCode on a typed failure. It carries offloadedTo only for a remote build, and offloadFallback when an offload
 attempt falls back here. Placement and failure reasons are in build logs.
 
+AGENT ACTIONS
+
+Launch through stim macos first. Use its isolated bundleId from the JSON
+launch record or status --json:
+
+  agent-device open <bundleId> --platform macos --surface app --foreground
+  agent-device click <ref> --settle
+  stim logs --source agent
+
+Stim reads agent-device's recorded app-scoped actions and failures into the
+native workspace's agent feed in Desktop and the phone viewer. Text stays
+redacted by agent-device. Matching uses the workspace-specific bundle ID and
+the current launch's start time; open/close attempts, app switches and event
+log rotation clear the binding. Open must explicitly include --surface app:
+agent-device can otherwise inherit a previous desktop or menubar surface.
+An unrecorded open needs a new recorded app open before actions appear.
+Native screenshot events are omitted because their surface override is not
+recorded. Generic computer-use tools and phone Control are not agent-device
+actions. Manually duplicated bundles sharing the isolated identifier are
+unsupported; leave app launch and stop to Stim. No native replay is added.
+The feed requires agent-device to record the explicit surface in its open
+event. agent-device 0.21.23 is the minimum; older versions such as 0.21.12 omit
+it, so native actions remain unavailable with them. Stim does not infer the
+surface from the bundle ID. Actions are attributed only while the launch is
+recorded as running: after the app exits or is relaunched, earlier launches'
+actions are no longer returned, and a failed open is not shown.
+
 OWNERSHIP AND LOCAL VIEWING
 
 The supervisor owns a process-identity claim with the app as its child. Stop
@@ -8939,6 +9475,8 @@ script such as mini-desktop.sh use these instead:
   3 concurrent slots         concurrency.maxDevices on the host; one bundle id
                              slot per session
 
+The host's own owned devices count toward concurrency.maxDevices.
+
 The agent-device rows work once the host's agent field names agent-device.
 
 DESKTOP DOGFOOD
@@ -8965,6 +9503,565 @@ development Info.plist for stim macos. Build and show its owned window in Stim
 Desktop, verify a source edit and readable failed-build logs, then stop only
 this workspace's app. Do not change permissions or use custom build scripts."
 `
+};
+//#endregion
+//#region src/guide/tutorial-data.ts
+const TUTORIAL_PINS = {
+	createExpoApp: "5.0.0",
+	template: "expo-template-blank@58.0.15"
+};
+const TUTORIAL_FILES = {
+	"App.js": `import { useEffect, useState } from 'react';
+import { Pressable, StyleSheet, Text, View } from 'react-native';
+import { StatusBar } from 'expo-status-bar';
+import { TITLE_COLOR } from './theme';
+
+const TAG = '[stim:tutorial]';
+
+function Button({ label, onPress }) {
+  return (
+    <Pressable accessibilityRole="button" onPress={onPress} style={styles.button}>
+      <Text style={styles.buttonText}>{label}</Text>
+    </Pressable>
+  );
+}
+
+export default function App() {
+  const [note, setNote] = useState('');
+
+  useEffect(() => {
+    console.log(\`\${TAG} title color=\${TITLE_COLOR}\`);
+  }, [TITLE_COLOR]);
+
+  const logError = () => {
+    console.error(\`\${TAG} error-button test error\`);
+    setNote('Logged an error.');
+  };
+
+  const crash = () => {
+    setTimeout(() => {
+      throw new Error(\`\${TAG} crash-button uncaught test error\`);
+    }, 0);
+  };
+
+  const slowRequest = async () => {
+    const started = Date.now();
+    setNote('Waiting 3 seconds...');
+    await new Promise((resolve) => setTimeout(resolve, 3000));
+    const elapsed = Date.now() - started;
+    console.warn(\`\${TAG} slow-request \${elapsed}ms\`);
+    setNote(\`Slow request took \${elapsed}ms.\`);
+  };
+
+  return (
+    <View style={styles.container}>
+      <Text style={[styles.title, { color: TITLE_COLOR }]}>Stim Tutorial</Text>
+      <Text style={styles.body}>Tap a button, then look at Stim Desktop &gt; Logs.</Text>
+      <Button label="Log an error" onPress={logError} />
+      <Button label="Crash me" onPress={crash} />
+      <Button label="Slow request" onPress={slowRequest} />
+      <Text style={styles.note}>{note}</Text>
+      <StatusBar style="auto" />
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: { flex: 1, backgroundColor: '#fff', alignItems: 'center', justifyContent: 'center', padding: 24 },
+  title: { fontSize: 32, fontWeight: '700', marginBottom: 8 },
+  body: { fontSize: 16, color: '#4b5563', textAlign: 'center', marginBottom: 24 },
+  button: { backgroundColor: '#111827', borderRadius: 10, paddingVertical: 14, paddingHorizontal: 28, marginBottom: 12 },
+  buttonText: { color: '#fff', fontSize: 17, fontWeight: '600' },
+  note: { marginTop: 12, fontSize: 15, color: '#374151' },
+});
+`,
+	"theme.js": `export const TITLE_COLOR = '#1f2937';
+`,
+	"app.json": `{
+  "expo": {
+    "name": "Stim Tutorial",
+    "slug": "stim-tutorial",
+    "version": "1.0.0",
+    "orientation": "portrait",
+    "icon": "./assets/icon.png",
+    "userInterfaceStyle": "light",
+    "ios": {
+      "supportsTablet": true,
+      "bundleIdentifier": "dev.stim.tutorial"
+    },
+    "android": {
+      "adaptiveIcon": {
+        "backgroundColor": "#E6F4FE",
+        "foregroundImage": "./assets/android-icon-foreground.png",
+        "backgroundImage": "./assets/android-icon-background.png",
+        "monochromeImage": "./assets/android-icon-monochrome.png"
+      },
+      "package": "dev.stim.tutorial"
+    },
+    "web": {
+      "favicon": "./assets/favicon.png"
+    },
+    "extra": {
+      "stimTutorial": 1
+    }
+  }
+}
+`,
+	".gitignore": `/ios
+/android
+/tutorial*.ad
+/tutorial*.png
+`
+};
+const TUTORIAL_PROMPTS = {
+	begin: "Run the Stim tutorial.",
+	rebuild: "Continue the Stim tutorial: rebuild",
+	agent: "Continue the Stim tutorial: agent",
+	refresh: "Continue the Stim tutorial: refresh",
+	machine: "Continue the Stim tutorial: machine",
+	finish: "Continue the Stim tutorial: finish"
+};
+const TUTORIAL_RESTART_PROMPT = "Restart the Stim tutorial.";
+const TUTORIAL_STEPS = [
+	{
+		id: "begin",
+		title: "Create the tutorial",
+		who: "agent",
+		optional: false,
+		prompt: TUTORIAL_PROMPTS.begin,
+		section: "run",
+		manual: [
+			"base=\"{base}\"",
+			"mkdir -p \"${base%/*}\"",
+			"if [ ! -e \"$base\" ]; then",
+			"cd \"${base%/*}\"",
+			"if git -C \"${base%/*}\" rev-parse --is-inside-work-tree >/dev/null 2>&1; then echo \"Stop: inside another repository. Ask for another folder; never git add in the user repository.\"; exit 1; fi",
+			`npx --yes create-expo-app@${TUTORIAL_PINS.createExpoApp} stim-tutorial --template ${TUTORIAL_PINS.template} --no-install --no-agents-md --yes`,
+			"cd \"$base\"",
+			"stim guide tutorial app",
+			...Object.entries(TUTORIAL_FILES).flatMap(([name, content]) => [`cat ${name === ".gitignore" ? ">>" : ">"} ${name} <<'STIM_TUTORIAL_EOF'`].concat(content.trimEnd().split("\n"), "STIM_TUTORIAL_EOF")),
+			"npm install --prefer-offline",
+			"npm pkg set scripts.ios=\"expo run:ios\" scripts.android=\"expo run:android\"",
+			"git init",
+			"git add -A",
+			"git -c user.name=Stim -c user.email=stim@localhost -c commit.gpgsign=false commit -m \"Stim tutorial\"",
+			"else",
+			"cd \"$base\"",
+			`node -e 'const fs = require("node:fs"); const app = fs.existsSync("app.json") ? JSON.parse(fs.readFileSync("app.json", "utf8")) : null; if (app?.expo?.extra?.stimTutorial !== ${JSON.parse(TUTORIAL_FILES["app.json"]).expo.extra.stimTutorial}) { console.error("Stop: existing non-tutorial folder or another version. Ask for another folder; never overwrite or delete it."); process.exit(1); }'`,
+			`git rev-parse --show-toplevel | node -e 'const fs = require("node:fs"); const root = fs.readFileSync(0, "utf8").trim(); if (fs.realpathSync(root) !== fs.realpathSync(process.cwd())) { console.error("Stop: inside another repository. Ask for another folder; never git add in the user repository."); process.exit(1); }'`,
+			"fi"
+		]
+	},
+	{
+		id: "sidebar",
+		title: "Workspace in sidebar",
+		who: "you",
+		optional: false,
+		prompt: null,
+		section: null,
+		manual: []
+	},
+	{
+		id: "build",
+		title: "First iOS build",
+		who: "you",
+		optional: false,
+		prompt: null,
+		section: null,
+		manual: [
+			"cd \"{base}\"",
+			"git worktree add -B stim-tutorial/tour \"{tour}\" HEAD",
+			"cd \"{tour}\"",
+			"stim worktree warm",
+			"stim guide agent",
+			"stim doctor --platform ios",
+			"stim start",
+			"stim ios"
+		]
+	},
+	{
+		id: "rebuild",
+		title: "Rebuild from cache",
+		who: "agent",
+		optional: false,
+		prompt: TUTORIAL_PROMPTS.rebuild,
+		section: "rebuild",
+		manual: [
+			"cd \"{tour}\"",
+			"stim ios",
+			"stim status --json"
+		]
+	},
+	{
+		id: "device",
+		title: "Live view and control",
+		who: "you",
+		optional: false,
+		prompt: null,
+		section: null,
+		manual: ["stim status"]
+	},
+	{
+		id: "logs",
+		title: "App logs",
+		who: "you",
+		optional: false,
+		prompt: null,
+		section: null,
+		manual: ["stim logs --errors", "stim logs --grep '\\[stim:tutorial\\]'"]
+	},
+	{
+		id: "agent",
+		title: "Agent actions and replay",
+		who: "agent",
+		optional: false,
+		prompt: TUTORIAL_PROMPTS.agent,
+		section: "agent",
+		manual: [
+			"cd \"{tour}\"",
+			"export AGENT_DEVICE_STATE_DIR=\"{stateDir}\"",
+			"stim status --json",
+			"read -r iosUdid",
+			"agent-device open dev.stim.tutorial --platform ios --udid \"$iosUdid\" --save-script=tutorial.ad",
+			"agent-device react-native dismiss-overlay || true",
+			`agent-device press 'label="Log an error"' --settle`,
+			"agent-device screenshot tutorial.png",
+			"agent-device close",
+			"grep -v -e 'target-v1' -e 'dismiss-overlay' tutorial.ad > tutorial-replay.ad",
+			"agent-device replay tutorial-replay.ad --platform ios --udid \"$iosUdid\"",
+			"stim logs --source agent --tail 10"
+		]
+	},
+	{
+		id: "refresh",
+		title: "Fast Refresh",
+		who: "agent",
+		optional: false,
+		prompt: TUTORIAL_PROMPTS.refresh,
+		section: "refresh",
+		manual: [
+			"cd \"{tour}\"",
+			"cat > theme.js <<'STIM_TUTORIAL_EOF'",
+			"export const TITLE_COLOR = '#7c3aed';",
+			"STIM_TUTORIAL_EOF",
+			"sleep 6",
+			"stim logs --errors",
+			"stim logs --grep 'title color'"
+		]
+	},
+	{
+		id: "phone",
+		title: "Watch on your phone",
+		who: "you",
+		optional: true,
+		prompt: null,
+		section: null,
+		manual: []
+	},
+	{
+		id: "machine",
+		title: "Build on another Mac",
+		who: "both",
+		optional: true,
+		prompt: TUTORIAL_PROMPTS.machine,
+		section: "machine",
+		manual: ["cd \"{tour}\"", "stim ios --build-machine \"{machine}\" --no-build-cache"]
+	},
+	{
+		id: "finish",
+		title: "Finish and archive",
+		who: "agent",
+		optional: false,
+		prompt: TUTORIAL_PROMPTS.finish,
+		section: "finish",
+		manual: [
+			"git -C \"{tour}\" checkout -- theme.js",
+			"cd \"{tour}\"",
+			"stim stop",
+			"cd \"{base}\"",
+			"stim worktree remove \"{tour}\""
+		]
+	}
+];
+//#endregion
+//#region src/guide/tutorial.ts
+const paths = `Use {base} = ~/stim-tutorial and {tour} = ~/stim-tutorial-tour unless the
+user named another parent folder. Expand ~ to the absolute home path when
+substituting inside quotes. Keep the tutorial outside the user's project.`;
+function commands(id) {
+	return TUTORIAL_STEPS.find((step) => step.id === id).manual.join("\n");
+}
+//#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: settings_default,
+	web: web_default,
+	macos: macos_default,
+	tutorial: {
+		summary: "An iOS tutorial: isolated worktree, builds, devices, logs, agent actions, and cleanup",
+		sectionHint: "run",
+		preamble: () => `STIM TUTORIAL
+
+Create a small Expo app in its own repository and tour worktree. Follow the
+normal Stim flow on iOS, then inspect builds, cache reuse, device control,
+logs, agent actions, Fast Refresh, and cleanup.
+
+Run one section per user request. Then end the turn, say what to look at in
+Stim Desktop, and give the next prompt. Pause never means stim stop.
+"${TUTORIAL_PROMPTS.begin}" means stim guide tutorial run.
+"Continue the Stim tutorial: <section>" means stim guide tutorial <section>.
+"${TUTORIAL_RESTART_PROMPT}" means stim guide tutorial restart.
+
+Without Stim Desktop, use the simulator, stim status for the workspace and
+device, stim logs --errors for errors, and stim stats for build performance.
+Follow stim guide agent for doctor, errors, consent, and cleanup. Never pair
+phones, approve machines, or grant access on the user's behalf.
+
+${paths}
+
+Start with stim guide tutorial run. For commands to type yourself, read
+stim guide tutorial manual. The first run needs network access unless the
+required npm and native dependencies are already cached.`,
+		sections: {
+			run: {
+				summary: "Create or reuse the app, warm a tour worktree, and build on iOS",
+				body: () => `RUN THE TUTORIAL
+
+${paths}
+
+Folder safety: create the base folder only if absent. Reuse an existing
+folder only if app.json's expo.extra.stimTutorial equals this guide's version,
+${JSON.parse(TUTORIAL_FILES["app.json"]).expo.extra.stimTutorial}; skip creation and file writes when reusing it. For an existing non-tutorial
+folder or another tutorial version, stop and ask the user for another folder.
+Never overwrite or delete it.
+
+For a new app, first check the selected parent folder: create it if absent,
+then run git -C <parent> rev-parse --is-inside-work-tree. If it succeeds, the
+folder is inside another repository: stop and ask the user for another folder.
+Never git add in the user's repo. Then, from the parent folder, run:
+
+  npx --yes create-expo-app@${TUTORIAL_PINS.createExpoApp} stim-tutorial --template ${TUTORIAL_PINS.template} --no-install --no-agents-md --yes
+
+Enter the base folder. Run stim guide tutorial app, write its three app files
+verbatim, and append its .gitignore lines. Then run:
+
+  npm install --prefer-offline
+  npm pkg set scripts.ios="expo run:ios" scripts.android="expo run:android"
+  git init
+  git add -A
+  git -c user.name=Stim -c user.email=stim@localhost -c commit.gpgsign=false commit -m "Stim tutorial"
+
+On reuse, run git rev-parse --show-toplevel in the base folder before adding
+a worktree; if it does not equal the base folder, the folder is inside another
+repository: stop and ask the user for another folder.
+
+Set the scripts before the commit because Expo prebuild rewrites them to
+expo run:ios and expo run:android; otherwise the dirty worktree blocks removal.
+On npm or network failure, report stderr and stop.
+
+From the base folder, add the tour worktree and run:
+
+  git worktree add -B stim-tutorial/tour "{tour}" HEAD
+  cd "{tour}"
+  stim worktree warm
+  stim guide agent
+
+Apply the guide agent doctor rule before native work: if its STATUS block
+says doctor is due, run stim doctor --platform ios from the tour worktree and
+resolve its findings. No STATUS block means doctor is current. Then run:
+
+  stim start
+  stim ios
+
+Tell the user the first build can take about four minutes on a cold cache.
+Relay the Open in Stim Desktop link printed by stim ios once.
+
+PAUSE: end the turn. Ask the user to look at the Build section, then the
+device, then Logs in Stim Desktop. Without Desktop, use stim status,
+stim stats, and stim logs --errors. Give the next prompt:
+"${TUTORIAL_PROMPTS.rebuild}". Leave the workspace running.`
+			},
+			app: {
+				summary: "Pinned template, verbatim app files, and .gitignore additions",
+				body: () => `TUTORIAL APP
+
+create-expo-app: ${TUTORIAL_PINS.createExpoApp}
+Template: ${TUTORIAL_PINS.template}
+Write the app files verbatim. Append the .gitignore lines to the template's
+existing file. App log lines start with [stim:tutorial]. Crash me raises an
+uncaught JavaScript error, and Slow request times a local three-second timer;
+Stim does not capture native network requests.
+
+${Object.entries(TUTORIAL_FILES).map(([name, content]) => `${name}\n\n\`\`\`${name.endsWith(".json") ? "json" : name.endsWith(".js") ? "js" : "text"}\n${content}\`\`\``).join("\n\n")}`
+			},
+			rebuild: {
+				summary: "Repeat the iOS build and explain the cache result",
+				body: () => `REBUILD
+
+${paths}
+
+Run the same build again, never with --no-build-cache:
+
+${commands("rebuild")}
+
+Read this workspace's environments[].lastBuilds.ios.cacheHit from
+stim status --json, and the miss reason printed by stim ios. Explain a local or remote hit, or the actual miss
+reason when cacheHit is false. A repeat run can miss; report the evidence.
+
+PAUSE: end the turn. Point at the Build section and cache badge, or stim stats.
+Ask the user to open the device's live view and tap Log an error; without
+Desktop use the simulator. Then inspect Logs or stim logs --errors. Crash me
+and Slow request are optional: the former shows a red box, the latter prints
+a timing line. Give the next prompt: "${TUTORIAL_PROMPTS.agent}".`
+			},
+			agent: {
+				summary: "Record a tap and screenshot, replay it, and inspect agent logs",
+				body: () => `AGENT ACTIONS
+
+${paths}
+
+Set {stateDir} to this workspace's agentDevice.stateDir from stim ios or
+stim status --json. Replace <ios.udid> with this workspace's ios.udid from
+stim status --json. Use that exact owned simulator, not a guessed one.
+Run from the tour worktree:
+
+${commands("agent").replace("read -r iosUdid", "iosUdid=\"<ios.udid>\"")}
+
+Use --save-script=tutorial.ad with the equals sign: agent-device treats a
+separate path as a URL and refuses. The dismiss-overlay step clears a red box that would cover the buttons.
+Replay with the same --platform and --udid so its steps reach the agent log.
+Remove the target-v1 evidence and dismiss-overlay lines before replay: replaying
+them can fail with REPLAY_DIVERGENCE on the recorded button identity.
+The scripts and screenshot stay in the tour worktree and are git-ignored.
+
+PAUSE: end the turn. Point at Agent actions, or the agent log records just
+printed. Expect another error-button line after replay. When screen recording
+is enabled, the user can scrub Replay in Desktop. Give the next prompt:
+"${TUTORIAL_PROMPTS.refresh}".`
+			},
+			refresh: {
+				summary: "Change the title to purple and verify Fast Refresh through logs",
+				body: () => `FAST REFRESH
+
+${paths}
+
+Set TITLE_COLOR in theme.js to '#7c3aed' (purple). Wait a few seconds for
+Fast Refresh, without reloading the app:
+
+${commands("refresh")}
+
+The line [stim:tutorial] title color=#7c3aed is the proof that the edit reached
+the app. The intentional button errors may still be in the error log; check
+whether the edit introduced a new error.
+
+PAUSE: end the turn. Point at the purple title in the device view or simulator
+and the title color log line. Phone viewing and an approved build machine are
+optional user steps; skip them if unwanted. Never pair, approve, or grant
+anything. If the user names an approved machine, the next prompt is
+"${TUTORIAL_PROMPTS.machine}". Otherwise give
+"${TUTORIAL_PROMPTS.finish}".`
+			},
+			machine: {
+				summary: "Optionally build using a machine the user names and has approved",
+				body: () => `BUILD MACHINE (OPTIONAL)
+
+${paths}
+
+Proceed only when the user names an approved build machine. Substitute that
+name for {machine}. Never approve, pair, or grant anything. If none is named,
+ask for the name or let the user skip this step.
+
+${commands("machine")}
+
+This step bypasses the artifact cache so the build can use the named machine.
+A named machine refuses without a local fallback. If it refuses, report the
+refusal and offer --build-machine auto or local; do not retry silently.
+
+PAUSE: end the turn. Point at the build's machine in Desktop or its report in
+stim status --json. Give the next prompt: "${TUTORIAL_PROMPTS.finish}".`
+			},
+			finish: {
+				summary: "Revert the tutorial edit, stop, and remove only the tour worktree",
+				body: () => `FINISH
+
+${paths}
+
+The user's finish request authorizes removing this tour worktree only.
+Revert the refresh edit before removal; worktree remove refuses dirty trees.
+Stop from the tour path, then remove from the base checkout:
+
+${commands("finish")}
+
+Never use --force. On a refusal, report it and stop. Keep the base folder
+and branch. Print these optional cleanup commands for the user; do not run. Deleting
+the base folder also removes the branch, so they are alternatives:
+
+  rm -rf "{base}"
+  git -C "{base}" branch -D stim-tutorial/tour
+
+If archive is enabled, tell the user the tour appears under Archived in Stim
+Desktop. With archive disabled, report removal without promising an archive.
+Without Desktop, inspect stim status --json for the removed environment and,
+when enabled, its archived entry. End the turn.`
+			},
+			restart: {
+				summary: "Remove the existing tour safely and repeat from the worktree step",
+				body: () => `RESTART
+
+${paths}
+
+For "${TUTORIAL_RESTART_PROMPT}", if the tour worktree is present, revert
+the refresh edit, stop, and remove it using the finish section's commands:
+
+${commands("finish")}
+
+Never use --force. On a refusal, report it and stop. Keep the base repository.
+Read stim guide tutorial run, recheck its folder and repository safety rules,
+and redo run from the worktree step. Pause after the build as run instructs.`
+			},
+			manual: {
+				summary: "Commands for every step, including heredocs for the app files",
+				body: () => `MANUAL TUTORIAL
+
+${paths}
+
+These commands are for a person typing them, one step at a time,
+as scripts: save a block to a file and run it with sh -e, so it stops on the
+first failure. Read stderr and do not continue to later commands. Follow stim guide tutorial run for folder and repository
+safety. Reuse only this version's tutorial app, never overwrite another folder.
+The creation block skips writes on reuse and checks the repository root.
+
+Replace {base} and {tour} with absolute paths; {base} must end in stim-tutorial. For Agent actions, replace
+{stateDir} with agentDevice.stateDir from stim ios or stim status --json;
+when read -r iosUdid waits, type this workspace's ios.udid from that status.
+For the optional machine step,
+replace {machine} with a machine you have already approved, or skip it.
+
+Look at the sidebar during warm and Build during the first build (about four
+minutes on a cold cache). Compare cacheHit and missReason on rebuild. At Live
+view and control, open the device viewer and tap Log an error; without Desktop
+use the simulator. At App logs, try Crash me or Slow request if wanted. A JS
+crash shows a red box; the slow request is a local timer, not network capture.
+At Watch on your phone, optionally open an already paired Stim phone to see
+the tour workspace; phone setup and machine approval stay with you.
+Use stim status, stim logs --errors, and stim stats without Desktop.
+
+${TUTORIAL_STEPS.map((step) => `${step.title}${step.optional ? " (optional)" : ""}\n\n${step.manual.length ? `\`\`\`sh\n${step.manual.join("\n")}\n\`\`\`` : "Observe this step in Stim Desktop, or skip it without Desktop."}`).join("\n\n")}
+
+Finish removes only the tour worktree. Never use --force; report a refusal.
+With archive enabled, find the tour under Archived in Desktop or archived[]
+in stim status --json. Keep the base repository and branch. To delete them,
+read stim guide tutorial finish for commands to review and run yourself.`
+			}
+		}
 	}
 };
 //#endregion