stim 1.18.0 → 1.19.0

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

@@ -1,8 +1,8 @@
-import { s as findProjectRoot$1 } from "./project-C3ChRLZy.mjs";
-import { t as RECENT_LAUNCH_MS } from "./status-Dcr0Qexd.mjs";
-import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-CQyMElEP.mjs";
-import { t as guideStatus } from "./guide-status-Bhf9SJXc.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 = {
@@ -1432,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:
@@ -1749,7 +1750,10 @@ 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,
@@ -1942,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,
@@ -1952,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:
@@ -2252,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.
@@ -2600,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
@@ -2625,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.
@@ -2915,18 +2930,22 @@ remote Mac and a named --remote target write none:
   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 for a device), candidates [{ machine, code,
+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. Choice codes for a build: placed, named,
+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. Machine names appear in these records;
+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
@@ -3440,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
@@ -3888,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\`.`
@@ -4175,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",
@@ -4959,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
@@ -5125,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.
@@ -5136,9 +5216,24 @@ 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.
@@ -5899,8 +5994,9 @@ PREDICTING THE NEXT BUILD (--plan)
   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, or ios.remote or android.remote set to eas or proxy, refuses
-  with STIM_BAD_ARG. Without --eas-profile an Android plan also
+  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.
 
@@ -7873,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",
@@ -8130,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
@@ -8272,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)
@@ -8522,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
@@ -8552,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.
@@ -8635,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
@@ -8726,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
@@ -8765,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
@@ -9416,18 +9572,39 @@ 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
@@ -9453,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
@@ -9771,290 +9951,147 @@ 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"
-		]
+		commands: []
 	},
 	{
-		id: "sidebar",
-		title: "Workspace in Sidebar",
+		id: "build",
+		title: "Make a Change",
 		who: "you",
 		optional: false,
-		prompt: null,
+		ask: null,
 		section: null,
-		manual: []
+		commands: []
 	},
 	{
-		id: "build",
-		title: "First iOS Build",
+		id: "parallel",
+		title: "Change It Again in Parallel",
 		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"
-		]
-	},
-	{
-		id: "rebuild",
-		title: "Rebuild from Cache",
-		who: "agent",
-		optional: false,
-		prompt: TUTORIAL_PROMPTS.rebuild,
-		section: "rebuild",
-		manual: [
-			"cd \"{tour}\"",
-			"stim ios",
-			"stim status --json"
-		]
+		commands: []
 	},
 	{
 		id: "device",
 		title: "Live View and Control",
 		who: "you",
-		optional: false,
-		prompt: null,
-		section: null,
-		manual: ["stim status"]
-	},
-	{
-		id: "logs",
-		title: "App Logs",
-		who: "you",
-		optional: false,
-		prompt: null,
+		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",
 		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",
 		who: "you",
 		optional: true,
-		prompt: null,
+		ask: null,
 		section: null,
-		manual: []
+		commands: []
 	},
 	{
 		id: "machine",
 		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",
 		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
@@ -10072,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.
-
-For a new app, first check the selected parent folder: create it if absent,
-then run git -C <parent> rev-parse --is-inside-work-tree. If it succeeds, the
-folder is inside another repository: stop and ask the user for another folder.
-Never git add in the user's repo. Then, from the parent folder, run:
-
-  npx --yes create-expo-app@${TUTORIAL_PINS.createExpoApp} stim-tutorial --template ${TUTORIAL_PINS.template} --no-install --no-agents-md --yes
-
-Enter the base folder. Run stim guide tutorial app, write its three app files
-verbatim, and append its .gitignore lines. Then run:
-
-  npm install --prefer-offline
-  npm pkg set scripts.ios="expo run:ios" scripts.android="expo run:android"
-  git init
-  git add -A
-  git -c user.name=Stim -c user.email=stim@localhost -c commit.gpgsign=false commit -m "Stim tutorial"
-
-On reuse, run git rev-parse --show-toplevel in the base folder before adding
-a worktree; if it does not equal the base folder, the folder is inside another
-repository: stop and ask the user for another folder.
-
-Set the scripts before the commit because Expo prebuild rewrites them to
-expo run:ios and expo run:android; otherwise the dirty worktree blocks removal.
-On npm or network failure, report stderr and stop.
-
-From the base folder, add the tour worktree and run:
-
-  git worktree add -B stim-tutorial/tour "{tour}" HEAD
-  cd "{tour}"
-  stim worktree warm
-  stim guide agent
-
-Apply the guide agent doctor rule before native work: if its STATUS block
-says doctor is due, run stim doctor --platform ios from the tour worktree and
-resolve its findings. No STATUS block means doctor is current. Then run:
-
-  stim start
-  stim ios
-
-Tell the user the first build can take about four minutes on a cold cache.
-Relay the Open in Stim Desktop link printed by stim ios once.
-
-PAUSE: end the turn. Ask the user to look at the Build section, then the
-device, then Logs in Stim Desktop. Without Desktop, use stim status,
-stim stats, and stim logs --errors. Give the next prompt:
-"${TUTORIAL_PROMPTS.rebuild}". Leave the workspace running.`
-			},
-			app: {
-				summary: "Pinned template, verbatim app files, and .gitignore additions",
-				body: () => `TUTORIAL APP
-
-create-expo-app: ${TUTORIAL_PINS.createExpoApp}
-Template: ${TUTORIAL_PINS.template}
-Write the app files verbatim. Append the .gitignore lines to the template's
-existing file. App log lines start with [stim:tutorial]. Crash me raises an
-uncaught JavaScript error, and Slow request times a local three-second timer;
-Stim does not capture native network requests.
-
-${Object.entries(TUTORIAL_FILES).map(([name, content]) => `${name}\n\n\`\`\`${name.endsWith(".json") ? "json" : name.endsWith(".js") ? "js" : "text"}\n${content}\`\`\``).join("\n\n")}`
-			},
-			rebuild: {
-				summary: "Repeat the iOS build and explain the cache result",
-				body: () => `REBUILD
-
-${paths}
-
-Run the same build again, never with --no-build-cache:
-
-${commands("rebuild")}
-
-Read this workspace's environments[].lastBuilds.ios.cacheHit from
-stim status --json, and the miss reason printed by stim ios. Explain a local or remote hit, or the actual miss
-reason when cacheHit is false. A repeat run can miss; report the evidence.
-
-PAUSE: end the turn. Point at the Build section and cache badge, or stim stats.
-Ask the user to open the device's live view and tap Log an error; without
-Desktop use the simulator. Then inspect Logs or stim logs --errors. Crash me
-and Slow request are optional: the former shows a red box, the latter prints
-a timing line. Give the next prompt: "${TUTORIAL_PROMPTS.agent}".`
-			},
-			agent: {
-				summary: "Record a tap and screenshot, replay it, and inspect agent logs",
-				body: () => `AGENT ACTIONS
-
-${paths}
-
-Set {stateDir} to this workspace's agentDevice.stateDir from stim ios or
-stim status --json. Replace <ios.udid> with this workspace's ios.udid from
-stim status --json. Use that exact owned simulator, not a guessed one.
-Run from the tour worktree:
-
-${commands("agent").replace("read -r iosUdid", "iosUdid=\"<ios.udid>\"")}
-
-Use --save-script=tutorial.ad with the equals sign: agent-device treats a
-separate path as a URL and refuses. The dismiss-overlay step clears a red box that would cover the buttons.
-Replay with the same --platform and --udid so its steps reach the agent log.
-Remove the target-v1 evidence and dismiss-overlay lines before replay: replaying
-them can fail with REPLAY_DIVERGENCE on the recorded button identity.
-The scripts and screenshot stay in the tour worktree and are git-ignored.
+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.
 
-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}
+Then, from the parent folder, run:
 
-Set TITLE_COLOR in theme.js to '#7c3aed' (purple). Wait a few seconds for
-Fast Refresh, without reloading the app:
+  git clone https://github.com/${TUTORIAL_REPO}.git stim-tutorial
 
-${commands("refresh")}
+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.
 
-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.
+${local}
 
-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.`
 			}
 		}
 	}
@@ -10409,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) => {