stim 1.17.2 → 1.19.0

package/dist/{guide-CSmhMTf8.mjs → guide-dRaQJJk9.mjs}

@@ -1,8 +1,8 @@
-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 { r as findProjectRoot } from "./project-B5eQ1USs.mjs";
+import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-CxgngUZk.mjs";
+import { s as RECENT_LAUNCH_MS } from "./watchman-BL1IdOtq.mjs";
+import { o as guideStatus, t as WATCHMAN_NESTED_WORKTREES } from "./doctor-watchman-wZhyTdp4.mjs";
+import { SETTINGS, SETTINGS_SCHEMA_URL, TUTORIAL_VERSION } from "@stim-cli/core/state";
 import chalk from "chalk";
 //#region src/guide/agent.ts
 var agent_default = {
@@ -293,6 +293,11 @@ Ask the user before these actions:
   nothing else.
 - gc --delete --worktrees, because it runs worktree remove on every clean,
   idle linked worktree Stim manages, across projects.
+- settings set maintenance.mode on in a home where it is off or report, because
+  it lets Stim itself clear build outputs, trim caches and remove finished
+  worktrees later, with no command from you. It is on by default outside CI
+  and scoped STIM_HOME homes. maintenance.keep true pins a workspace against
+  that; maintenance.mode report or off stops it.
 - stop when the workspace owns an EAS session, because it irreversibly ends
   that remote session. For a local device, stop shuts it down but does not
   delete it. An explicit stop shuts down a Stim-owned simulator even when
@@ -382,6 +387,7 @@ FULL TOPIC LIST
   stim guide lifecycle options    # every flag, Android variants, --device-type, --system-image, --device-profile
   stim guide lifecycle devices    # ios --device and android --device on a physical phone
   stim guide lifecycle release    # Release configurations and ...Release variants
+  stim guide api                  # typed run, stop, diagnostics and cancellation from the main package
   stim guide facts                # the --json payloads
   stim guide facts devmenu        # the Expo dev menu or Tools button over the app
   stim guide macos                # Swift Package Debug apps, logs, local preview, --remote on another Mac
@@ -397,6 +403,64 @@ FULL TOPIC LIST
   stim guide settings             # configuration files and supported keys`
 };
 //#endregion
+//#region src/guide/api.ts
+var api_default = {
+	summary: "Typed lifecycle API: createStim, run, stop, diagnostics, and cancellation",
+	body: () => `PROGRAMMATIC API
+
+Install stim as a project dependency: npm install --save-dev stim.
+Import { createStim, StimError } from 'stim'. Node 22.12 or later is required.
+
+  const stim = createStim({ projectRoot: process.cwd() });
+  try {
+    const result = await stim.run({ platform: 'ios' });
+  } finally {
+    try {
+      const diagnostics = await stim.diagnostics({ errors: true });
+    } finally {
+      const cleanup = await stim.stop();
+      if (!cleanup.ok) throw new Error(cleanup.summary);
+    }
+  }
+
+createStim takes projectRoot, optional absolute home and buildCache paths,
+and onProgress({ stream, message }). message is an output chunk. Without
+onProgress, operations write nothing to the caller's stdout or stderr. Each
+operation uses a bundled worker that calls the same lifecycle operations as
+the CLI; it never parses CLI arguments or changes the caller's cwd/environment.
+
+run takes platform plus its options:
+  ios:     configuration, scheme, deviceType, runtime
+  android: variant, systemImage, deviceProfile
+  macos:   remoteBuild
+  web:     headed (default false)
+iOS and Android also accept slot, metroCheck, buildCache, and remoteBuild.
+All methods accept signal. run builds, installs and launches; build-only is
+not available. Web requires a running server, just like stim web.
+
+run returns { platform, facts }. iOS facts include udid; Android includes
+serial; both include bundleId, appPath, metroPort, cacheHit and launched.
+macOS facts include bundle, bundleId, executable, pid, build and launched.
+Web facts contain the owned browser's existing launch and page facts.
+Do not interpret 'bundling' or 'unverified' as proven application readiness.
+
+stop({ slot? }) returns { ok, outcomes, summary }. It acts on the workspace,
+including resources from earlier runs. Use a dedicated workspace in CI.
+Cancellation waits for the operation worker to exit; stop with a fresh signal
+after cancellation or partial failure. Always inspect cleanup.ok.
+
+diagnostics({ tail: 200, errors: false }) returns { directory, records } from
+the local timeline, even before a successful run. tail: 0 returns paths only.
+It does not fetch remote logs or capture new crashes. Stim failures reject with
+StimError carrying code, message, remedy and details (including the log path).
+An exception thrown by onProgress cancels its worker and propagates unchanged.
+
+Normal ownership, device creation, cache locks and coordination remain active.
+All concurrent artifact-cache writers must share the same coordinating home.
+Do not point independent Stim homes at a concurrently writable shared cache.
+`
+};
+//#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",
@@ -945,7 +1009,7 @@ leased until <time>" for each one.`,
                   reasons as { code, reason } with that code. capacity
                   is the machine's offer: { running, max, diskFreeBytes,
                   minDiskFreeBytes, cpus?, loadPerCore?, builds?, maxBuilds?,
-                  maxLoadPerCore?, declined? }; an older stim-server omits the
+                  maxLoadPerCore?, memoryUsedBytes?, memoryTotalBytes?, declined? }; an older stim-server omits the
                   optional fields
   findings        the diagnostic findings; a lower resolved Stim is a
                   costs-time finding with a PATH or installation remedy
@@ -1203,7 +1267,7 @@ RULES
                     cannot read. A macOS privacy denial (EPERM) names the
                     Privacy & Security setting to grant
   maintenance     top-level { mode, pressure, actions, blocked,
-                  skips, note, invalid? }, the next report-only maintenance plan
+                  skips, note, invalid? }, the next maintenance plan
                   from live pressure and cached sizes. note says when no
                   pass has run yet. No du runs for this preview.
   sections        one array per report section, in the text order. Every key
@@ -1368,8 +1432,9 @@ RULES
 			body: () => `  stim status --json
 
   logs        { dir, errorsSinceMarker }, or null without a log directory
-  agentDevice { stateDir }: absolute workspace agent-device state path on
-              every environment, shared by its slots. Reporting it creates
+  agentDevice { stateDir, installed }: absolute workspace agent-device state
+              path on every environment, shared by its slots, and whether
+              the agent-device executable is on PATH. Reporting it creates
               no directory; agent-device creates it when used.
 
   Each environment carries phase, where the workspace is in its lifecycle:
@@ -1685,14 +1750,18 @@ RULES
                    once the app is ready and covers waiting for the
                    device: its boot, adoption cleanup, or a physical
                    device's lease and connection check. A boot that
-                   finishes during the build adds no device time. An
+                   finishes during the build adds no device time. For a
+                   device hosted on another Mac, device covers reserving
+                   and preparing it there, install covers delivering the
+                   app, and launch starts when the host launches it. An
                    --eas-profile run has no cache lookup, so its outcome
                    stays the project's most recent one until install.
                    A stim macos run enters only prepare, compile (SwiftPM,
                    with detail), install (staging the bundle, or fetching
                    it from a build machine) and launch. It has no cache
                    lookup: outcome is null, plannedPhases is null, and
-                   builds.macos holds its finished runs and their phases.
+                   builds.macos holds its finished runs, their phases and
+                   compileSteps.
   startedAt        when the run started; phaseStartedAt when its phase did
   outcome          "cold" after the local/provider lookups resolve a miss;
                    "hit" after a cached artifact is ready to reuse, including
@@ -1877,7 +1946,8 @@ RULES
   disk (environment)  { worktreeBytes, nodeModulesBytes, buildBytes,
                       measuredAt }
     worktreeBytes     the linked worktree, or else the checkout holding the
-                      workspace, node_modules included
+                      workspace, node_modules included; the linked
+                      worktrees nested inside a checkout are not counted
     nodeModulesBytes  node_modules at that root and at the workspace path;
                       part of worktreeBytes
     buildBytes        Stim's folder for the workspace: Xcode derived data,
@@ -1887,11 +1957,13 @@ RULES
   disk (device)       { bytes, measuredAt }: the simulator's data folder
                       under CoreSimulator/Devices, or the AVD's .avd folder
 
-  \`status --watch\` runs one du at a time off its refresh path, and measures
-  a folder at most every 5 minutes while its environment is active and every
-  hour otherwise. It caches each size under $STIM_HOME/disk-usage, which
-  one-shot status only reads, so the fields appear once a watcher, such as
-  stim-server or Stim Desktop, has measured.
+  \`status --watch\` runs one du at a time on the whole machine, at low
+  priority, off its refresh path, and measures a folder at most every 5
+  minutes while its environment is active and every hour otherwise. A walk
+  that fails or times out is not repeated by any watcher for that period. It
+  caches each size under $STIM_HOME/disk-usage, which one-shot status only
+  reads, so the fields appear once a watcher, such as stim-server or Stim
+  Desktop, has measured.
 
   An environment carries agents when coding-agent sessions work in it, most
   recently active first:
@@ -1957,13 +2029,15 @@ RULES
   and always uses the estimate. What is using CPU and memory now is the
   top-level machine section:
 
-  maintenance { mode, lastChecks: { pressure, size }, pressure, sizes,
+  maintenance { mode, lastChecks: { pressure, size, worktree, sweep }, pressure, sizes,
                 lastPass, running, recent, plan, invalid?, claim? }
-    Report-only observations; every plan action's kind starts with would-.
+    mode is off, report or on. Plan actions start with would-; the records
+    of actions taken drop the prefix (clear-outputs, trim-cache, empty-cache,
+    remove-worktree, remove-orphan, unregister-cache).
     lastChecks are epoch milliseconds or null. running comes only from a
     live maintenance/run.claims owner, never from a check stamp.
-    lastPass carries startedAt, durationMs, trigger, mode, freedBytes (0),
-    actions, stopped (0), blocked. recent holds the last 20 action, failure
+    lastPass carries startedAt, durationMs, trigger, mode, freedBytes
+    (0 in report mode), actions, stopped (0), blocked. recent holds the last 20 action, failure
     and blocked NDJSON records from maintenance/maintenance.ndjson.
     invalid names invalid settings; invalid cache caps use their defaults,
     while invalid maintenance settings disable passes. claim contains an
@@ -2018,7 +2092,7 @@ RULES
 
   { platform, slot?, fingerprint, cacheKey, cacheHit, provider,
     cacheSkipped, prebuild, outcome, expectedMs, basis, missReason?,
-    refusal? }
+    placement?, refusal? }
 
   fingerprint   the fingerprint the run would look up first; with
                 --eas-profile, the one EAS CLI computes
@@ -2044,6 +2118,9 @@ RULES
                 plan does not, so changes compare the fingerprint before that
                 prebuild; changeCount 0 then means those inputs match the
                 baseline. rekeyedBy is empty.
+  placement     with ios.remote or android.remote set to auto or a Mac,
+                where the plan assumes the device runs: "on <machine>" or
+                "this Mac; auto may use <machines>"; absent otherwise
   refusal       { code, message, remedy } when the run would refuse:
                 STIM_PREBUILD_FAILED for a tracked native dir the fingerprint
                 leaves out, STIM_EAS_BUILD_MISSING for an EAS miss
@@ -2182,8 +2259,9 @@ HOW A RUN IS COUNTED (\`stats\`)
 
 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
+  facts, lastBuilds and build history. decision is "local", "hosted",
+  "waited-locally" (the local run actually waited for a device slot) or "eas"
+  (remote.easFallback put it on an EAS Simulator, reported like --remote eas). 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.
@@ -2530,9 +2608,15 @@ then 8081, without probing or reserving; an invalid pin still refuses.
 
 New allocations scan TCP ports 8900-8999. They skip registry reservations
 and existing listeners, announcing occupied ports and upward retries on
-stderr. Listener checks require lsof, or netstat on Windows. All 100 ports
-occupied or reserved is a refusal; stop or release unused allocations in
-their owning workspaces.
+stderr. All 100 ports occupied or reserved is a refusal; stop or release
+unused allocations in their owning workspaces.
+
+Metro allocation (from 8082 up) and named allocation find listeners in the
+native TCP table: netstat on macOS and Windows, /proc/net on Linux. When that
+table is denied, empty or unreadable, as in some sandboxes, each candidate is
+checked with an lsof listener scan and connects to 127.0.0.1 and ::1 instead.
+Allocation refuses only when none of them can answer: start refuses with
+STIM_PORT_INSPECTION_FAILED, and ports get prints the same message.
 
 The machine registry, under STIM_HOME, serializes allocation and cleanup.
 The workspace is the nearest package.json directory, resolved through
@@ -2555,6 +2639,7 @@ ports lists named labels and ports, plus Metro marked managed.
 ports stop [label] kills TCP listeners on those named ports and releases
 the allocations. It sends SIGTERM, waits two seconds, then SIGKILL if needed;
 on Windows it terminates the listener's process tree with taskkill.
+Stopping listeners requires lsof on macOS and Linux, or netstat on Windows.
 It prints the PID and command (the image name on Windows) for each stopped
 process. The listener's cwd can be anywhere: the named reservation is
 permission to stop that listener.
@@ -2646,7 +2731,7 @@ FLAGS
   --slot <name>   only this slot's records plus, once it has launched, the
                   shared untagged Metro and app client records (not the web
                   page's); default also includes untagged legacy records
-  --source <s...>  metro, client, device, build, agent, maintenance (one or more), or all.
+  --source <s...>  metro, client, device, build, agent, maintenance, placement (one or more), or all.
                    An unknown value is REJECTED rather than quietly matching
                    nothing.
   --level <l>      minimum level: debug, info, warn, error, fatal
@@ -2783,6 +2868,12 @@ THE RECORD
     event    the producer's own event name (bundle_build_done, client_log, ...)
     stack    frames of { file, line, column, fn }, passed through as reported
     marker   true on the records that close an error window
+    runId    the id of the stim invocation that wrote the record: STIM_RUN_ID
+             when set to a valid id (letters, digits, . _ -, at most 64),
+             else generated per run. Processes a command starts, such as the
+             Metro supervisor and the collectors, keep the id of the command
+             that started them. Debug records and the hello to stim-server
+             carry it too, and stim-server puts it on its log lines.
     deviceTs Android logcat's original epoch milliseconds; ts is aligned to
              host time using a bounded clock query at each collector attachment
     clockOffsetMs the offset added to deviceTs; absent if the query failed.
@@ -2800,6 +2891,63 @@ Add --errors to --source maintenance to show only maintenance_failure events;
 failures before a later launch marker are hidden. Machine passes are reported in
 status and maintenance/maintenance.ndjson; this command reads workspace logs.
 
+REMOTE REQUEST RECORDS
+A request to another Mac that fails is a warn record with src: build in the
+run's build log: remote_connect_failed { host, capability, ms, timeoutMs, msg,
+code } (could not connect or say hello, e.g. "no reply in time" when the Mac
+did not answer hello) and remote_request_failed { method, ms, code, msg }.
+Timings of requests that succeed are debug records (below).
+stim-server writes to its service log (~/Library/Logs/Stim/<label>.log), with
+no tokens or tickets: "request failed method=<m> client=<device id> run=<runId>
+ms=<n> error=<code>" for an error reply (once a minute per client, method and
+code) and "host_connect ... error=<reason_with_underscores>" when its connection to a hosting
+Mac fails. With debug.logs on or STIM_DEBUG=1 for the server it logs every
+request instead: "debug request method=<m> client=<id> run=<runId> ms=<n>
+slow=true error=<code> whois=<ms> probe=<ms>" (slow means 1000 ms or more;
+whois and probe are the hello's Tailscale identity lookup and its wait for
+the host permission probe; a method name that is not a plain dotted lowercase
+name is logged as unknown)
+and "debug host_connect host=<mac> ms=<n> connectMs=<n> helloMs=<n>" (reused=true instead of the two
+timings when an open connection was shared), also as
+records in STIM_HOME/logs/debug/server.ndjson. Search the run id in both logs.
+
+DEBUG LOGS
+With debug.logs on or STIM_DEBUG=1 (stim guide settings), the CLI also appends
+debug records to STIM_HOME/logs/debug/cli.ndjson, outside any workspace, so
+stim logs does not show them. Read them with jq:
+  jq -c 'select(.event=="exec" and .ms>1000)' ~/.stim/logs/debug/cli.ndjson
+Events: run_start, run_end { exit, ms }, exec { program, ms, ok, exit? }, and
+remote_connect and remote_request { ms, ok, code? } for requests to another
+Mac. They carry no arguments, tokens or tickets.
+
+Placement records use src: placement and sit in the run's build log
+(build-*.ndjson), so a new run replaces the previous run's. A run writes one
+record per decision it makes (a build that compiles and has a remote Mac to
+consider, or ios/android --remote auto), with event build_placement,
+device_placement or placement_fallback. A cache hit, a project with no paired
+remote Mac and a named --remote target write none:
+  stim logs --source placement
+  stim logs --source placement --json
+Fields: kind (build or device), platform, settings [{ key, value, from }] with
+from flag, env, setting or default (remote.build and remote.buildMode for a
+build, ios.remote or android.remote, plus remote.easFallback when it is on, for
+a device), candidates [{ machine, code,
+msg, detail? }], choice { machine, code, msg } with machine local when the run
+stays on this Mac, and fallback { code, msg, machine? } when a remote Mac that
+was meant to take the run did not (level warn). The msg is the same text the
+placement: and build: phase lines print.
+Candidate codes: accepted, unreachable, busy, disk, load, version-mismatch
+(detail lists the toolchain parts: xcode, arch, jdk, ...), no-matching-device,
+declined, memory, no-capacity; with machine eas, why an EAS Simulator was not
+used: eas-named-slot, eas-local-flags, eas-no-agent-device, eas-no-cli,
+eas-cli-too-old, eas-session-busy, eas-metro-unreachable, eas-logged-out, eas-not-enabled,
+eas-unavailable. Choice codes for a build: placed, named,
+forced, this-mac-busy, this-mac-free, mode-off, local-selected, no-remote-mac,
+unsupported; fallback codes: no-remote-mac-took-it, offload-failed, fallback.
+Choice codes for a device: placed, sticky, this-mac-free, no-remote-mac,
+device-count-unknown, no-host-admits, eas-fallback (machine eas). Machine names appear in these records;
+they stay in the local logs. These records carry no tokens.
+
 WHAT WRITES WHAT
   maintenance.ndjson   workspace maintenance actions, failures and explaining skips
   metro.ndjson         the bundler, in both supervisor modes
@@ -3005,6 +3153,9 @@ Branch on the code, never on the message.`,
   an unavailable choice. A session that exists stays recorded even if delivery
   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.
+  To see why a host was slow or refused: stim logs --source placement (hosts checked and
+  reason codes), stim logs --source build (remote_connect_failed, remote_request_failed),
+  and the host's stim-server service log, searched for the run id (stim guide logs).
   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 handoff and native logs (hello features hosted-ios-data
@@ -3308,9 +3459,14 @@ Branch on the code, never on the message.`,
   works. See stim guide macos.`
 		},
 		STIM_OFFLOAD_REFUSED: {
-			summary: "the selected remote Mac cannot build this app",
+			summary: "the selected remote Mac or automatic build pool cannot build this app",
 			body: () => `STIM_OFFLOAD_REFUSED
 
+Automatic placement also refuses when local is excluded in remote.buildPoolDisabled
+and no enabled remote can finish this build, or when the build requires a local
+compiler. Enable local or choose an explicit --remote-build placement. Existing
+builds are not interrupted and a cache hit needs no compiler.
+
 A named --remote-build selection is strict. The message names the machine
 and why it cannot take or finish the build: not configured or paired, approval
 pending or denied, unreachable or changed pinned identity, incompatible
@@ -3756,7 +3912,9 @@ so a Debug run on one is wired to a LAN origin instead of localhost.`,
   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
+  or raise concurrency.maxDevices. With --remote auto, remote.machines and
+  the opt-in remote.easFallback (billed EAS Simulator) are tried before this
+  wait; \`stim logs --source placement\` says why neither took the run. 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\`.`
@@ -4043,6 +4201,17 @@ 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_PORT_INSPECTION_FAILED: {
+			summary: "no free Metro port could be confirmed: netstat, lsof and loopback connects all failed",
+			body: () => `STIM_PORT_INSPECTION_FAILED
+  Stim reads the native TCP listener table (netstat on macOS and Windows,
+  /proc/net on Linux) to find a free Metro port. When that table is denied,
+  empty or unreadable, it checks each candidate with an lsof listener scan and
+  connects to 127.0.0.1 and ::1. This refusal means none of them could answer,
+  usually because a sandbox denies them. Allow Stim to run netstat or lsof, or
+  to connect to loopback, then retry. A metro.port pin skips the scan for
+  Metro. \`stim ports get\` prints the same message.`
 		},
 		STIM_SUPERVISOR_EXITED: {
 			summary: "the dev server failed outright; the quoted supervisor.log tail is the real error",
@@ -4397,7 +4566,12 @@ not on any remote"  (worktree remove)
   Warm copied ignored Pods from the source checkout, but their Manifest.lock
   differs from the tracked Podfile.lock in this worktree. Warm does not change
   tracked files. Run the printed pod-install command before building directly.
-  \`stim ios\` detects a mismatch and runs \`pod install\` for you.
+  \`stim ios\` detects a mismatch and runs \`pod install\` for you. A mismatch
+  limited to checksums of podspecs that embed the source checkout's path is
+  resolved by warm itself ("carry moved <dir>/Pods to this checkout's path")
+  and does not print this line. When the locks match but Pods still name the
+  source path and warm cannot move it, it prints "removed <dir>/Pods/Manifest.lock
+  so pod install runs" and \`stim ios\` runs \`pod install\`.
 
 "carry       carried <dir>/Pods but there is no <dir>/Podfile.lock"
   Warm copied Pods but the destination has no Podfile.lock. Follow the printed
@@ -4523,6 +4697,22 @@ not on any remote"  (worktree remove)
   Expo build-cache provider would each use a different store. Set the named
   variable to an absolute path, or unset it to use the default. Metro and the
   cache provider, which cannot refuse, ignore a relative value with a warning.`
+		},
+		STIM_WORKER_FAILED: {
+			summary: "a programmatic API worker exited without returning an operation result",
+			body: () => `STIM_WORKER_FAILED  (programmatic API)
+  The worker process ended without a structured result. StimError.details
+  includes its final stderr output. Inspect that output and call diagnostics()
+  for existing workspace logs, then stop() with a fresh signal to clean up
+  any resources created before the failure. See stim guide api.`
+		},
+		STIM_RUN_FAILED: {
+			summary: "a programmatic operation failed without a more specific Stim code",
+			body: () => `STIM_RUN_FAILED  (programmatic API)
+  The underlying operation threw an error without a specific code. Its
+  message and workspace log path are preserved in StimError. Read diagnostics()
+  and call stop() in cleanup, including after a partial run. If the error is
+  unexpected, report its message and logs at github.com/appandflow/stim/issues.`
 		},
 		STIM_NODE_UNSUPPORTED: {
 			summary: "stim or stim-server started on a Node older than 22.12.0, often a project pin",
@@ -4806,6 +4996,46 @@ WAITING FOR A CHANGE
   still running, which it notices at the next change.
   Without --json it reprints the human view on change.`,
 	sections: {
+		ci: {
+			summary: "Run an app and tests through @stim-cli/ci with diagnostics and scoped cleanup",
+			body: () => `CONTINUOUS INTEGRATION
+
+Install app dependencies and platform tools first. Use a dedicated checkout:
+cleanup stops that workspace, including resources created before a build fails.
+
+  npx --yes --package @stim-cli/ci stim-ci run --platform ios --project ./app --timeout 1800 -- pnpm test:e2e
+
+Or install npm install --global @stim-cli/ci and use stim-ci directly.
+Platforms: ios, android, macos, web. Everything after -- is argv, not a shell.
+--artifacts selects the result directory (a fresh temporary directory by default).
+An explicit artifacts directory must be empty; use a new directory per run.
+Stdout is one JSON result; progress and test output go to stderr.
+
+Tests receive STIM_CI_PLATFORM, STIM_CI_DEVICE_ID, STIM_CI_APP_ID,
+STIM_CI_METRO_PORT, STIM_CI_ARTIFACTS_DIR and STIM_CI_RUN_RESULT. The last is
+run.json with the exact public API result. Use that target and check app
+readiness; launched can still be bundling or unverified.
+
+result.json preserves the test exit code even if diagnostics or cleanup fail.
+Passing tests with failed cleanup return 1; timeout returns 124; cancellation
+returns 130. Leave 70 seconds before the job's hard timeout for diagnostics and
+stop. SIGKILL and runner loss cannot run cleanup. Stop shuts down owned devices;
+it never deletes them.
+
+GitHub-hosted jobs default to $RUNNER_TEMP/stim-ci/home and
+$RUNNER_TEMP/stim-ci/build-cache, reused between steps in the job. Detection
+requires GITHUB_ACTIONS=true, RUNNER_ENVIRONMENT=github-hosted and RUNNER_TEMP.
+An explicit --home or STIM_HOME keeps the selected home and its normal cache
+configuration; --build-cache or STIM_BUILD_CACHE overrides the cache path.
+Self-hosted runners and local runs keep normal Stim configuration. Other
+exclusive disposable providers can set their job-local paths explicitly.
+CI=true alone does not change defaults, ownership or coordination. Persist only
+cache artifacts, not state, claims or device ledgers. Independent homes must
+not share a writable filesystem cache because its claims live in the home.
+
+The programmatic runner is import { runCI } from '@stim-cli/ci'. See its package
+README for result types, cancellation, cache policy, and coordination findings.`
+		},
 		"hosted-android": {
 			summary: "Android on a named approved Mac: strict placement, private Metro, status and stop",
 			body: () => `ANDROID ON A HOSTING MAC
@@ -4972,7 +5202,10 @@ 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 server.maxLoadPerCore. Without remote.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.
+still decides. The default without a flag or setting stays local. remote.devicePoolDisabled excludes
+members from new automatic placement only; an excluded local member is never a
+fallback. Existing sessions keep their owner and named placement bypasses the pool.
+See stim guide settings for separate build/device membership controls.
 
 Otherwise Stim asks every approved remote.machines host in parallel, with a
 3-second probe timeout and this run's model/runtime or image/profile selectors.
@@ -4983,9 +5216,26 @@ Hosts rank by the build preference (flag > STIM_REMOTE_BUILD > remote.build)
 when it names a machine, then lowest load, most free memory and remote.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
+When no host admits and this Mac is at its concurrency.maxDevices cap (or runs
+are queued ahead), remote.easFallback (default false; EAS Simulator is billed)
+runs the device on an EAS Simulator exactly as --remote eas would: the build
+stays here, nothing starts an EAS cloud build, stop ends the session, and
+status reports it under remoteDevices. A busy Mac with a free slot never uses
+it. Before choosing it Stim checks, without starting a session, that eas-cli
+has simulator commands (and 22.2.0+ for --device-type), eas
+simulator:availability says this project's account can use it, agent-device
+is on PATH, the slot is default, no --runtime, --system-image or
+--device-profile flag is given, no EAS Simulator session of this workspace runs
+another platform or model, and a Debug run's Metro is reachable (not
+metro.tunnel off; on an Expo tunnel, run stim start --remote first). A recorded
+EAS session is not sticky: once this Mac has room, auto runs here and the
+session bills until stim stop. If any check fails, or the
+setting is off, 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.
+line explains the decision, the skipped hosts and why EAS was not used
+(machine "eas"). JSON progress goes to stderr.
+The same decision, with a reason code per host, is a src: placement record in
+stim logs (stim guide logs).
 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.
 
@@ -5736,8 +5986,17 @@ PREDICTING THE NEXT BUILD (--plan)
   An Android plan reads the ABI from the emulator the slot records, or from
   the system image a new one would use. A plan refuses --device, --remote,
   --wait, --no-wait, --no-metro-check and --simulator-app with STIM_BAD_ARG.
-  Without --eas-profile it also refuses the ios.remote and android.remote
-  settings with STIM_BAD_ARG. Without --eas-profile an Android plan also
+  With ios.remote or android.remote set to a Mac name, a plan reads the
+  architecture or ABI from that Mac's device offer, the question a run asks
+  before it reserves anything. With auto it repeats the placement decision a
+  run would make now and reports where in the payload's placement field, for
+  example "this Mac; auto may use janics-mac-mini". When the plan stays on
+  this Mac and a listed Mac would build for another architecture, placement
+  says so, since that Mac's key differs. The plan only predicts the key: a
+  run reads the architecture of the device it actually gets. A Mac that does
+  not answer, ios.remote or android.remote set to eas or proxy, or auto that
+  would use an EAS Simulator now (remote.easFallback), refuses with
+  STIM_BAD_ARG. Without --eas-profile an Android plan also
   refuses the experimental compiler CAS with STIM_BAD_ARG, and refuses with
   STIM_NO_DEVICE when no system image is installed.
 
@@ -6493,6 +6752,24 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   overlapping a nested destination worktree or below a symlink ancestor.
   Tracked .idea settings come from Git and stay untouched by warm.
 
+  A carried ios/Pods still names the source checkout's path in its generated
+  files and in the checksum of a podspec that embeds that path (the
+  precompiled ExpoModulesCore). When ios/Podfile.lock and the carried
+  ios/Pods/Manifest.lock differ only by those checksums, warm rewrites the
+  source path to the worktree's path in Pods/Target Support Files,
+  Pods.xcodeproj, Local Podspecs and absolute symlinks, then makes
+  Manifest.lock equal Podfile.lock, so the first \`stim ios\` skips
+  \`pod install\`. Any other difference, a missing podspec, or a podspec
+  that does not embed the source path, any other file in Pods that names
+  the source path, or carried node_modules that do not match the worktree's
+  lockfile leaves Pods as copied, and \`pod install\` runs. Warm does not edit Podfile.lock.
+
+  When the two locks already match but the copied Pods still name the source
+  path, warm applies the same rewrite and scan so builds do not read the
+  source checkout's files (entitlements, Podfile.properties.json). If it
+  cannot (stale node_modules, a leftover path, an error), warm deletes
+  ios/Pods/Manifest.lock so \`stim ios\` runs \`pod install\`.
+
   Other generated state stays eligible: .gradle, .cxx, *.tsbuildinfo, build
   directories, and embedded JavaScript need project-specific decisions about
   regeneration. Native intermediates can record the source checkout's paths;
@@ -7042,35 +7319,66 @@ $STIM_HOME/archive by default. See stim guide cleanup archive.
 
 MAINTENANCE
 
-Automatic maintenance is report-only in this release: it measures, plans and
-logs, and never stops or deletes resources. The default mode is report; it is
-off in CI and scoped STIM_HOME homes unless STIM_MAINTENANCE is explicit.
-Commands trigger a detached pass when disk and memory checks (every minute)
-or directory sizes (hourly) are due. guide, settings and help do not trigger
+Automatic maintenance has three modes. on (the default) runs the disk actions
+below through gc's own removal code and logs each one. report measures, plans
+and logs, and never deletes anything. off disables it. It is off in CI and
+scoped STIM_HOME homes unless STIM_MAINTENANCE is explicit, so a scratch home
+or CI run never deletes on its own.
+Commands trigger a detached pass when a check is due: disk and memory pressure
+(every minute), directory sizes (hourly), finished worktrees (every 15
+minutes) and the age sweep (daily). guide, settings and help do not trigger
 it; gc --delete also skips the hook. status --watch also triggers checks.
-Size checks defer under high load. Attempts back off for at least one minute.
-Measured directories are workspace build outputs and Stim's shared native,
-Metro, ccache, Swift compilation and registered caches. Pressure checks read
-free disk on the Stim home, projects and worker root volumes. On macOS the
-memory signal is the sysctl pressure level, with no signal if sysctl fails.
-Other platforms use os.freemem(); macOS never falls back to it.
-Memory pressure is recorded only; memory stops are deferred to a later phase.
+Size, worktree and sweep checks defer under high load. Attempts back off for at
+least one minute. Measured directories are workspace build outputs and Stim's
+shared native, Metro, ccache, Swift compilation and registered caches.
+Pressure checks read free disk on the Stim home, projects and worker root
+volumes. On macOS the memory signal is the sysctl pressure level, with no
+signal if sysctl fails. Other platforms use os.freemem(); macOS never falls
+back to it. Memory pressure is recorded only; stopping devices, dev servers
+and helpers is not automatic.
+
+In on mode a pass runs, cheapest to rebuild first:
+  1. orphaned workspace directories whose project is gone, and registered
+     caches whose directory no longer exists
+  2. build outputs of idle workspaces, over maintenance.workspaceOutputsMaxGb,
+     below the free-disk floor, or unused for maintenance.olderThanDays
+  3. build-cache and Metro entries, least recently used first, down to
+     maintenance.capTargetPercent of caches.buildCacheMaxGb or
+     caches.metroCacheMaxGb, and entries unused for olderThanDays
+  4. the Swift compilation cache, emptied whole, only below
+     budget.hardFloorDiskGb and with no build lock or slot held
+  5. linked worktrees whose branch or pull request finished (gc's finished
+     worktree rules and gc.worktreeGraceMinutes; maintenance.removeFinishedWorktrees)
+Disk-driven steps stop once free space is back above the floor. Kept for
+every pass: a workspace that is in use, holds a lock, was used within
+maintenance.protectRecentHours, is pinned with maintenance.keep, or is the
+workspace of the command that started the pass; cache entries used within
+protectRecentHours, named by a project's last builds, a parked device or a
+live build lock, or in a Metro store with a running or unverifiable dev
+server. Anything the pass cannot verify is kept. A pass never shuts down idle devices or dev servers or stops watchman; removing a
+finished worktree or orphaned directory does tear down that workspace's own
+dev server, owned devices and Chrome profile, as gc --delete does. ccache evicts by itself under
+caches.ccacheMaxGb.
 
   stim status                     last checks, plan and running pass
   stim status --json              maintenance observations and recent records
   stim logs --source maintenance  this workspace's maintenance records
   stim gc                         live pressure and cached-size preview
-  stim settings set maintenance.mode off
+  stim settings set maintenance.mode off     turn automatic cleanup off
+  stim settings set maintenance.mode report  plan and log, delete nothing
 
 The machine log is $STIM_HOME/maintenance/maintenance.ndjson, rotated at
 maintenance.logMaxMb with the old generation retained for
 maintenance.logRetentionDays. Child crashes use maintenance/child.log.
-Actions and explaining skips are logged only when newly planned. A pass is
-logged after a size check or a change to actions, skips or blocked reasons.
+In report mode actions and explaining skips are logged only when newly
+planned; in on mode every action taken, failure and explaining skip is logged
+with its bytes, and a pass record carries the bytes freed. Removal of a
+worktree or orphaned directory is logged to the machine log only.
 maintenance.logChecks enables debug observations; default false.
 status and doctor report invalid settings and unresolved claims with a removal
 command to run only after confirming the holder is gone. Invalid cache caps
 fall back to their own defaults; invalid maintenance settings disable passes.
+Pin a workspace with \`stim settings set maintenance.keep true\` in its project.
 The run claim serializes passes with gc --delete; gc refuses a held claim
 with the holder and recovery guidance instead of waiting.
 
@@ -7661,7 +7969,23 @@ 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.`
+  \`stim doctor\` notes a watchman footprint over 2 GiB.
+
+  A checkout that holds its linked worktrees inside it, such as
+  .worktrees/<name>, makes a watchman root there crawl every worktree's files,
+  node_modules and build output. \`stim doctor\` reports each such checkout
+  whose .watchmanconfig ignore_dirs does not exclude them, as
+  ${WATCHMAN_NESTED_WORKTREES}, and says when watchman watches it now.
+  \`stim doctor --fix\` merges the worktrees' shared parent (.worktrees) when
+  git tracks nothing in it, otherwise each worktree path, into that
+  checkout's .watchmanconfig and keeps every other key; it refuses a file
+  that is not a JSON object or whose ignore_dirs is not an array. Watchman
+  matches entries literally: \`.worktrees/\` or \`./.worktrees\` ignores
+  nothing. Commit the file. Watchman reads ignore_dirs only from a root's
+  .watchmanconfig, never from a global config, and only when it adds the
+  root, so an existing root needs \`watchman watch-del <root>\` before the
+  ignore applies. Doctor never runs watch-del or shutdown-server; a watch-del
+  plus a watchman restart frees the memory now.`
 		},
 		disk: {
 			summary: "disk usage, workspace build outputs, logs and device recordings, AVD and build-log sizes, the data partition, trimming the shared caches",
@@ -7918,7 +8242,8 @@ KEYS STIM READS
   ios.remote            "proxy", "eas", or a named approved Mac from
                         remote.machines, with the same meaning as --remote.
                         "auto" places on an approved Mac when this Mac is full or
-                        busy. Unset runs here. See lifecycle hosted-ios.
+                        busy. Unset runs here; "local" runs here even when a
+                        lower layer says otherwise. See lifecycle hosted-ios.
   ios.simslimProfile    a SimSlim JSON profile under the app directory,
                         at most 64 KiB. Install the
                         external tool once with
@@ -8060,8 +8385,23 @@ ${ANDROID_AVD_CONFIG_HELP.map((line) => `                          ${line}`).joi
                         means the debug keystore's fixed "android".
   android.remote        "proxy", "eas", or a named approved Mac in
                         remote.machines; "auto" places on an approved Mac when
-                        this Mac is full or busy. Unset runs here.
+                        this Mac is full or busy. Unset runs here; "local"
+                        runs here even when a lower layer says otherwise.
                         See lifecycle hosted-android.
+  remote.easFallback    true lets "auto" (ios.remote, android.remote or
+                        --remote auto) run the simulator or emulator on a
+                        billed EAS Simulator when this Mac is at its
+                        concurrency.maxDevices cap (or has runs queued) and no
+                        remote.machines Mac takes the run, instead of waiting
+                        or refusing with STIM_AT_CAPACITY. Default false. A
+                        busy Mac with a free slot never uses it. Stim checks
+                        first that the run could use --remote eas (eas-cli
+                        with simulator commands, eas simulator:availability,
+                        agent-device, the default slot, a reachable Metro);
+                        otherwise it waits or refuses as before. Machine or
+                        project scope; a committed value opts in everyone who
+                        runs the app. Only the user enables it. See lifecycle
+                        hosted-ios.
   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)
@@ -8267,12 +8607,26 @@ overrides the file:
 budget is off. A value of the wrong shape refuses start, ios and android with
 STIM_BAD_ARG. See \`guide lifecycle budget\` for what each limit reclaims.
 
+DEBUG LOGS ARE MACHINE-LEVEL AND OFF BY DEFAULT
+debug.logs STIM_DEBUG  default false. STIM_DEBUG=1 (or 0) overrides the setting
+for one command. While on, the CLI writes debug records to
+STIM_HOME/logs/debug/cli.ndjson (run_start, run_end, exec with the program name,
+duration and exit status but never arguments, remote_connect and
+remote_request with durations and codes); stim-server writes server.ndjson there
+and logs every request with its timings to its service log. The file rotates at about 8 MiB and keeps one previous
+generation, and nothing is sent anywhere. Keys named like a secret are redacted.
+  stim settings set debug.logs true --scope machine
+See \`guide logs\` for reading the files.
+
 AUTOMATIC MAINTENANCE IS MACHINE-LEVEL
-Report-only in this release: it measures and plans, and deletes or stops nothing.
+maintenance.mode on (the default) removes what gc would under the caps and
+floors below; report measures and plans and deletes nothing; off disables it.
 STIM_HOME and CI make the mode off unless STIM_MAINTENANCE is set.
+maintenance.keep is a project setting: pin a workspace so a pass never clears
+its build outputs or removes its worktree.
 See \`guide cleanup\` for checks, plans and log paths.
 
-${SETTINGS.filter((setting) => setting.key.startsWith("maintenance.") || /^caches\..*MaxGb$/.test(setting.key)).map((setting) => `  ${setting.key}  ${setting.env}  ${setting.default === void 0 ? "unset" : `default ${setting.default}`}
+${SETTINGS.filter((setting) => setting.key.startsWith("maintenance.") || /^caches\..*MaxGb$/.test(setting.key)).map((setting) => `  ${setting.key}  ${setting.env ?? "project setting"}  ${setting.default === void 0 ? "unset" : `default ${setting.default}`}
     ${setting.description}`).join("\n")}
 
 Maintenance uses the sysctl pressure level on macOS, with no memory signal
@@ -8296,8 +8650,9 @@ To show the booted simulator in Stim Desktop and open no simulator window:
 
   { "iosSimulatorApp": "stim-desktop" }
 
-Stim Desktop selects the workspace that owns the simulator and focuses that
-device. It only displays the simulator; it never boots or shuts it down.
+Stim Desktop keeps the current page and shows a launch card. Clicking Show
+opens the workspace that owns the simulator and focuses that device.
+It only displays the simulator; it never boots or shuts it down.
 When Stim Desktop is not running, Stim starts it without the command's
 \`STIM_HOME\`, so it reads the same Stim home as when you open it yourself.
 It shows only devices from that home: under another \`STIM_HOME\`, pick
@@ -8326,7 +8681,8 @@ headlessly and show it in Stim Desktop:
   { "androidEmulatorApp": "stim-desktop" }
 
 Stim then starts the emulator with \`-no-window -gpu host\` and opens
-\`stim-desktop://open?serial=<serial>\` in the background. Stim Desktop reads
+\`stim-desktop://open?serial=<serial>\` in the background. Stim Desktop shows a
+launch card and opens the emulator only when Show is clicked. It reads
 frames and sends input over the emulator's gRPC endpoint. The setting applies
 only when Stim boots the emulator: one that is already running keeps its
 current display until it next boots, and physical devices are unaffected.
@@ -8409,6 +8765,32 @@ simulator sessions on, by MagicDNS name with an optional serve port (default
   stim settings set remote.machines '["janics-mac-mini"]'
   stim doctor --fix
 
+Automatic membership is separate from approval. In Desktop Settings > Remote Macs,
+use Automatic builds and Automatic simulators for this Mac or a configured remote.
+The equivalent machine settings list the excluded members; both default to []:
+
+  stim settings set remote.buildPoolDisabled '["local"]'
+  stim settings set remote.devicePoolDisabled '["janics-mac-mini"]'
+  stim settings unset remote.buildPoolDisabled
+
+Use local for this Mac and exact remote.machines entries for remotes, including
+case and port. Names are not trimmed; unmatched entries exclude nothing. Copy the
+configured name or use Desktop's switches. Each pool
+must retain local or at least one configured remote already approved for that role.
+Offline approved members count as configured members, but placement still requires
+an available compatible host. Settings refuses removing the last member, including
+removing it from remote.machines. Disabling does not unpair a machine or stop a run.
+
+These settings apply only to new automatic work requested by this Mac. They do not
+change which work other requesters send to a host. Named placement and --remote-build
+local bypass membership; the default device placement without --remote auto remains
+local. Existing local and hosted device sessions keep their owner. Cache hits remain
+usable without compiling. If local is excluded, automatic placement cannot fall back
+to a local compile or boot; unavailable hosts and unsupported offloads refuse. Excluding
+local alone does not trigger billed EAS fallback; an existing explicit EAS opt-in still
+requires the physical device cap or queue condition. Restore membership before retrying or choose
+an explicit placement. Build and simulator memberships are independent.
+
 A remote Mac is used for a capability only after it grants that approval. Build
 and device-host approvals are separate: a Mac in the list that never granted
 one is not an error, it is not used for that capability, and doctor reports
@@ -8418,7 +8800,7 @@ DEVICE HOSTING
 Only \`doctor --fix\` asks for device-host access. A person on that Mac
 approves the printed id with \`stim-server devices grant <id> --device-host\`.
 A person can also run \`stim-server setup\` on the worker: one node, one ticket,
-one expiry, at most one request per capability, with per-grant y/N in a
+one expiry, at most one request per capability, with a per-grant Y/n question (Enter approves) in a
 terminal or \`--yes\` otherwise. Agents never run \`stim-server setup\` or
 approve requests. Setup never changes TCC or enables Funnel; an SSH-driven
 run is not offered. Without a terminal or --yes, setup refuses before installing
@@ -8500,7 +8882,7 @@ value is unset. Trimmed auto/local are case-insensitive. Machine names match
 configured names case-insensitively, with port 7443 when omitted; reports use
 the configured entry.
 
-  auto   follows remote.buildMode and keeps its local fallback behavior
+  auto   follows remote.buildMode, considering only enabled automatic pool members
   local  builds only on this Mac for this invocation
   name   requires a matching entry in remote.machines, already paired and
          approved for builds; ignores remote.buildMode and this Mac's load/slot gating
@@ -8539,7 +8921,7 @@ emulator debug build or a stim macos SwiftPM Debug build compiles:
          Mac's. A Mac too old to report its load counts only while every
          slot here is busy.
   force  on a remote Mac whenever one accepts it
-  off    always here
+  off    here when local remains enabled in the automatic build pool
 
 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
@@ -8563,10 +8945,12 @@ preferring the one that already holds this repository, then the least loaded,
 and moves to the next one in that order when a machine that offered fails the
 sync or refuses to start the build.
 For iOS the machine's Xcode and simulator SDK must match, and it needs an
-iPhone simulator on the target runtime. Its CocoaPods must match too, unless
+iPhone simulator on the target runtime. Its project-selected CocoaPods must match too, unless
 the app's Gemfile.lock pins CocoaPods: both Macs then run that version through
 bundler, so the machine needs only Bundler on its stim-server PATH and
-installs the pinned gems itself on the first build. For Android its JDK major
+installs the pinned gems itself on the first build. The comparison selects
+the app's .ruby-version when installed, with pod install's UTF-8 locale defaults.
+For Android its JDK major
 version must match, and its Android SDK must hold the NDK, build-tools and
 compile platform that the project's React Native version names in
 gradle/libs.versions.toml; Gradle and AGP come from the synced project. When
@@ -9157,7 +9541,14 @@ macos.arguments is an array of arguments passed directly to the executable:
 
 The plist must contain CFBundleIdentifier and CFBundleExecutable matching the
 product. Use a development plist without shared URL schemes or an update feed.
-Stim gives the copied bundle a workspace-specific identifier. SwiftPM resource
+Stim gives the copied bundle a workspace-specific identifier and name: it sets
+CFBundleDisplayName and CFBundleName on the copy to "<product> \u00b7 <label>",
+where label is the owned-device label (worktree and app directory names, cleaned
+to letters, digits, . _ -; at most 24 characters, cut with an ellipsis). The Dock,
+Cmd-Tab and lsappinfo show it, so several runs tell apart; the process name in
+System Events stays the executable. The project plist and the app's window titles
+are untouched. The name is displayName in the launch payload and status. Hosted
+(--remote) and offloaded builds get the same name. SwiftPM resource
 bundles and frameworks in the reported build directory are copied into it;
 macos.resources maps destinations under Contents/Resources to file or directory
 sources relative to the Swift Package directory, for example:
@@ -9181,26 +9572,48 @@ executables, including Stim Desktop's sim-fold helper, are not built.
 
   stim macos              # fixed SwiftPM Debug build, then launch
   stim macos --json       # one launch record; progress goes to stderr
+  stim macos --plan --json # validate the next build without running it
   stim status --json      # environments[].macos and build state
   stim logs --source build
   stim logs --errors
   stim stop               # stop this workspace's owned app and supervisor
 
-Each invocation stops its previous owned app, rebuilds and launches. SwiftPM
+Each invocation validates the project settings, development plist and resource
+entries before stopping its previous owned app, rebuilding and launching. SwiftPM
 keeps incremental outputs in the workspace's runtime directory under STIM_HOME.
+Every process running an app bundle from that directory is the workspace's
+owned app, including copies opened through LaunchServices (open, agent-device
+open). stim macos, stim stop, stim worktree remove and stim gc --delete stop all
+of them: SIGTERM, up to 5 s, then SIGKILL, and success only once each has
+exited. When an app cannot be verified or does not exit, stop reports
+STIM_MACOS_OWNER_UNVERIFIED or a failure, and removal keeps the workspace.
 Local stim macos starts the app in the background without activating it or
 changing focus: it sets STIM_BACKGROUND_LAUNCH=1 in the app's environment, which
-Stim Desktop honors. An app that activates itself at launch still takes focus.
+Stim Desktop honors, including for reopen events from open -g. An app that
+activates itself at launch or on reopen still takes focus.
 Hosted launches (macos --remote) do not set it.
-macOS artifacts are not cached. This prototype has no --plan, --slot, or reload command.
+macOS artifacts are not cached. This prototype has no --slot or reload command.
+--plan validates the Swift Package directory, macos settings, development plist
+and declared resources without building, signing, staging, stopping or launching
+an app, writing workspace state or claiming a build slot. It does not execute
+Package.swift, so it cannot validate the executable product or package dependencies.
+--remote-build is respected, including named-machine setup refusals; no worker
+is contacted and live worker availability is unknown. --remote is launch-only
+and refuses with --plan. The JSON plan has platform "macos", product and
+buildMachine; fingerprint, cacheKey, provider, prebuild, outcome and expectedMs
+are null, cacheHit and cacheSkipped are false, and basis is 0. SwiftPM decides
+incremental compile work when a build runs; the plan predicts no cache outcome
+or duration. Desktop checks automatically while build details are visible,
+reusing a completed build or check for 60 seconds and skipping running builds.
 A failed build records its error and compiler output without launching an app.
 While it runs, stim status --json reports it as environments[].build with
 platform "macos": phase prepare, compile, install, then launch, and during
 compile detail.unit "steps" with SwiftPM's [done / total] counts (fetching and
 planning are detail.step "configure"). It has no cache lookup, so outcome and
 plannedPhases are null; finished runs and their phase times are in
-environments[].builds.macos. An offloaded build reports the worker's steps the
-same way.
+environments[].builds.macos, where phases includes launch once the launch step finishes
+and compileSteps is SwiftPM's step total. An offloaded build reports the worker's
+steps the same way.
 Runtime stdout and stderr become client records; build output becomes build
 records, all with platform "macos". Unexpected app exits are error records.
 Stim runs the app with NSUnbufferedIO=YES, so Swift print output arrives per
@@ -9217,7 +9630,10 @@ refuse before stopping the app or changing its build record. See stim guide erro
 
 With remote.build auto, remote.buildMode places these SwiftPM Debug builds:
 auto builds here while this Mac has capacity, force uses an approved build
-machine when one accepts, and off always builds here. Configure remote.machines
+machine when one accepts, and off builds here when local remains in the automatic
+build pool. remote.buildPoolDisabled excludes members from automatic placement,
+including its local fallback. Explicit local or named placement bypasses membership.
+Configure remote.machines
 and approve build access as described in stim guide settings. The worker needs
 matching Stim, CPU architecture, Xcode and macOS SDK, plus network access to
 fetch package dependencies the first time. It keeps SwiftPM dependencies in a
@@ -9535,295 +9951,153 @@ 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_REPO = "appandflow/stim-tutorial";
+const TUTORIAL_BUNDLE_ID = "dev.stim.tutorial";
 const TUTORIAL_RESTART_PROMPT = "Restart the Stim tutorial.";
+/**
+* The requests Stim Desktop offers to copy, written the way a developer would ask. {base}, {tour}, {worktrees} and
+* {machine} are filled in by Desktop. Only the first and last name a guide section, which holds the folder and cleanup safety rules.
+*/
+const TUTORIAL_ASKS = {
+	begin: `Clone ${TUTORIAL_REPO} into {base} and install its dependencies, then run stim doctor for iOS there so Stim registers it. Use a fresh folder: if {base} already exists or is inside another git repository, stop and ask me for another folder, and never git add in my own repo. Follow stim guide tutorial run.`,
+	agent: "Open the app on the iOS simulator, take a screenshot and confirm the title color.",
+	machine: "Build the app for iOS on {machine} with stim instead of on this Mac. Do not approve or pair anything.",
+	finish: "I'm done with these experiments in {base} and don't need the changes. Stop the apps and remove the worktrees {worktrees}, and keep the clone. Follow stim guide tutorial finish.",
+	share: `Open a pull request to ${TUTORIAL_REPO} with my title color change, and include a screenshot of it running in the simulator. See stim guide tutorial share.`,
+	retry: "The first iOS build of the tutorial app in {tour} failed. Find out why and run it on iOS again."
+};
 const TUTORIAL_STEPS = [
 	{
 		id: "begin",
-		title: "Create the tutorial",
+		title: "Get the Test App",
 		who: "agent",
 		optional: false,
-		prompt: TUTORIAL_PROMPTS.begin,
+		ask: TUTORIAL_ASKS.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: []
+		commands: []
 	},
 	{
 		id: "build",
-		title: "First iOS build",
+		title: "Make a Change",
 		who: "you",
 		optional: false,
-		prompt: null,
+		ask: 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"
-		]
+		commands: []
 	},
 	{
-		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",
+		id: "parallel",
+		title: "Change It Again in Parallel",
 		who: "you",
 		optional: false,
-		prompt: null,
+		ask: null,
 		section: null,
-		manual: ["stim status"]
+		commands: []
 	},
 	{
-		id: "logs",
-		title: "App logs",
+		id: "device",
+		title: "Live View and Control",
 		who: "you",
-		optional: false,
-		prompt: null,
+		optional: true,
+		ask: null,
 		section: null,
-		manual: ["stim logs --errors", "stim logs --grep '\\[stim:tutorial\\]'"]
+		commands: ["stim status"]
 	},
 	{
 		id: "agent",
-		title: "Agent actions and replay",
+		title: "Agent Actions and Replay",
 		who: "agent",
-		optional: false,
-		prompt: TUTORIAL_PROMPTS.agent,
-		section: "agent",
-		manual: [
+		optional: true,
+		ask: TUTORIAL_ASKS.agent,
+		section: null,
+		commands: [
 			"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 open ${TUTORIAL_BUNDLE_ID} --platform ios --udid {udid}`,
 			"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: "logs",
+		title: "App Logs",
+		who: "you",
+		optional: true,
+		ask: null,
+		section: null,
+		commands: ["stim logs --errors", "stim logs --grep stim:tutorial"]
 	},
 	{
 		id: "phone",
-		title: "Watch on your phone",
+		title: "Watch on Your Phone",
 		who: "you",
 		optional: true,
-		prompt: null,
+		ask: null,
 		section: null,
-		manual: []
+		commands: []
 	},
 	{
 		id: "machine",
-		title: "Build on another Mac",
+		title: "Build on Another Mac",
 		who: "both",
 		optional: true,
-		prompt: TUTORIAL_PROMPTS.machine,
-		section: "machine",
-		manual: ["cd \"{tour}\"", "stim ios --remote-build \"{machine}\" --no-build-cache"]
+		ask: TUTORIAL_ASKS.machine,
+		section: null,
+		commands: ["cd \"{tour}\"", "stim ios --remote local --remote-build \"{machine}\" --no-build-cache"]
+	},
+	{
+		id: "share",
+		title: "Share Your Finish",
+		who: "you",
+		optional: true,
+		ask: TUTORIAL_ASKS.share,
+		section: "share",
+		commands: [
+			"cd \"{tour}\"",
+			"git commit -am \"Tutorial change\" -m \"Build <time>, second build cache <hit or miss>\"",
+			"xcrun simctl io {udid} screenshot finish.png",
+			`gh repo fork ${TUTORIAL_REPO} --remote --remote-name fork`,
+			"git push -u fork HEAD",
+			`gh pr create --repo ${TUTORIAL_REPO} --fill --attach "finish.png#The change running in the simulator"`
+		]
 	},
 	{
 		id: "finish",
-		title: "Finish and archive",
+		title: "Finish and Archive",
 		who: "agent",
 		optional: false,
-		prompt: TUTORIAL_PROMPTS.finish,
+		ask: TUTORIAL_ASKS.finish,
 		section: "finish",
-		manual: [
-			"git -C \"{tour}\" checkout -- theme.js",
+		commands: [
 			"cd \"{tour}\"",
 			"stim stop",
+			"cd \"{second}\"",
+			"stim stop",
 			"cd \"{base}\"",
-			"stim worktree remove \"{tour}\""
+			"stim worktree remove \"{tour}\"",
+			"stim worktree remove \"{second}\""
 		]
 	}
 ];
 //#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.`;
+const paths = `Use {base} = ~/stim-tutorial unless the user named another folder. Expand ~
+to the absolute home path when substituting inside quotes. Keep the tutorial
+outside the user's own projects.`;
+const local = `The tutorial runs on this Mac. Every time you run the tutorial app on iOS
+from a worktree of {base}, use stim ios --remote local --remote-build local,
+even when the user's settings would place the device or the build on another
+Mac. Only an explicit request to build on another Mac changes the build, with
+stim ios --remote local --remote-build "<machine>"; the device stays here.`;
 function commands(id) {
-	return TUTORIAL_STEPS.find((step) => step.id === id).manual.join("\n");
+	return TUTORIAL_STEPS.find((step) => step.id === id).commands.join("\n");
 }
 //#endregion
 //#region src/guide/index.ts
 const TOPICS = {
 	agent: agent_default,
+	api: api_default,
 	facts,
 	metro: metro_default,
 	ports: ports_default,
@@ -9835,260 +10109,160 @@ const TOPICS = {
 	web: web_default,
 	macos: macos_default,
 	tutorial: {
-		summary: "An iOS tutorial: isolated worktree, builds, devices, logs, agent actions, and cleanup",
+		summary: "A cloned test app: a first build, a second change in parallel with a cache hit, 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.
+The tutorial clones ${TUTORIAL_REPO}, a tiny Expo app, into {base}; the clone is
+never run or removed. The user then asks for a visual change, and for another
+change while the first builds. Each change runs in its own linked worktree of
+{base}, so each has its own simulator and Metro port, and the second worktree's
+first iOS build reuses the first one's native build. Only the clone, the
+optional share and the cleanup need this guide: the changes are ordinary
+requests, so follow stim guide agent for them, and check each change on the
+device.
 
-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.
+${local}
 
-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.
+"Follow stim guide tutorial run" means stim guide tutorial run.
+"Follow stim guide tutorial finish" means stim guide tutorial finish.
+"${TUTORIAL_RESTART_PROMPT}" means stim guide tutorial restart.
 
 ${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.`,
+Never pair phones, approve machines, or grant access on the user's behalf.
+For commands to type yourself, read stim guide tutorial manual.`,
 		sections: {
 			run: {
-				summary: "Create or reuse the app, warm a tour worktree, and build on iOS",
+				summary: "Clone the test app into a fresh folder and install its dependencies",
 				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.
+Folder safety: use a fresh folder. If {base} exists, stop and ask the user for
+another folder; never overwrite or delete it. First check the parent folder:
+create it if absent, then run git -C <parent> rev-parse --is-inside-work-tree.
+If that succeeds, the folder is inside another repository: stop and ask the
+user for another folder. Never git add in the user's repo.
 
-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:
+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
+  git clone https://github.com/${TUTORIAL_REPO}.git stim-tutorial
 
-Enter the base folder. Run stim guide tutorial app, write its three app files
-verbatim, and append its .gitignore lines. Then run:
+Check that app.json in the clone has expo.extra.stimTutorial equal to
+${TUTORIAL_VERSION}. If it does not, report the mismatch and stop; the user needs a newer Stim.
+Enter the clone and install its dependencies (npm ci) so the worktrees made for
+the changes inherit them, then run stim doctor --platform ios there: it registers
+the clone with Stim so Stim Desktop sees it, and builds or boots nothing. Do not
+run the app: the clone is only the base for the user's changes and is never removed.
+Report the findings of stim doctor and do not act on them: no SimSlim install, no
+--fix, nothing that changes the machine during the tutorial. On npm or network failure, report stderr
+and stop.
 
-  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"
+${local}
 
-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 remote Mac 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: () => `REMOTE MAC (OPTIONAL)
-
-${paths}
-
-Proceed only when the user names an approved remote Mac. 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 --remote-build 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}".`
+PAUSE: end the turn. Tell the user to ask for a visual change next, such as
+making the title purple, in their own words. Each change runs in a new linked
+worktree of {base} (stim guide agent), and its first iOS build takes a few
+minutes.`
 			},
 			finish: {
-				summary: "Revert the tutorial edit, stop, and remove only the tour worktree",
+				summary: "Stop and remove the two tutorial worktrees, keeping the clone",
 				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:
+The worktrees to remove are the two the tutorial tracked: the linked
+worktrees of {base} made for the user's changes. The finish request names them
+as {tour} and {second}. Never touch any other worktree, an earlier tutorial
+clone, or the clone itself. For each, stop from its path, then remove it from
+the clone:
 
 ${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:
+Use a plain remove first. The user's finish request says they do not need the
+changes, which is the consent stim guide agent asks for before worktree remove
+--force, for exactly those two paths: if the plain remove refuses one of them
+only because of uncommitted changes or commits found nowhere else, remove that
+worktree with --force. Never use --force on the clone or on any other
+worktree, and on any other refusal report it and stop. Keep the clone. Print
+these optional cleanup commands for the user; do not run them:
 
   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.`
+If archive is enabled, tell the user the worktrees appear under Archived in
+Stim Desktop. With archive disabled, report removal without promising an
+archive. Without Desktop, inspect stim status --json for the removed
+environments. End the turn.`
+			},
+			share: {
+				summary: "Optionally open a public pull request with a screenshot of the change",
+				body: () => `SHARE YOUR FINISH (OPTIONAL)
+
+Only on the user's explicit request, which the share prompt is, and before the
+finish step removes the worktrees. The pull request is public: the user's GitHub
+name and change appear on ${TUTORIAL_REPO}, and a bot replies and closes it. It
+needs gh signed in. Never open it unprompted or from any other step.
+
+Work from the worktree holding the user's change, {tour}. Commit the change
+there, fork the repository and push the branch to the fork, since the user has
+no write access:
+
+  gh repo fork ${TUTORIAL_REPO} --remote --remote-name fork
+  git push -u fork HEAD
+
+Screenshot: take a PNG under 1 MB of the app showing the change, with
+agent-device screenshot when it is installed, otherwise
+xcrun simctl io <ios.udid> screenshot finish.png, using the udid of that
+worktree from stim status --json, never booted. If the app is no longer
+running, run it again from the branch first.
+
+Open the pull request with gh pr create --repo ${TUTORIAL_REPO} --fill. Put one
+short line with the build time and whether the second worktree's first iOS build
+was a cache hit, when you know them from stim status --json or stim stats, in the
+commit message body (git commit -m "<title>" -m "<that line>"), so --fill carries it
+into the pull request body.
+
+Attach the screenshot with gh: gh pr create --attach "finish.png#The change
+running in the simulator" uploads the image and appends it to the body. gh
+2.99.0 (2026-09-01) has --attach; confirm with gh pr create --help rather than
+guessing a version. When gh has no --attach, commit the PNG on the PR branch as
+finish/<github-login>.png before pushing and embed it in the body with a
+relative link: ![the change](finish/<github-login>.png).`
 			},
 			restart: {
-				summary: "Remove the existing tour safely and repeat from the worktree step",
+				summary: "Start the tutorial again without removing anything",
 				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.`
+For "${TUTORIAL_RESTART_PROMPT}", remove nothing: the user may still want the
+earlier worktrees. Finish only removes the pair named in its request, so leave
+any earlier worktrees and tell the user they stay until they ask for each by
+path; never use --force for them. Reuse the clone at {base} only if its
+stimTutorial marker equals ${TUTORIAL_VERSION}; otherwise follow stim guide
+tutorial run into a fresh folder. Pause as run instructs. Stim Desktop starts
+over: only worktrees and builds after the restart count.`
 			},
 			manual: {
-				summary: "Commands for every step, including heredocs for the app files",
+				summary: "The commands behind each step, for typing yourself",
 				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.`
+Replace {base}, {tour} and {second} with absolute paths: {base} is the clone,
+{tour} the first worktree and {second} the second. For Agent Actions, replace
+{stateDir} with agentDevice.stateDir from stim ios or stim status --json and
+{udid} with the workspace's ios.udid. For the optional machine step, replace
+{machine} with a machine you have already approved, or skip it. Clone with git
+clone https://github.com/${TUTORIAL_REPO}.git into a fresh folder outside any
+repository. Each change runs in its own worktree of that clone (stim guide
+agent); the clone itself is never run. Run each worktree on iOS with
+stim ios --remote local --remote-build local so it stays on this Mac.
+
+${TUTORIAL_STEPS.map((step) => `${step.title}${step.optional ? " (optional)" : ""}\n\n${step.commands.length ? `\`\`\`sh\n${step.commands.join("\n")}\n\`\`\`` : "Ask your agent in your own words, or observe this step in Stim Desktop."}`).join("\n\n")}
+
+Finish removes only the two tutorial worktrees, never the clone; stim guide tutorial finish says when --force is allowed for them.`
 			}
 		}
 	}
@@ -10172,7 +10346,7 @@ function renderIndex(version) {
 	return lines.join("\n");
 }
 function guideCommand(program, version, status = (running) => guideStatus({
-	projectRoot: findProjectRoot$1(process.cwd()),
+	projectRoot: findProjectRoot(process.cwd()),
 	running
 })) {
 	program.command("guide [topic] [section]").description("Print reference documentation for THIS version of Stim (topics: " + topicNames().join(", ") + "). A topic with sections prints its section index; name a section to print only it, e.g. `stim guide errors STIM_NO_METRO` or `stim guide lifecycle builds`. Generated by the binary, so it cannot drift from the installed CLI.").action(async (topic, section) => {