stim 1.26.0 → 1.28.0

package/dist/{guide-D7K0X6KG.mjs → guide-C4I46XAk.mjs}

@@ -1,8 +1,8 @@
-import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-CosW5X-S.mjs";
-import { i as findProjectRoot$1 } from "./project-BUu6Is4k.mjs";
-import { h as RECENT_LAUNCH_MS } from "./eas-session-ledger-B5vygTiD.mjs";
-import { o as guideStatus, t as WATCHMAN_NESTED_WORKTREES } from "./doctor-watchman-BStK05nt.mjs";
-import "./status-watch-B5wDIH_o.mjs";
+import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-CY5JZlNN.mjs";
+import { i as findProjectRoot$1 } from "./project-Sui52ywT.mjs";
+import { h as RECENT_LAUNCH_MS } from "./eas-session-ledger-CBFo_Uo1.mjs";
+import { o as guideStatus, t as WATCHMAN_NESTED_WORKTREES } from "./doctor-watchman-BTW82PDC.mjs";
+import "./status-watch-BmsPqYSU.mjs";
 import { SETTINGS, SETTINGS_SCHEMA_URL, TUTORIAL_VERSION } from "@stim-cli/core/state";
 import chalk from "chalk";
 //#region src/guide/agent.ts
@@ -297,16 +297,20 @@ reserved named ports, even outside the workspace. Read guide ports before use.
 
 Ask the user before these actions:
 
-- worktree remove, because it deletes the worktree and gives up its owned
-  device. It works with any linked worktree, warmed or not, without requiring
+- worktree remove of a worktree you did not create, because it deletes the
+  worktree and gives up its owned device. It works with any linked worktree, warmed or not, without requiring
   a Stim registry entry. Git-created branches are kept; a branch with an
   existing Stim ownership record is deleted only when it has no unique commits.
 - worktree remove --force, because it also discards uncommitted and untracked
   files.
 - gc --delete, because it deletes orphaned resources, removes clean linked
   worktrees whose branch or pull request is merged (or whose pull request
-  was closed), and clears the build outputs of every
-  workspace not in use. Run stim gc --json first and show
+  was closed), and lightens every workspace that is not building and ran
+  no ios, android or macos command in the last 15 minutes, a running dev
+  server included, by clearing its build outputs and its git-ignored
+  in-tree build directories, and deletes node_modules and ios/Pods of idle
+  linked worktrees, which the next start, ios or android restores with
+  worktree warm. Run stim gc --json first and show
   the user the entries its sections list (guide facts gc). gc --delete
   --cache all empties the shared build caches and those outputs instead, and
   gc --delete --cache workspaces clears only the outputs; both inspect
@@ -327,8 +331,10 @@ Ask the user before these actions:
 
 LEAVE THE MACHINE CLEAN
 
-Run stim stop when you pause or finish a task, and stim worktree remove once
-it is merged or abandoned. Never create a simulator or emulator by hand;
+Run stim stop when you pause or finish a task, and stim worktree remove on
+the worktree you created once its work is merged or abandoned. Keep scratch
+files, test output and downloads outside the worktree: a stray untracked file
+blocks that removal, and automatic cleanup then has to archive it. Never create a simulator or emulator by hand;
 every device comes from Stim. Before starting a new workspace, check stim
 status for an idle workspace to reuse and confirm capacity headroom instead of
 adding another. Never quit Device Hub or Simulator.app: on Xcode 27
@@ -1335,7 +1341,8 @@ ON FAILURE
   An \`ios\` or \`android\` run that \`stim stop\` or Ctrl-C interrupted
   reports STIM_CANCELLED and exits 130. A
   run that exits on the interrupt at once (a second Ctrl-C, or Ctrl-C with no
-  build tool or SimSlim to stop) exits 130 with no payload.
+  build tool, SimSlim, launch readiness wait or hosted app delivery to stop)
+  exits 130 with no payload.
 
   \`stop --json\` prints { root, ok, supervisor, collectors, metro, device,
   port, metroTunnel, releasedLeases, macos? }. macos is { status: stopped | failed,
@@ -1532,7 +1539,8 @@ RULES
                   why) or "failed" (detail says why and what to retry).
                   kind: device, parkedDevice, parkedHostedDevice, idleDevice,
                   deviceRecord,
-                  workspaceOutputs, recording, workspaceDirectory, project,
+                  workspaceOutputs, worktreeDependencies, recording,
+                  workspaceDirectory, project,
                   buildLock, buildSlot, deviceLease, easSession, worktree,
                   cache, gradleVersion, tempLeftover (one "done" labelled
                   with the TMPDIR it cleared, plus a "kept" or "failed" per
@@ -1600,9 +1608,9 @@ RULES
                               else null. buildState is { bytes, dirs:
                               { path, bytes } } for the in-tree build and
                               dependency directories automatic maintenance
-                              clears (ios/build, android/app/build,
-                              android/build, android/.gradle, .build,
-                              node_modules, ios/Pods, at the root, a
+                              clears (android/app/build, android/build,
+                              android/.gradle, .build, node_modules,
+                              ios/Pods, at the root, a
                               project root, or apps/* and packages/* for
                               build directories) and a root .pnpm-store,
                               paths relative to the worktree, largest
@@ -1701,18 +1709,29 @@ RULES
                               Metro, client and device logs over twice the
                               8 MiB cap; willTrim marks the ones it would
                               trim
+    worktreeDependencies    { path, willDelete, detail }  node_modules and
+                              ios/Pods of linked worktrees; willDelete marks
+                              the ones --delete would lighten, and detail
+                              says why the others stay. Sizes are not
+                              measured: APFS clones make them misleading
     recordings              { dir, projectRoot, bytes, deleteBytes,
                               willDelete, withWorkspace, reason, detail }
                               recordings/ of each workspace; deleteBytes is
                               what --delete would remove; withWorkspace
                               marks those of a gone workspace, removed with
                               its workspace directory
-    workspaceBuildOutputs   { dir, projectRoot, bytes, idleDays, willClear,
-                              reason, detail }  derived-data, gradle-build,
-                              android-cas, cache-provider, macos/build,
-                              macos/<Product>.app and macos/staging-* of each
-                              workspace; willClear marks the ones --delete
-                              would clear; --cache workspaces omits the
+    workspaceBuildOutputs   { dir, projectRoot, inTreeDirs, bytes, idleDays,
+                              willClear, reason, detail }  derived-data,
+                              gradle-build, android-cas, cache-provider,
+                              macos/build, macos/<Product>.app and
+                              macos/staging-* of each workspace; inTreeDirs
+                              lists the project's android/app/build,
+                              android/build,
+                              android/.gradle and .build that --delete
+                              clears with them, every file in them
+                              ignored by git and none tracked, and
+                              bytes includes them; willClear marks the ones
+                              --delete would lighten; --cache workspaces omits the
                               directories that --delete removes whole (dead
                               projects and orphanedWorkspaces), and --cache
                               all does not
@@ -1771,11 +1790,13 @@ RULES
                               bytes, willDelete, kept }] } | null  ignored
                               directories worktree remove moved out of a
                               worktree into $STIM_HOME/trash before git
-                              removed it. bytes is null while a removal is
+                              removed it, and paths worktree warm moved out
+                              of a copy. bytes is null while a removal is
                               deleting the entry. kept names the live or
                               unresolved ownership claim, the missing or
                               invalid trash.json, or the worktree that
-                              still exists, that keeps a directory;
+                              still exists (not for a warm entry), that
+                              keeps a directory;
                               --delete deletes the rest, only remove-*
                               entries with a valid trash.json. null when the
                               trash is empty or under any --cache scope
@@ -1813,8 +1834,8 @@ RULES
   reason is null for an entry --delete acts on, and otherwise a stable code
   to branch on; detail is the text line, for the user. Never parse detail.
   A linked worktree's detail is never null.
-    workspaceBuildOutputs   unresolved | in-use | last-use-unknown |
-                            recently-used
+    workspaceBuildOutputs   unresolved | locked | lock-unknown | in-use |
+                            last-use-unknown | recently-used
     workspaceLogs           unresolved | in-use | collector
     recordings              unresolved | retained | recently-recorded
     memory                  in-use | busy | unknown | build-running |
@@ -2273,6 +2294,10 @@ RULES
     build: ios compile on janics-mac-mini (build, 2m10s), 3m05s elapsed
     build: ios launch (bundling JS 45%, 12s), 58s elapsed
 
+  The machine keeps every native build run, not only the latest, in
+  $STIM_HOME/builds/builds.ndjson (newest 500), read with
+  \`stim logs --source builds --json\` (\`guide logs\`, BUILD LEDGER).
+
   An environment with a recorded run also carries lastBuilds, each
   platform's most recent ios or android run, finished or failed:
 
@@ -2455,7 +2480,35 @@ RULES
 
   capacity.committedMb sums memoryMb; in a \`status --watch --json\` line each
   figure, including an environment's memoryMb, is held on its own (see
-  \`guide lifecycle\`), so the sums can differ from what they sum. The memory budget plans before a boot
+  \`guide lifecycle\`), so the sums can differ from what they sum.
+
+  capacity.load is always present. capacity.builds is present only while
+  concurrency.maxBuilds is set, and capacity.devices only while
+  concurrency.maxDevices is set (see \`guide lifecycle concurrency\`):
+
+  load     { cpus, loadPerCore, busyAt, limit, state }. loadPerCore is the
+           5-minute load average divided by cpus, to one decimal. busyAt is
+           server.maxLoadPerCore (\`guide settings\`). state is free under
+           busyAt, busy at or over it, where automatic placement prefers
+           another machine, or holding at or over limit. limit is null
+           because no setting sets it yet, so state is never holding.
+
+  builds   { max, inUse, holders: [{ slot, workspace, client, since,
+           unresolved? }] }. inUse counts the slots below max that a new
+           build cannot take. workspace is the root of the local build in
+           the slot; client is the device id of the client whose offloaded
+           build this machine runs in it. An unresolved slot has a claim
+           whose holder Stim cannot identify; both are null, and the slot
+           stays in use until that claim is removed.
+  devices  { max, inUse, unknown?, holders: [{ platform, label, workspace,
+           slot, booting? }] }, the owned devices the cap counts: booted or
+           booting stim simulators, owned emulators adb lists, and boots in
+           progress. label is the label of the workspace that records the
+           device, with its device slot; for a device no workspace records,
+           label is its name and workspace and slot are null. inUse is null
+           and unknown says why when the devices could not be listed.
+
+  The memory budget plans before a boot
   and always uses the estimate. What is using CPU and memory now is the
   top-level machine section:
 
@@ -2550,9 +2603,10 @@ 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 machine; auto may use <machines>"; absent otherwise
+  placement     with ios.remote or android.remote set to auto, remote,
+                remote-only or a Mac, where the plan assumes the device runs:
+                "on <machine>" or "this machine; <word> 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
@@ -2707,9 +2761,9 @@ BUILD PLACEMENT (\`offload\`)
   decision is "here", "offloaded", or "fell-back" (it tried a remote machine
   and built here). reason is why: the run's \`placement:\` reason, such as
   "load 0.6/core, 1 of 3 build slots busy here" (auto keeps the build here
-  while this machine has room) or "remote.buildMode is off" (which prints no line),
+  while this machine has room) or "--remote-build local" (which prints no line),
   or for a fallback the cause, prefixed by the machine it concerns, such as
-  "mini: no less loaded (load 1.2/core there, 0.6/core here)". buildMs is the compile here, or the offloaded build's
+  "mini: saturated: load 2.4/core there, at or above 2/core". buildMs is the compile here, or the offloaded build's
   total (offer, sync, build and fetch); localEstimateMs is this project's
   last cold build here before the run. A run that hits the cache or waits
   for another workspace's build compiles nothing and records none.
@@ -2753,19 +2807,19 @@ comes from \`start --remote\`, eas/proxy in \`ios.remote\`, or \`android.remote\
 
 HOSTED IOS METRO
   ios --remote <machine> keeps Metro local and needs no start --remote.
-  The supervisor watches private gateway requests in workspace state, binds
-  only this machine's Tailscale address and accepts only the pinned hosting peer
-  with a per-session secret. The host's bridge is loopback-only. For an Expo
-  dev client it listens on this machine's Metro port, which the dev server
+  The supervisor watches hosted Metro requests in workspace state and keeps a
+  few authenticated connections open to the host for each session. The host
+  pairs one with each connection the device makes to its loopback-only bridge,
+  and the supervisor forwards it to this Metro, so the host never connects back
+  to this machine and a shared or ACL-restricted host works. For an Expo
+  dev client the bridge listens on this machine's Metro port, which the dev server
   writes into the manifest. ios --remote starts Metro on a port free on both
   Macs; a running Metro or a pin on a port the host uses refuses the run before
-  the build. Port and secret
-  stay in 0600 workspace state and never appear in status, JSON or logs.
-  metro.tunnel and metro.publicUrl are ignored. Supervisor restart recreates
-  the recorded gateway; stop or a stopped hosted session closes it. A recorded
+  the build. metro.tunnel and metro.publicUrl are ignored. Supervisor restart
+  reopens the recorded links; stop or a stopped hosted session closes them. A recorded
   hosted session prevents Metro idle stop. Release runs skip the bridge.
-  Hosted Debug runs require the supervisor's private gateway support before
-  reservation. --no-metro-check refuses; restart a missing or older supervisor
+  Hosted Debug runs require a supervisor and a stim-server that support these
+  links before reservation. --no-metro-check refuses; restart a missing or older supervisor
   with stim stop; stim start.
   Native iOS and Android logs are pulled from the host by stim logs, including --errors;
   JavaScript logs still arrive through Metro. Stop pulls native logs before
@@ -2827,8 +2881,8 @@ BUNDLE WARMUP
   device logs may prove a request, but bundle completion may stay unverified.
 
 HOSTED ANDROID
-  android --remote <machine> keeps Metro here through the private tailnet
-  gateway. The host reverses the client Metro port into its loopback bridge
+  android --remote <machine> keeps Metro here through the same client-opened
+  links as hosted iOS. The host reverses the client Metro port into its loopback bridge
   on the exact owned emulator. Each run and reload restores that reverse;
   no adb command for the host serial runs here. metro.tunnel and metro.publicUrl
   are ignored. See guide lifecycle hosted-android.
@@ -3199,7 +3253,8 @@ FLAGS
                   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, placement (one or more), or all.
-                   gc alone reads the machine-wide gc log (GC LOG below).
+                   gc alone reads the machine-wide gc log (GC LOG below);
+                   builds alone reads the machine-wide build ledger (BUILD LEDGER below).
                    An unknown value is REJECTED rather than quietly matching
                    nothing.
   --level <l>      minimum level: debug, info, warn, error, fatal
@@ -3252,7 +3307,8 @@ serve bounded log queries.
   SecTrust, WebKit, CoreUI) that have nothing to do with your app. The proven
   ones are demoted to info by the collector, and iOS main-thread
   "Synchronous URL loading" performance diagnostics (Expo icons served by
-  Metro raise them) to warn, so a launch does not count them as app errors;
+  Metro raise them) and SwiftUI "Invalid Configuration" faults (the Expo dev
+  launcher raises them for a duplicated server entry) to warn, so a launch does not count them as app errors;
   the scope rule covers the rest.
   The metro stream carries exactly one demotion of its own, and it is Stim's
   doing: the dev-client deep link \`ios\`/\`android\` open to wire the app to
@@ -3370,6 +3426,35 @@ THE RECORD
              there are none. Stim adds it at query time; it is not in the
              log files.
 
+IOS BOOT RECORDS
+Booting an owned iOS simulator writes records to the workspace's device.ndjson:
+src device, platform ios, deviceId the simulator udid, slot when it is not
+default, level info unless noted. They show in a plain \`logs\` and in
+\`--source device\`, and never in \`--errors\`.
+  event ios_boot, with phase:
+    boot_requested      just before simctl boot; boot is adopted (a parked
+                        simulator), created, existing (an owned simulator
+                        that was shut down) or restart
+    bootstatus_done     simctl bootstatus -b returned
+    springboard_started SpringBoard finished starting; pid is its pid
+    viewer_opened       the simulator viewer was asked to open it
+    simslim_reboot      SimSlim changed the simulator and SpringBoard's pid
+                        changed; pidBefore and pidAfter are null when the pid
+                        could not be read
+    restart             warn: SpringBoard is not running after boot and the
+                        simulator was shut down; Stim boots it once more
+  event springboard_crash_reports, written before that restart and again if
+    SpringBoard is still missing after it. files lists the SpringBoard-*.ips
+    reports that name this simulator and were captured in the last ten minutes,
+    copied from ~/Library/Logs/DiagnosticReports and its Retired folder into
+    the workspace logs directory; level is warn, or info with an empty files
+    when none matched. dropped counts matching reports that exceeded the limits
+    below and were not copied; failure is the message of a write that failed,
+    with the reports copied before it in files. macOS deletes the originals
+    after about two days; Stim only reads that folder. It looks at the newest
+    100 reports of at most 1 MiB each, copies at most 8 MiB per run, and keeps
+    at most 40 in the directory.
+
 Maintenance records use src: maintenance and appear in the plain timeline.
   stim logs --source maintenance
 Add --errors to --source maintenance to show only maintenance_failure events;
@@ -3397,6 +3482,51 @@ Each record has src: gc, level (info, or error for a failed item), msg and
            and the reason a kept or failed item was left
 Records of one run share runId. See stim guide cleanup, WHAT WAS CLEARED.
 
+BUILD LEDGER
+stim logs --source builds reads $STIM_HOME/builds/builds.ndjson from any
+directory: one record per native build run (ios, android or macos; compiled
+here, offloaded or fetched from a cache; succeeded, failed or cancelled). It
+keeps the newest 500 records, outlives the workspace that ran the build, and
+is never removed by gc. It cannot be combined with other sources, and --source
+all does not include it. --errors shows the failed runs. A record has
+src: builds, event: build, level (info, warn for cancelled, error for failed),
+msg and
+  ts, startedAt   epoch milliseconds when the run finished and started
+  id              the run
+  project, workspace, branch
+                  project root, workspace id and the branch checked out
+  platform        ios, android or macos
+  scheme, variant, configuration
+                  the iOS scheme when one was selected, the Android variant,
+                  the build configuration
+  placement       { where: local | offloaded, machine?, fellBack?, reason? };
+                  machine is the build machine that compiled the app, and
+                  fellBack with reason marks a build that considered
+                  offloading and compiled here
+  cache           { result: hit | miss | bypassed, source?: local | remote,
+                  key, fingerprint, missReason? }
+  durationMs, phases
+                  wall time and milliseconds in each local phase (prepare,
+                  cache-lookup, wait, prebuild, pods, compile, device,
+                  install, launch)
+  offloadPhases   milliseconds on the build machine: sync, deps, prebuild,
+                  pods, build, fetch
+  outcome         succeeded, failed or cancelled
+  failure         failed or cancelled runs: { code, message, remedy, phase }
+  device          { name, runtime? } of the simulator, emulator or device;
+                  never its serial or UDID
+  loadPerCore     this machine's 5-minute load average per CPU when the run
+                  started, to one decimal
+  boot            { startedAt, loadPerCore } of the run's first owned
+                  simulator or emulator boot: epoch milliseconds when it
+                  started, once any concurrency.maxDevices wait was over,
+                  and the load per core then. Absent when the run booted
+                  nothing.
+  stimVersion     the stim that ran the build
+Records written before these fields existed lack loadPerCore and boot.
+A run that stopped before it had an app to build (a refused flag, a missing
+project) writes no record. Writing the record never changes the run's result.
+
 REMOTE REQUEST RECORDS
 A request to another machine that fails is a warn record with src: build in the
 run's build log: remote_connect_failed { host, capability, ms, timeoutMs, msg,
@@ -3426,16 +3556,45 @@ 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
 machine. They carry no arguments, tokens or tickets.
 
+TIMING TRACES
+STIM_TRACE=<path> makes a stim command write a timeline of where it spent its
+time, as Chrome trace events. Open the file in Perfetto (ui.perfetto.dev) or
+chrome://tracing. Unset, nothing is written and no file is opened. There is no
+setting for it, and the trace goes only to that file, never to stdout or stderr.
+Use a new path for each command: the command you start truncates the file, and
+the processes it starts (a Metro supervisor, collectors, a nested stim) append
+to it.
+  STIM_TRACE=/tmp/ios.json stim ios
+The file is a JSON array with one event per line and no closing bracket, so
+read it with JSON.parse(text.trimEnd().replace(/,$/, '') + ']'). Every event
+has pid; spans have ts and dur in microseconds since the epoch. Events:
+  command  one span named "stim <command>" with the exit code in args.exit
+  exec     one span per child process. args.argv (or args.command for a shell
+           command) has the values of secret-looking flags, credentials in
+           URLs and token shapes replaced by [redacted], and the credentials
+           of curl -u and security import -P; other short flags such as -p
+           and -u are kept. args also has cwd, ok, exit and signal
+  phase    the build phases of an ios, android or macos run on a
+           "phases: <platform> build" track, named as in stats.json and the
+           build ledger (prepare, cache-lookup, wait, prebuild, pods, compile,
+           device, install, launch), and the steps of worktree warm
+  span     fingerprint, wait for metro and carry ignored entries
+  mark     instant events such as a fingerprint memo hit
+Children running at the same time are drawn on separate tracks. A span still
+open when its process exits is written with unfinished: true; a process ended
+by a signal writes none. A trace holds
+full paths and arguments, so treat it like a log.
+
 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 machine to
-consider, or ios/android --remote auto), with event build_placement,
+consider, or ios/android --remote auto|remote|remote-only), with event build_placement,
 device_placement or placement_fallback. A cache hit, a project with no paired
 remote machine 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
+from flag, env, setting or default (remote.build 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
@@ -3458,6 +3617,8 @@ WHAT WRITES WHAT
   maintenance.ndjson   workspace maintenance actions, failures and explaining skips
   $STIM_HOME/gc/gc.ndjson  machine-wide, not in a workspace: what gc, maintenance
                        and the budget gate cleared (stim logs --source gc)
+  $STIM_HOME/builds/builds.ndjson  machine-wide: the last 500 native builds
+                       (stim logs --source builds)
   metro.ndjson         the bundler, in every supervisor mode. Stim's
                        middleware adds one record per bundle request
                        (bundle_response_started, _progress, _finished,
@@ -3480,7 +3641,8 @@ WHAT WRITES WHAT
                        -- and, on iOS, where every Apple framework running in
                        the app's process also logs. The proven noise sources
                        are recorded at info rather than error (Synchronous
-                       URL loading diagnostics at warn); the rest is why
+                       URL loading diagnostics and SwiftUI Invalid Configuration
+                       faults at warn); the rest is why
                        --errors leaves this source out unless asked. A VERIFIED
                        LAUNCH counts these records and prints one line:
 
@@ -3673,7 +3835,12 @@ Branch on the code, never on the message.`,
   hosted session. Auto skips declined offers before building, then uses the
   local queue if none admits. A reserve refusal after an accepted offer fails
   with this code and asks to retry; it does not re-place the built architecture.
-  Check stim-server and Tailscale there,
+  remote-only never runs here and never joins the local queue: it refuses
+  with this code when no host could ever take the run, and waits for a host that
+  is only full or loaded (see STIM_AT_CAPACITY).
+  An unreachable host's message and remedy are the diagnosis stim doctor gives
+  (Tailscale off, Mac offline with last seen, serve route, stim-server), without
+  tailscale ping. Check stim-server and Tailscale there,
   then run stim doctor. Correct --device-type / --runtime for iOS or
   --system-image / --device-profile for Android when the offer names
   an unavailable choice. A session that exists stays recorded even if delivery
@@ -3795,9 +3962,14 @@ Branch on the code, never on the message.`,
   note naming which of the two set it; Gemfile.lock is never edited either way.
   \`worktree warm --refresh\` reports the same code for the install it runs in
   the SOURCE CHECKOUT -- the lockfile's own command (\`pnpm install\`,
-  \`yarn install\`, \`bun install\`, \`npm ci\`) or that same pod ladder. The
+  \`yarn install\`, \`bun install\`, \`npm ci\`), the \`npm run postinstall\`
+  it runs when npm's config there sets ignore-scripts, or that same pod ladder. The
   message names the command, quotes its last lines, and nothing is copied: fix
-  the source checkout, then warm again.`
+  the source checkout, then warm again.
+  start, ios and android also refuse with this code when \`gc --delete\`
+  lightened the worktree and the \`stim worktree warm\` they ran to restore
+  its node_modules and ios/Pods failed. The warm's own lines say why; fix
+  that, then run \`stim worktree warm\` or retry the command.`
 		},
 		STIM_BUILD_FAILED: {
 			summary: "xcodebuild or gradle failed; the Android missing-SDK and APK refusals",
@@ -4035,6 +4207,11 @@ 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.
 
+remote-only never builds here: it refuses when no remote machine in remote.machines
+can take the build, naming each machine and why it was skipped, and for a build that
+cannot leave this machine. Rerun with --remote-build remote to allow a local build
+when no remote machine can take it.
+
 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, changed pinned server key, a stim-server
@@ -4063,7 +4240,7 @@ Run stim doctor --fix to ask for build access if not paired. Check
 stim settings get remote.machines. A person on the worker approves this machine
 by running the stim-server setup command doctor --fix printed, with its ticket
 and expiry (guide settings). Agents never run setup or approve requests.
-Rerun with --remote-build auto for normal placement and local fallback, or
+Rerun with --remote-build auto or remote for placement with local fallback, or
 --remote-build local to keep the build here.
 `
 		},
@@ -4158,6 +4335,13 @@ Rerun with --remote-build auto for normal placement and local fallback, or
   Trust, then run the command again. It is a per-developer-certificate tap, not
   a per-build one -- but an uninstall clears it, including the one Stim's own
   signer-conflict retry performs.
+  On a local iOS simulator, a cache-hit app that dyld kills at launch because
+  one part of the app cannot bind a symbol from another part of the same app
+  (for example React.framework against hermesvm.framework) is a damaged build,
+  not a launch problem. Stim removes that cache entry, and the remedy names
+  it. Run the command again to build the app fresh. A cache provider's copy is
+  not removed; add \`--no-build-cache\` to skip it. If the fresh app crashes
+  the same way, the project's own native code is the cause.
   With \`--remote eas\` the remedy names the EAS Simulator session that is
   still running, as for STIM_INSTALL_FAILED.`
 		},
@@ -4439,6 +4623,16 @@ so a Debug run on one is wired to a LAN origin instead of localhost.`,
   installation. If it fails, the refusal includes observed host memory pressure
   when available. Free memory before retrying under pressure; see
   \`stim guide lifecycle simslim\`. Booted alone does not prove readiness.
+  The same probe lists the simulator's launchd jobs and requires a running
+  SpringBoard. A simulator that reports Booted while SpringBoard has died
+  (\`simctl launch\` then says "The system shell probably crashed") is shut
+  down through teardown and booted once more; if SpringBoard is still not
+  running, the refusal names the udid and the remedy: \`stim stop\`, then
+  \`stim ios\` again. Repeated SpringBoard crashes leave reports in
+  ~/Library/Logs/DiagnosticReports, and macOS deletes them after about two
+  days; before the restart Stim copies the simulator's recent ones into the
+  workspace logs directory and records the boot steps by udid
+  (\`stim logs --source device\`, \`stim guide logs\`, IOS BOOT RECORDS).
   On Android the emulator's own stdio is captured to
   the global workspace logs/emulator.log (truncated per boot), and when it printed a
   \`FATAL |\` / \`ERROR |\` / \`PANIC:\` line THAT is the message and the remedy
@@ -4541,6 +4735,11 @@ so a Debug run on one is wired to a LAN origin instead of localhost.`,
   locks, builds, viewers and recent activity. Reclaim excludes this workspace,
   physical, hosted, remote, parked and other homes' devices and never deletes.
   A failed reclaim is logged and skipped; the run keeps waiting.
+  --remote remote-only (and macos.remote remote-only) has no local queue: when every
+  approved host is full, loaded or short of memory it polls the hosts every 5 seconds
+  for the same wait (--wait, default 600 seconds) and then refuses with this code;
+  --no-wait and --wait 0 refuse at once. Builds under remote-only refuse with
+  STIM_OFFLOAD_REFUSED instead.
   Stop an environment (\`stim stop\`), pass a longer \`--wait <seconds>\`,
   or raise concurrency.maxDevices. With --remote auto, remote.machines and
   the opt-in remote.easFallback (billed EAS Simulator) are tried before this
@@ -4980,8 +5179,8 @@ Inspect what remains with gc() before retrying a mutation.
 `
 		},
 		STIM_CANCELLED: {
-			summary: "an ios or android run was interrupted by `stim stop` or Ctrl-C before it finished",
-			body: () => `STIM_CANCELLED  (ios, android; exit 130)
+			summary: "an ios, android or macos run was interrupted by `stim stop` or Ctrl-C before it finished",
+			body: () => `STIM_CANCELLED  (ios, android, macos; exit 130)
   "The ios run was cancelled by \`stim stop\` (pid <n>) before it finished."
   The run was interrupted: by \`stim stop\`, which cancels a build it leaves
   with nothing to deploy to, or by Ctrl-C. It forwarded the interrupt
@@ -4990,8 +5189,11 @@ Inspect what remains with gc() before retrying a mutation.
   stopped at. An interrupted build stores no artifact, so the next run looks
   up the cache as usual. Stopped between build tools, a run that \`stop\`
   cancelled starts no further build tool and stops before it installs. A
-  second Ctrl-C exits at once, and so does a Ctrl-C with no build tool or
-  SimSlim to stop; those exits print no payload. Run the same command again when you want the
+  Ctrl-C while the run delivers the app to a hosting Mac, or waits for the app
+  to load its bundle or report readiness, ends that work and reports
+  STIM_CANCELLED. A second Ctrl-C exits at once, and so does a Ctrl-C with no
+  build tool, SimSlim, hosted app delivery or launch readiness wait to stop;
+  those exits print no payload. Run the same command again when you want the
   app on a device.`
 		},
 		STIM_STOP_BLOCKED: {
@@ -5204,8 +5406,9 @@ not on any remote"  (worktree remove)
   lockfile says nothing about the one on disk now, whose dependencies may well
   have been installed since; and a repository with no record at all -- every
   repository before its first \`--refresh\` -- copies as it always has.
-  In a monorepo the record is keyed on the directory that owns the lockfile,
-  which is usually the repository root, so every app of it reads the same one.`
+  Each directory that owns a lockfile the refresh installs has its own record:
+  the repository root and, when the app has a lockfile of its own, the app. A
+  plain warm reads both.`
 		},
 		warm: {
 			summary: "worktree warm claim storage refusals and recovery",
@@ -5494,7 +5697,7 @@ STIM_SUPERVISOR_EXITED, ...) before any build work. Release builds and
 \`--no-metro-check\` neither check nor start the dev server; hosted Debug iOS
 refuses --no-metro-check with STIM_BAD_ARG. \`--remote\`
 with eas or proxy starts it the way \`stim start --remote\` does. A named
-hosting Mac keeps Metro local through a private bridge; see hosted-ios. Step 2 remains useful to warm
+hosting Mac keeps Metro local through links this machine opens; see hosted-ios. Step 2 remains useful to warm
 Metro while other work happens.
 
 Each time Stim boots an owned local simulator or emulator, it mutes it: iOS
@@ -5674,7 +5877,8 @@ WAITING FOR A CHANGE
   status payload per line: one at once, then one each time the payload
   changes, never two identical ones in a row. In a watch line, a usage
   figure repeats its value in the previous line until it moves by a step: an owner's cpuPercent 5 points, an
-  owner's or environment's memoryMb and capacity.committedMb 16 MB. An owner's row
+  owner's or environment's memoryMb and capacity.committedMb 16 MB, and
+  capacity.load as a whole until its loadPerCore moves 1 per core or its state changes. An owner's row
   changes as a whole, so its residentMb and processes update with it. A change
   in only a bookkeeping timestamp prints no line: each pullRequest.checkedAt,
   maintenance.lastChecks, maintenance.lastPass.startedAt and durationMs, and
@@ -5901,9 +6105,9 @@ If Stim is not installed globally, replace stim with npx stim.
 
 A person on the host approves device-host access, separately from build, read
 and control. The setup in hosted-ios also serves Android. android.remote sets
-a workspace default. eas and proxy remain backends. --remote auto or
-android.remote = auto places automatically; see hosted-ios for the shared
-policy. No flag or setting runs on this machine.
+a workspace default. eas and proxy remain backends. --remote auto, remote or
+remote-only (or the same android.remote value) places automatically; see
+hosted-ios for the shared policy. No flag or setting runs on this machine.
 
 A named Mac is strict: refusal, unreachable, declined or failed preparation
 returns STIM_HOSTING_REFUSED without fallback. --device with --remote
@@ -5920,8 +6124,8 @@ soon as it exists, then delivers one App.apk. The emulator boots headless;
 androidEmulatorApp is ignored with a note.
 
 React Native Debug requires the local Metro supervisor. metro.publicUrl and metro.tunnel
-are ignored with a note. A private tailnet gateway reaches the host loopback
-bridge; the host reverses the client's Metro port into that bridge on its exact
+are ignored with a note. Connections this machine opens to the host carry each
+device connection from the host loopback bridge to local Metro; the host reverses the client's Metro port into that bridge on its exact
 ledger-owned serial and sets debug_http_host to localhost:<clientMetroPort>.
 Each run and stim reload android restores the reverse, including after a host
 adb server restart. Reload broadcasts through the local Metro and never runs
@@ -5944,7 +6148,7 @@ session probe states; a conflicting local emulator remains visible with a
 warning. A recorded placement keeps the workspace in use and blocks idle stop.
 
 stop and worktree remove wait for device-host.stop, park the host's eligible owned
-emulator within pool.androidParkedMax (delete otherwise), close the gateway and clear placement. stop --json reports
+emulator within pool.androidParkedMax (delete otherwise), close the Metro links and clear placement. stop --json reports
 outcomes.device["android:host:<slot>"]. Forbidden or unknown-session also clears
 placement; an unreachable host keeps it and fails cleanup. A clean host restart
 parks eligible devices; a later reserve by the same client adopts a compatible
@@ -6030,8 +6234,8 @@ Logcat retains a finite buffer; records already evicted or persisted beyond the
 overlap may be unavailable. An oversized query retries the recent tail and writes
 a device warning naming any dropped interval. Followers share a child-aware log
 claim; install and stop cancel and settle the worker before native operations.
-Stop copies logs before and after the host's final collection and teardown, with
-each client drain bounded to 30 seconds and progress on stderr. Collected logs
+Stop copies logs once, after the host's final collection and teardown, bounded to
+30 seconds with progress on stderr; Ctrl-C cancels the copy and keeps the placement. Collected logs
 remain readable after stop. The host advertises hosted-android-data for Android
 handoff and native logs. Older hosts get a newer stim-server note, use upload
 and show records already copied here.`
@@ -6051,28 +6255,44 @@ If Stim is not installed globally, replace stim with npx stim.
   stim reload ios
   stim stop
 
-The same setup serves macos --remote. Approval is separate from build, read
+The same setup serves macos --remote and macos.remote. Approval is separate from build, read
 and phone control. Set ios.remote to the machine name for a default (machine scope for every app on this machine);
 no flag or setting runs here. eas and proxy keep their remote backend meanings.
 --remote auto (or ios.remote = auto / android.remote = auto) stays here when
 there is a free concurrency.maxDevices slot (0 means unlimited), no device
 waiter ahead, normal host memory pressure, no budget shortfall,
 and 5-minute load per core below server.maxLoadPerCore. Without remote.machines,
-auto is local. An unknown local device count also stays local; boot admission
+auto and remote are local and remote-only refuses with STIM_HOSTING_REFUSED. An unknown local device count also stays local; boot admission
 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.
 
+--remote remote (or ios.remote = remote) skips that local check and asks the hosts
+first, in remote.machines order; the simulator runs here only when none admits
+it, with the same wait and EAS fallback as auto. --remote remote-only never runs
+here and never joins the local queue or uses EAS. When every host that answered is
+only full, loaded or short of memory, it waits for one to have room, polling every
+5 seconds for --wait seconds (default 600) and printing one placement line; --no-wait,
+--wait 0 or the end of the wait refuse with STIM_AT_CAPACITY. When no host can ever take
+the run (none configured, unreachable, declined for another reason such as paused),
+it refuses at once with STIM_HOSTING_REFUSED, naming each skipped host and its reason.
+--plan never waits. It prints the same STIM_HOSTING_REFUSED, or a STIM_BAD_ARG naming
+an invalid remote.build or STIM_REMOTE_BUILD.
+Excluding local in remote.devicePoolDisabled has the same effect on auto and remote.
+
 Otherwise Stim asks every approved remote.machines host in parallel, skipping
 one that tailscale status reports as running an OS other than macOS, with a
 3-second probe timeout and this run's model/runtime or image/profile selectors.
-A compatible choice, no declined reason, normal memory pressure and available
-capacity are required. With a free local slot, a host must report a lower load;
-with a full cap or a queue ahead, an admitted host with unknown load is allowed.
-Hosts rank by the build preference (flag > STIM_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.
+A compatible choice, no declined reason, normal memory pressure, available
+capacity and a load per core under the host's own server.maxLoadPerCore are
+required (a host that reports no limit uses this machine's). With a free local
+slot, a host with unknown load is skipped under auto (remote admits it); with a full cap or a queue ahead, an
+admitted host with unknown load is allowed. Admitted hosts are tried in order:
+the host named by the build preference (flag > STIM_REMOTE_BUILD > remote.build)
+when it names a machine, then remote.machines order, so the first listed host with
+room fills before the next gets a run. Load and free memory do not rank hosts.
+Automatic build offload resolves later, after the device architecture is known.
 
 When no host admits and this machine is at its concurrency.maxDevices cap (or runs
 are queued ahead), remote.easFallback (default false; EAS Simulator is billed)
@@ -6089,7 +6309,7 @@ metro.tunnel off; on an Expo tunnel, run stim start --remote first). A recorded
 EAS session is not sticky: once this machine has room, auto runs here and the
 session bills until stim stop or remote.easMaxDurationMinutes. 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
+slot queue; --no-wait and --wait 0 refuse with STIM_AT_CAPACITY (remote-only has no local queue and waits for a remote host instead, as described above). The placement
 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
@@ -6101,8 +6321,8 @@ A reserve refusal after a successful offer can race with another run. It fails
 with STIM_HOSTING_REFUSED naming the host and asking to retry. Stim does not
 try the next host or local placement after the build has targeted that host's
 architecture, and never falls back once a hosted session exists. A named machine remains strict. --device
-cannot combine with --remote auto, and a --device run ignores ios.remote and
-android.remote. eas/proxy and macOS placement are unchanged.
+cannot combine with --remote auto, remote or remote-only, and a --device run ignores ios.remote and
+android.remote. eas/proxy placement is unchanged; macOS placement follows macos.remote (stim guide macos).
 --simulator-app is honoured locally with auto and ignored with a note on a host.
 Placement measures budgets without reclaiming; only a new local run reclaims.
 Android --remote <machine> uses an owned emulator on that Mac; see hosted-android.
@@ -6134,9 +6354,10 @@ sessions.
 
 
 Stim builds or fetches before reserving, records the session immediately, then
-uploads the app on every run. React Native and Expo Debug keep Metro here; the supervisor owns a
-private gateway bound to this machine's Tailscale address, pinned to the host peer
-and protected by a per-session secret. The host exposes only a loopback bridge.
+uploads the app on every run. React Native and Expo Debug keep Metro here; the supervisor keeps
+authenticated connections open to the host, and the host pairs one with each
+connection the simulator makes to its loopback-only bridge. The host never
+connects back to this machine.
 For an Expo dev client the bridge listens on this machine's Metro port, because
 the dev server writes that port into the manifest's bundle URL. When this run
 starts Metro, it asks the host and picks a port free on both Macs, moving the
@@ -6144,8 +6365,8 @@ recorded port if the host uses it. A running Metro or a metro.port pin on a port
 the host uses refuses before the build: run stim stop, then stim ios --remote
 <machine> without stim start, or pin a port free on both Macs.
 No start --remote is needed; metro.tunnel and metro.publicUrl are ignored.
-Debug requires a running supervisor with private gateway support before reserving
-a simulator. --no-metro-check refuses with STIM_BAD_ARG for hosted Debug runs.
+Debug requires a running supervisor and a host stim-server that support these
+links before reserving a simulator. --no-metro-check refuses with STIM_BAD_ARG for hosted Debug runs.
 If its supervisor is missing or older, run stim stop; stim start, then retry.
 Non-Debug runs skip Metro. Launch is unverified until this workspace's Metro
 provides bundle evidence, or the host proves a live release process. Native Xcode
@@ -6158,14 +6379,14 @@ hosting Mac, refuses for that slot: run stim stop first.
 Status adds ios.host { machine, session, selected, device: { name, runtime },
 agent, state } per slot. A shutdown local simulator is replaced in status; a
 booted or unknown local simulator stays visible alongside ios.host with a warning.
-The default slot appears only in ios, never in slots[]. No host UDID or gateway secret enters local device state or
+The default slot appears only in ios, never in slots[]. No host UDID enters local device state or
 status. Ready is normal; stopped has a rerun hint; unknown or unreachable is
 unverified. A clean host server restart stops its sessions and retains eligible
 parked devices. A running session left by a crash stays unknown until explicit
 stop; the restarted server never re-attaches to a booted device.
 
 stop and worktree remove wait for the host to stop, park its eligible owned
-simulator within pool.iosParkedMax (delete otherwise), close the gateway and clear placement. stop --json
+simulator within pool.iosParkedMax (delete otherwise), close the Metro links and clear placement. stop --json
 reports each hosted slot under outcomes.device["ios:host:<slot>"], retaining
 local device outcomes and successful siblings when another slot fails. Revoked or
 missing sessions clear placement too. An unreachable host retains placement
@@ -7444,8 +7665,10 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
                             Waiting prints the count, holder workspace names
                             and elapsed time at once and about every 10s, then
                             the queue position, head workspace name and
-                            $STIM_HOME/device-waits path. Timeout names the
-                            same head and path. Stop cancels a queued run and
+                            $STIM_HOME/device-waits path. Workspaces that
+                            share a project name show the directory that tells
+                            them apart, as in mobile (qa-b-p2). Timeout names
+                            the same head and path. Stop cancels a queued run and
                             releases its ticket without booting its device.
                             Status JSON adds build.waitingFor independently
                             of phase: { kind: "device-slot" | "build-slot",
@@ -7523,7 +7746,14 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
        (\`gc --delete\` semantics; the next build installs from the shared
        cache). A workspace whose last use is unknown is kept
     4. trim shared cache entries nothing has used for 14 days
-       (\`gc --delete --older-than 14\` for the caches)
+       (\`gc --delete --older-than 14\` for the caches). Caches with nothing
+       to trim print one line, not one each. A trim that removed nothing is
+       recorded in $STIM_HOME/budget-sweep.json and not repeated for 5
+       minutes while the set of caches is the same and free disk has not
+       fallen by more than 1 GB since; the run prints one budget line saying
+       it skipped. \`gc\` and automatic maintenance never skip, and a dry
+       run (\`doctor\`) still plans the step. The STIM_LOW_DISK message
+       measures the largest uses of disk at the same time.
 
   IDLE SHUTDOWN (30 MINUTES BY DEFAULT): with devices.idleShutdownMinutes above
   0, a workspace's supervisor shuts down that workspace's owned simulators and
@@ -7592,8 +7822,8 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
 			summary: "every flag per command, Android variants and flavors, the per-run simulator model, runtime and system image",
 			body: () => `THE OPTION SURFACE, IN FULL
   start           --json --wait <seconds> --remote --reset-cache
-  ios             --remote-build <auto|local|name> --slot <name> --json --plan --no-metro-check --no-build-cache --scheme <name> --configuration <name> --device-type <name> --runtime <version> --simulator-app <xcode|siniulator|stim-desktop> --device [udid] --wait <seconds> --no-wait --remote <eas|proxy|auto|machine>
-  android         --remote-build <auto|local|name> --slot <name> --json --plan --no-metro-check --no-build-cache --variant <name> --system-image <id> --device-profile <id> --device [serial] --wait <seconds> --no-wait --remote <proxy|eas>
+  ios             --remote-build <local|auto|remote|remote-only|name> --slot <name> --json --plan --no-metro-check --no-build-cache --scheme <name> --configuration <name> --device-type <name> --runtime <version> --simulator-app <xcode|siniulator|stim-desktop> --device [udid] --wait <seconds> --no-wait --remote <eas|proxy|local|auto|remote|remote-only|machine>
+  android         --remote-build <local|auto|remote|remote-only|name> --slot <name> --json --plan --no-metro-check --no-build-cache --variant <name> --system-image <id> --device-profile <id> --device [serial] --wait <seconds> --no-wait --remote <proxy|eas|local|auto|remote|remote-only|machine>
   ios/android --wait bounds owned-device slot waits (default 600s), or physical
   leases with --device (default 60s). Remote targets do not join this local
   slot queue. --no-wait refuses a full/queued owned
@@ -7701,12 +7931,24 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   .stim.json, else \`git symbolic-ref --short refs/remotes/origin/HEAD\`;
   when neither answers it says so and makes no warning.
 
-  Dependencies install where the lockfile is, which in a monorepo is the
-  repository root, when the lockfile moved or nothing is installed. Pods run
-  for the app the command was invoked from, and only that app, when its
-  ios/Podfile.lock moved or ios/Pods/Manifest.lock does not match it. Each
-  completed or skipped deps and pods step names its source directory and
-  reason. A failed install refuses with STIM_DEPS_FAILED and nothing is copied.
+  The app is the one warm prepares: the app the command was invoked from, or,
+  from a monorepo root, the one app registered in the source checkout or in
+  the worktree. With no such app, a refresh from the root updates only the
+  repository root and says so on stderr.
+  Dependencies install where the repository root's lockfile is and, when the
+  app has its own lockfile (a nested package outside the root workspaces),
+  there too; a root that has neither installed dependencies nor an install
+  record is left alone when the app has its own lockfile. Each installs when
+  its lockfile moved, when its patches/ directory moved (npm projects only),
+  when nothing is installed, or when npm reports a tree that differs from the
+  one it reported after the last completed install. An npm project whose
+  npm config sets ignore-scripts gets no postinstall from \`npm ci\`, so when its
+  package.json defines one the refresh runs \`npm run postinstall\` next
+  (patch-package, usually); dependencies' own install scripts stay blocked.
+  Pods run for that app, and only that app, when its ios/Podfile.lock moved or
+  ios/Pods/Manifest.lock does not match it. Each completed or skipped deps and
+  pods step names its source directory and reason. A failed install or
+  postinstall refuses with STIM_DEPS_FAILED and nothing is copied.
 
   An install that did not finish is remembered, and a PLAIN warm reads that
   before it copies. The refresh records the completed install of the lockfile it
@@ -7771,7 +8013,11 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   expo-modules-jsi/apple/.DerivedData Xcode build state, directly under
   node_modules or in the pnpm virtual store. An ignored directory that Git
   reports above those names (for example an app directory with no tracked
-  files) is copied as is. Warm also skips paths
+  files) is copied as is. Warm renames those deleted paths into
+  $STIM_HOME/trash and a detached, low-priority rm deletes them after warm
+  returns (through the programmatic API, before the call resolves); when the
+  rename is not possible (Windows, $STIM_HOME on another volume), warm deletes
+  them before it returns. Warm also skips paths
   overlapping a nested destination worktree or below a symlink ancestor.
   Tracked .idea settings come from Git and stay untouched by warm.
 
@@ -8457,11 +8703,14 @@ In on mode a pass runs, cheapest to rebuild first:
      claim is unresolved; the emptying holds the exclusive claim
   5. linked worktrees whose branch or pull request finished (gc's finished
      worktree rules and gc.worktreeGraceMinutes; maintenance.removeFinishedWorktrees),
-     and, with maintenance.removeIdleWorktrees (off by default), in the age
+     a dirty finished one after archiving its uncommitted files (ARCHIVED
+     CHANGES in stim guide cleanup gc), clean ones with no commits of their
+     own (NO COMMITS OF ITS OWN there), and, with
+     maintenance.removeIdleWorktrees (off by default), in the age
      sweep clean, pushed ones unused for olderThanDays, as gc --delete
      --worktrees --older-than removes them, git-ignored files included; never
-     a dirty one, one with unpushed commits, the source checkout, or one whose
-     last use is unknown
+     an unfinished dirty one, one with unpushed commits, the source checkout,
+     a locked one, or one whose last use is unknown
   6. parked simulators and emulators unused for olderThanDays in the age
      sweep, through centralized teardown with ownership checked again
   7. owned simulators and emulators of a finished worktree that is kept, such
@@ -8497,14 +8746,21 @@ DISK PRESSURE LEVELS
   level 2, which runs until free disk is back above the floor; level 3 runs
   only while free disk stays under the level 3 floor. At levels 2 and 3 the
   protection window is maintenance.pressureProtectMinutes (10) instead of
-  protectRecentHours. Each step re-measures first and stops once free disk is
-  back above its level's floor, cheapest to rebuild first.
+  protectRecentHours, except for the build outputs and build directories of
+  level 2, which follow the lightening rule of gc --delete (WORKSPACE BUILD
+  OUTPUTS): a running dev server, a booted or hosted device and a managed
+  tunnel do not keep them, a build or a running macOS app does, and they stay
+  for 15 minutes after the workspace's last ios, android or macos run.
+  Each step re-measures first and stops once free disk is back above its
+  level's floor, cheapest to rebuild first.
   Level 2:
-    1. build outputs of workspaces unused for the short window
+    1. build outputs of workspaces, with the lightening rule above
     2. parked simulators and emulators, deleted through centralized teardown
-    3. build directories of idle worktrees: ios/build, android/app/build,
-       android/build, android/.gradle and .build, at a project root, the
-       worktree root, or apps/* and packages/*
+    3. build directories of worktrees with a Stim workspace, by the same
+       rule: android/app/build, android/build, android/.gradle and .build, at
+       a project root, the worktree root, or apps/* and packages/*. ios/build
+       stays: React Native's pod install writes the codegen output and
+       podspec facades there that only pod install recreates
     4. owned simulators and emulators of workspaces idle for the short window
     5. Stim temp directories, xctrace recordings and SwiftPM temp directories
        in TMPDIR unmodified for 24 hours, with gc --delete's checks (see stim guide cleanup gc)
@@ -8514,12 +8770,14 @@ DISK PRESSURE LEVELS
        and the build
     2. finished worktrees, and clean, pushed worktrees with no commits of
        their own beyond the default branch, with the short window as grace
-       period (maintenance.removeFinishedWorktrees still applies)
+       period and idle window (maintenance.removeFinishedWorktrees still applies)
     3. workspaces whose dev server runs but that are otherwise inactive for
        the short window: their dev server stops and their owned simulators
        and emulators are deleted
     4. node_modules and ios/Pods at the root or a project root of idle linked
-       worktrees, never the source checkout
+       worktrees, never the source checkout, with the running-process checks
+       of WORKTREE DEPENDENCIES; when worktree warm can restore them they are
+       recorded for the next start, ios or android to restore
     5. idle Gradle and Kotlin daemons, stopped as gc --delete --cache
        gradle-daemons stops them (never during a Stim build, never a busy or
        unverified one, never with STIM_HOME set), only when every Gradle
@@ -8531,9 +8789,12 @@ DISK PRESSURE LEVELS
        gradle-versions, run again after step 5 so a daemon that did not exit
        still keeps them
   A directory is cleared only when it is a real directory inside its
-  worktree, git tracks nothing in it, its worktree is not in use, holds no
-  lock or build and is not pinned, and nothing under it, nor the worktree's
-  git index, HEAD or Stim state, changed within the short window. A dirty or
+  worktree, git tracks nothing in it, its worktree is not in use, is not
+  locked with git worktree lock, holds no build lock and is not pinned, and, for the node_modules and ios/Pods of
+  level 3, nothing under it, nor the worktree's git index, HEAD or Stim
+  state, changed within the short window. A build directory of level 2 also
+  stays in a worktree where no Stim workspace has recorded any state; a build
+  that Stim did not run is not detected. A dirty or
   unpushed worktree can still be stopped and have these directories cleared;
   only its removal is refused. Caches of other tools (pnpm and npm stores,
   CocoaPods, SwiftPM, the shared Gradle caches) are never deleted.
@@ -8664,6 +8925,11 @@ this cleanup. agent-device is optional: a missing binary skips this step, and a
 failed or timed-out list/close prints a device line on stderr while teardown
 continues. Each cleanup pass allows at most 15 seconds of agent-device calls
 per device; the pass \`stop\` makes after shutdown has its own budget.
+A daemon agent-device will not replace (daemon-busy: it is starting up or still
+has sessions, requests or leases) is not retried. Stim prints one line per
+device, naming each busy daemon, even though it lists sessions before and after
+shutdown: sessions on the device in them stay open until the daemon is idle or,
+if it is yours, stopped with agent-device daemon stop --state-dir <dir>.
 A local daemon that cannot use socket transport or a CLI without the target guard
 skips cleanup with a warning; no remote daemon is used.
 
@@ -8854,7 +9120,10 @@ LINKED WORKTREES
   still exists, as after a removal killed between the rename and git, stays
   with the reason; if that worktree is the one the entry came from, run
   \`stim worktree remove\` on it to finish the removal.
-  gc never moves the directories back.
+  gc never moves the directories back. Warm uses the same trash for the
+  known paths it deletes from a copy (such as a copied .pnpm-store); gc
+  --delete deletes such an entry (trash.json kind warm) once its claim is free,
+  whatever the state of the worktree.
   When git still refuses the removal, the kept ownership record no longer
   names the devices that were parked or deleted. A workspace that is in use
   (see IN USE below) keeps its directory, devices and registry entry, and the
@@ -8863,11 +9132,14 @@ LINKED WORKTREES
   only when it has no unique commits.
 
 IN USE
-  gc and worktree remove never delete a workspace's directory, build outputs
-  or checkout while it is in use: its dev server supervisor is running or
+  gc and worktree remove never delete a workspace's directory or checkout
+  while it is in use: its dev server supervisor is running or
   cannot be verified, a \`stim ios\`, \`stim android\` or \`stim stop\` run
   holds its native-run.lock, a live or unresolvable build lock or slot names it,
-  or its managed tunnel or managed remote lock is held. The deletion holds
+  or its managed tunnel or managed remote lock is held. Build outputs follow
+  the narrower rule in WORKSPACE BUILD OUTPUTS (\`guide cleanup disk\`): only
+  a build, a running macOS app, or an ios, android or macos run in the last
+  15 minutes keeps them. The deletion holds
   native-run.lock itself, so no native run can start partway through. A lock
   that names no workspace blocks nothing, because every build also holds its
   own workspace's native-run.lock; gc lists it with the command that removes
@@ -8884,14 +9156,17 @@ SWEEPING FINISHED WORKTREES
   ever ran in it. It groups them by git worktree and reports each linked
   worktree with the reason it is removed or kept. A worktree is finished when
   its branch is merged into the default branch, or its pull request was
-  merged or closed (PULL REQUESTS below). \`--worktrees\` also removes
+  merged or closed (PULL REQUESTS below). A clean worktree with no commits
+  of its own counts as finished once idle (NO COMMITS OF ITS OWN below).
+  \`--worktrees\` also removes
   one that is idle: no recorded use for --older-than days, 7 without it; a
   worktree whose last use is unknown is kept, unless it has no commits of its
-  own beyond the default branch (NO COMMITS OF ITS OWN below). Both need the
-  same clean state;
+  own beyond the default branch (NO COMMITS OF ITS OWN below). Each needs a
+  clean state, except a finished one whose changes are archived;
   a worktree is kept when it is the source checkout, bare, locked, holds
   another worktree (worktree remove refuses it too), in use,
-  dirty (untracked files count; pod install churn and
+  dirty and not finished, or dirty and finished when its changes cannot be
+  archived (ARCHIVED CHANGES below; untracked files count; pod install churn and
   watchman's untracked \`.watchman-cookie-*\` files alone do not), unpushed
   (commits no remote-tracking ref or other local branch reaches), or has
   initialized submodules. Without --worktrees, the report leaves out the
@@ -8922,14 +9197,17 @@ SWEEPING FINISHED WORKTREES
   an unexpired device lease. When the simulator or emulator list cannot be
   read, the worktree counts as in use. A device left booted keeps the
   worktree until \`stim stop\` in it, or \`gc --idle <duration>\`, shuts
-  the device down.
+  the device down. A worktree that holds the running stim or the realpath of
+  the \`stim\` on PATH is in use too, and \`stim worktree remove\` refuses it
+  even with --force, as it refuses an installed stim-server service's checkout.
 
   RECENT ACTIVITY keeps a worktree gc would otherwise remove until
   gc.worktreeGraceMinutes (120 by default, \`guide settings\`) have passed
   since the latest of: a write to its git index, HEAD or HEAD reflog, a write
   to its Stim workspace state or log files, and, for a merged branch, the
   committer date of the commit that brought it into the default branch, or
-  the time its pull request was merged or closed. That
+  the time its pull request was merged or closed, and, for a dirty finished
+  worktree, the newest change to its uncommitted or untracked files. That
   window is when an agent that just merged runs \`stim stop\` and \`stim
   worktree remove\` itself. The reason is recent-activity, and the report
   and the JSON eligibleAt field say when it becomes removable. When that
@@ -8984,20 +9262,56 @@ SWEEPING FINISHED WORKTREES
 
   NO COMMITS OF ITS OWN: a worktree whose HEAD the default branch contains
   and whose branch has no commit made on it (fresh, cut from another
-  branch, or reset onto one; the MERGED rule above) holds nothing git would
-  lose, but looks the same as one just made by git worktree add. Plain gc keeps
-  it (reason not-merged, "no commits of its own beyond origin/<default>").
-  \`--worktrees\` removes it when idle: by its recorded use when there is
-  one, else by the RECENT ACTIVITY sources above being older than
-  --older-than days (reason recently-used while they are newer, and
-  last-use-unknown when they cannot be read). Automatic maintenance removes it
-  the same way in its daily age sweep, after maintenance.olderThanDays, only
-  with maintenance.removeIdleWorktrees (off by default), and at disk pressure
-  level 3 once that activity is older than
-  maintenance.pressureProtectMinutes and at least 5 minutes old, whatever
-  the setting; unreadable activity keeps it. Removal re-checks, under the removal
-  locks, that HEAD did not move and the worktree is still idle, and
-  \`stim worktree remove\` still refuses dirty or unpushed work.
+  branch, reset onto one, or a detached HEAD; the MERGED rule above) holds
+  nothing git would lose, but looks the same as one just made by git
+  worktree add. gc --delete and the maintenance worktree check remove a clean
+  one without an open pull request once the RECENT ACTIVITY sources above
+  are older than gc.worktreeGraceMinutes and maintenance.protectRecentHours
+  (2 hours by default), and never younger than 5 minutes (reason
+  recent-activity until then, activity-unknown when they cannot be read). At
+  disk pressure level 3 the window is maintenance.pressureProtectMinutes,
+  still at least 5 minutes. Removal re-checks, under the removal locks, that
+  HEAD did not move and the worktree is still idle, and \`stim worktree
+  remove\` still refuses dirty or unpushed work. A process Stim does not
+  track, such as a benchmark run from a detached build, does not keep it.
+
+  ARCHIVED CHANGES: a dirty worktree that is otherwise finished, idle past
+  RECENT ACTIVITY and not in use is archived, then removed, by gc --delete
+  and the maintenance worktree check. Under the removal locks Stim writes
+  \`git diff --binary HEAD\` (staged and unstaged changes together) to
+  tracked.patch, the untracked files git does not ignore to untracked.tar,
+  HEAD's commits the default branch lacks to head.bundle,
+  with a manifest.json naming the branch, HEAD, pull request and files, in
+  $STIM_HOME/archive/worktrees/<repository>/<branch-or-dir>-<timestamp>/.
+  Ignored files (node_modules, build output) are not saved. It verifies the
+  patch with \`git apply --check -R\`, the tarball's file list, and that no
+  archived file changed, again just before git removes the worktree; any
+  failure keeps the worktree and deletes the archive. It also keeps a
+  worktree whose archive.enabled is false, or false for a project registered
+  inside it, with archive.maxAgeDays or
+  archive.maxTotalGb 0, whose untracked files or patch exceed
+  archive.maxTotalGb, whose archive would leave less free disk than
+  budget.hardFloorDiskGb, whose staged version of a file differs from its
+  working tree, or that holds an untracked nested repository; disk
+  pressure level 3 never archives. Archives are 0700 and 0600 with no
+  redaction, so an untracked secret such as a .env file that git does not
+  ignore is saved; use archive.enabled false for a sensitive repository. A
+  \`git status\` or editor refresh that rewrites the index restarts RECENT
+  ACTIVITY. The removal line and the gc
+  and maintenance logs name the archive and the restore commands; head.bundle
+  exists only when the default branch lacks HEAD, and lets the restore work
+  after the branch is deleted:
+    git -C <repository> bundle unbundle <archive>/head.bundle    (with a bundle)
+    git -C <repository> worktree add --detach <path> <HEAD>
+    git -C <path> apply <archive>/tracked.patch
+    tar -xf <archive>/untracked.tar -C <path>
+  Archive retention, which runs before and after each new worktree archive
+  and after each removal that archives a workspace, deletes worktree archives
+  older than archive.maxAgeDays. A new archive that would not fit beside the
+  others in archive.maxTotalGb keeps its worktree instead, so the oldest are
+  deleted for size only after that cap is lowered. An archive whose removal
+  is still running holds an ownership claim and is never deleted. Plain \`stim worktree remove\` never archives; it
+  refuses dirty work as before.
 
   PULL REQUESTS: with fresh state, gc runs one \`gh api graphql\` query per
   repository that asks for the 20 newest pull requests of each linked worktree's branch, as
@@ -9389,9 +9703,10 @@ THE ONE CASE GC WILL NOT REAP
 			summary: "disk usage, workspace build outputs, logs and device recordings, AVD and build-log sizes, the data partition, trimming the shared caches",
 			body: () => `DISK
   Logs, state, pidfiles and Xcode DerivedData are under the global workspace
-  directory, and \`worktree remove\` reclaims them. \`gc --delete\` clears the
-  build outputs of workspaces nobody is using (WORKSPACE BUILD OUTPUTS
-  below) and keeps the rest. Gradle retains its normal
+  directory, and \`worktree remove\` reclaims them. \`gc --delete\` lightens
+  every workspace that is not building and did not run a native command in
+  the last 15 minutes, clearing its build outputs (WORKSPACE BUILD OUTPUTS
+  below), and keeps the rest. Gradle retains its normal
   project build directories while sharing task outputs through its build cache.
 
   Android AVDs normally live under ~/.android/avd, and a booted owned AVD can
@@ -9442,18 +9757,40 @@ a changed value.
 WORKSPACE BUILD OUTPUTS
   Each workspace directory holds derived-data/, gradle-build/, android-cas/,
   cache-provider/, macos/build, the staged macos/<Product>.app and macos/staging-*
-  leftovers. \`gc\` reports them as one detected cache, "Workspace build
-  outputs", with a per-workspace size, last use and verdict. Plain
-  \`gc --delete\` clears them for every workspace not in use (see \`guide
-  cleanup gc\`), before anything else. \`--older-than <days>\` limits that to
+  leftovers. The project's own android/app/build, android/build,
+  android/.gradle and .build count with them when git ignores every file in
+  the directory and tracks none; one that fails that check, or is not in a
+  git checkout, stays, and \`gc --delete\` prints why when the check fails
+  between the report and the deletion. ios/build stays: React Native's pod
+  install writes podspec facades and codegen output there that only pod
+  install recreates. \`gc\` reports them as one
+  detected cache, "Workspace build outputs", with a per-workspace size, last
+  use and verdict. Plain \`gc --delete\` lightens every workspace, before
+  anything else, by clearing them, and prints the bytes freed per workspace.
+  A workspace whose worktree is locked with git worktree lock is never
+  lightened: not its outputs, not its project's build directories, at any
+  disk pressure level, including gc --older-than and the budget, and gc and
+  the maintenance log name the lock. The outputs also stay when git lists
+  nothing for a project inside a git checkout (code lock-unknown). A
+  running dev server, a booted or hosted simulator or emulator and a managed
+  tunnel no longer keep them. They stay while the workspace is building (its
+  native-run.lock is held, a live or unresolvable build lock or slot names
+  it, or its build claim is live), while its macOS app or build runs or cannot
+  be verified, and for 15 minutes after its last ios, android or macos run,
+  cache hits included, as recorded in state.json's build records. Dev server
+  starts, reloads and logs do not count as a native run. The shared build
+  cache, the Xcode compilation cache, the Gradle caches and the Metro cache
+  are never touched. \`--older-than <days>\` limits that to
   workspaces idle at least that long, and keeps one whose last use is
   unknown. \`--cache workspaces\` acts on them alone, except in the workspace
   directories that plain \`gc --delete\` removes whole (dead projects and
   orphaned directories); \`--cache all\` includes them. macos/ itself,
   macos/runtime.lock and its claim set, workspace.json, state.json, logs/,
-  other macOS files, locks and device records stay, as does the project's
-  own .build. The workspace keeps its devices and ports. A running, building,
-  unverified or hosted macOS app keeps its workspace untouched.
+  other macOS files, locks and device records stay. The workspace keeps its
+  devices, ports and running dev server. Automatic maintenance at disk
+  pressure level 2 clears them by the same rule (DISK PRESSURE LEVELS); level
+  1 keeps its own rules. A running, building, unverified or hosted macOS app
+  keeps its workspace untouched.
     stim gc --delete --cache workspaces --older-than 7
   Last use is the newest of the lastUsedAt that start, ios, android, reload
   and worktree warm record in state.json, lastBuild.startedAt,
@@ -9470,6 +9807,31 @@ WORKSPACE BUILD OUTPUTS
   build recompiles Swift. The next \`stim macos\` rebuilds its scratch from
   nothing (a full Swift build) and restages the app.
 
+WORKTREE DEPENDENCIES
+  Plain \`gc --delete\` also lightens linked worktrees: it deletes the
+  node_modules and ios/Pods at the root or a project root of a linked
+  worktree that has a Stim workspace, never the source checkout. A worktree
+  locked with git worktree lock keeps them always, so a rollback checkout
+  stays runnable. Otherwise a worktree keeps them while it is in use (its
+  dev server runs, a native run or build holds it), while it was used in
+  the last 15 minutes (a git index, HEAD or reflog write, a Stim state or
+  log write, or a write at the top of the directory), while git tracks a file in them, while a stim-server service
+  or the stim on PATH runs from it, while a live process has its command
+  line or working directory in it, and when the running processes cannot be
+  listed (always on Windows). It also keeps them when \`stim worktree warm\`
+  could not put the same thing back: warm would not copy that directory from
+  the source checkout (it is missing there, excluded by .worktreeexclude or
+  worktree.exclude, or inside a larger ignored directory such as a wholly
+  ignored ios/), the worktree's lockfile (or ios/Podfile.lock for Pods)
+  differs from the source checkout's, or the source checkout's own copy was
+  not installed from its lockfile. gc records what it deleted in the
+  workspace's lightened.json; the next \`stim start\`, \`stim ios\` or
+  \`stim android\` there runs \`stim worktree warm\` first to restore it, and
+  refuses with STIM_DEPS_FAILED, keeping the record, when those checks no
+  longer pass, when warm fails, or when it leaves a directory missing. A
+  deletion that stopped part-way is finished before the warm. Other commands, such as a test run, find the directory missing
+  until then. .pnpm-store stays: it is all clones and frees nothing.
+
 WORKSPACE LOGS
   \`gc\` reports the size of each workspace's logs/ (the workspaceLogs
   section of \`gc --json\`). metro.ndjson, client.ndjson and device.ndjson and
@@ -9529,6 +9891,12 @@ SHARED BUILD CACHES
   report-only because every Gradle build shares it. Stim reports its size
   but never prunes or empties it, including with --older-than or --cache all.
 
+  A cache directory that \`gc --delete --older-than\` cannot list (EACCES,
+  EPERM or ELOOP, for example) is a failed trim, not an empty one: the run
+  prints "N entries in <dir> could not be read or removed", records the cache
+  as failed and exits 1. Fix the directory's permissions and run it again. A
+  directory that is missing or is not a directory is not a failure.
+
   Trim rather than empty. Emptying costs the next build in every project the
   time the cache was saving.`
 		}
@@ -9649,12 +10017,16 @@ KEYS STIM READS
                         embedded JS, no Metro, cache keyed -release-sim, and
                         a JS-bundle swap on cache hits. The \`--configuration\`
                         flag overrides this per invocation. Unset means Debug.
-  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 machine is full or
-                        busy. Unset runs here; "local" runs here even when a
-                        lower layer says otherwise. A --device run ignores
-                        it. See lifecycle hosted-ios.
+  ios.remote            where the simulator runs, with the same meaning as
+                        --remote: "local" here, even when a lower layer says
+                        otherwise; "auto" here, and on an approved Mac from
+                        remote.machines when this machine is full or busy;
+                        "remote" on the first approved Mac in remote.machines
+                        order with room, here only when none takes it;
+                        "remote-only" the same but never here; a named
+                        approved Mac exactly that Mac; "proxy" or "eas" a
+                        remote device backend. Unset runs here. A --device run
+                        ignores it. See lifecycle hosted-ios.
   ios.projectPath       directory under the app holding a bare React Native
                         app's Xcode project and Podfile; default "ios". "."
                         is the app directory itself (RNTester's layout).
@@ -9875,14 +10247,13 @@ ${ANDROID_AVD_CONFIG_HELP.map((line) => `                          ${line}`).joi
                         password, handed to apksigner through its
                         environment, never its command line. Unset 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 machine is full or busy. Unset runs here; "local"
-                        runs here even when a lower layer says otherwise.
-                        A --device run ignores it. See lifecycle
-                        hosted-android.
-  remote.easFallback    true lets "auto" (ios.remote, android.remote or
-                        --remote auto) run the simulator or emulator on a
+  android.remote        where the emulator runs, with the same words as
+                        ios.remote: "local", "auto", "remote", "remote-only",
+                        a named approved Mac in remote.machines, "proxy" or
+                        "eas". Unset runs here. A --device run ignores it. See
+                        lifecycle hosted-android.
+  remote.easFallback    true lets "auto" or "remote" (ios.remote, android.remote
+                        or --remote) run the simulator or emulator on a
                         billed EAS Simulator when this machine is at its
                         concurrency.maxDevices cap (or has runs queued) and no
                         remote.machines entry takes the run, instead of waiting
@@ -10016,6 +10387,16 @@ ${ANDROID_AVD_CONFIG_HELP.map((line) => `                          ${line}`).joi
                         compiled into Contents/Resources before signing
   macos.resources       map of Contents/Resources destinations to source paths
                         relative to Package.swift; see stim guide macos
+  macos.remote          where stim macos launches the app, with the words of
+                        ios.remote except "eas" and "proxy": "local" here;
+                        "auto" here unless this machine is busy, then an
+                        approved Mac in remote.machines; "remote" on the
+                        first approved Mac in order with room, here only when
+                        none takes it; "remote-only" the same but never here,
+                        which keeps the app from taking focus on this Mac; a
+                        named Mac exactly that Mac. The --remote flag
+                        overrides it. A recorded hosted app keeps its Mac
+                        until stim stop. Unset runs here. See stim guide macos.
   web.url               the page \`stim web\` opens in the owned Chrome, an
                         http:// or https:// URL. {port:<label>} becomes the
                         workspace's named port (allocated like \`stim ports
@@ -10073,8 +10454,9 @@ ${ANDROID_AVD_CONFIG_HELP.map((line) => `                          ${line}`).joi
                         them from the environment or the machine layers.
 
 Each setting takes its documented type: string, array of strings, number,
-boolean, or object. ios.remote and android.remote accept backend names or
-tailnet machine names. metro.tunnel, web.viewport,
+boolean, or object. ios.remote, android.remote, macos.remote and remote.build
+accept placement words (local, auto, remote, remote-only) or tailnet machine
+names, and ios.remote and android.remote also the backend names. metro.tunnel, web.viewport,
 optimizations.android.compilerCache and optimizations.android.pch take only
 their listed choices. A value of the wrong
 type or outside those choices is refused by name on every command that resolves
@@ -10300,6 +10682,21 @@ simulator sessions on, by MagicDNS name with an optional serve port (default
   stim settings set remote.machines '["janics-mac-mini"]'
   stim doctor --fix
 
+The order of \`remote.machines\` is the priority order for every workload: the
+build, simulator, emulator and macOS app each go to the first listed machine that
+has approval, a free slot and a 5-minute load per core under that machine's own
+\`server.maxLoadPerCore\`, and the next one in order only when it does not. A
+machine at its caps, over its load limit, unreachable or lacking approval is
+skipped; load does not rank the machines that qualify, so the first one fills
+before the next is used. Put the fastest machine first and set the order with
+one command; \`stim doctor\` prints it as \`placement order\` and gives each
+machine a \`priority\` in its JSON:
+
+  stim settings set remote.machines '["fast-mini","slow-mini"]'
+
+A host reports its own load limit in its device offer; a stim-server older than
+that does not, and this machine's \`server.maxLoadPerCore\` stands in for it.
+
 Automatic membership is separate from approval. In Desktop Settings > Remote
 Machines, use Builds enabled and Simulators enabled for this machine or a
 configured remote. The equivalent machine settings list the excluded members;
@@ -10387,9 +10784,9 @@ An invalid remote.machines setting reports an error and preserves every saved cr
 replaced machine, run it, then re-add the name to request a new approval.
 A definite revoked or lapsed request can be requested again with --fix.
 An in-progress approval inspection reports busy rather than replacing its
-pending token. \`stim macos --remote <machine>\` runs a macOS app on an
-approved remote Mac (stim guide macos); \`ios\` and \`android\` do not yet
-place sessions on these Macs. To view or control a hosted macOS app, a person
+pending token. \`stim macos --remote <placement>\` or \`macos.remote\` runs a macOS
+app on an approved remote Mac (stim guide macos), and \`ios.remote\` and
+\`android.remote\` place simulators and emulators on them. To view or control a hosted macOS app, a person
 on that Mac approves Screen & System Audio Recording and Device Control and Data
 Access (Accessibility on macOS 26 and earlier) for Stim Host, the app
 \`stim-server service install\` runs the server under.
@@ -10436,18 +10833,35 @@ builds, or the build messages change; their Stim builds can differ. A
 stim-server too old to report one needs the same Stim build as this machine.
 
 \`remote.build\` (machine scope, default auto) selects placement for
-\`ios\`, \`android\` and \`macos\`. \`--remote-build <auto|local|name>\`
+\`ios\`, \`android\` and \`macos\`. \`--remote-build <local|auto|remote|remote-only|name>\`
 overrides STIM_REMOTE_BUILD, which overrides the setting. A blank environment
-value is unset. Trimmed auto/local are case-insensitive. Machine names match
+value is unset. \`doctor\` flags an invalid value in the machine config or in
+STIM_REMOTE_BUILD before a build refuses on it. Trimmed placement words are case-insensitive. Machine names match
 configured names case-insensitively, with port 7443 when omitted; reports use
 the configured entry.
 
-  auto   follows remote.buildMode, considering only enabled automatic pool members
-  local  builds only on this machine for this invocation
-  name   requires a matching entry in remote.machines, already paired and
-         approved for builds; ignores remote.buildMode and this machine's load/slot gating
+  local        builds only on this machine for this invocation
+  auto         (default) here while this machine has capacity, a remote
+               machine from remote.machines when it does not; only enabled
+               automatic pool members count
+  remote       on the first remote machine in remote.machines order that
+               accepts the build, here only when none does
+  remote-only  the same, never here: when no remote machine accepts the build
+               it refuses with STIM_OFFLOAD_REFUSED
+  name         requires a matching entry in remote.machines, already paired and
+               approved for builds; ignores this machine's load/slot gating
+
+\`remote.buildMode\` and STIM_REMOTE_BUILD_MODE were removed and are no longer read.
+\`doctor\` and \`stim settings\` report any left in a config file or the environment,
+\`stim settings set remote.buildMode\` refuses with the \`remote.build\` command that
+replaces it (auto stays auto, force becomes remote, off becomes local), and
+\`stim settings unset remote.buildMode\` removes the leftover key from every layer
+that has it (--scope limits it to one).
 
 A name never prompts for pairing, tries another remote machine or falls back here.
+remote-only refuses instead of building here for a build that cannot leave this
+machine (device, Release, an unknown simulator runtime, the build cache off), and
+when no pairing or approval exists.
 Any refusal or failure is STIM_OFFLOAD_REFUSED with the remote machine and reason.
 Device, Release/non-Debug, --remote, Android CAS compiler builds, builds with
 the build cache off, and an unknown simulator runtime cannot build there and
@@ -10474,26 +10888,29 @@ Copyable agent prompt:
   Run stim ios --remote-build janics-mac-mini. If it refuses, report the
   STIM_OFFLOAD_REFUSED reason and remedy; do not retry with another placement.
 
-With remote.build auto, \`remote.buildMode\` decides where an iOS simulator Debug build or an Android
-emulator debug build or a stim macos SwiftPM Debug build compiles:
+Which remote machine takes a build that leaves this machine follows the order of
+\`remote.machines\`: the first machine that accepts it, meaning it has a free slot
+(\`concurrency.maxBuilds\`), enough disk, a matching toolchain, and a load per core
+under its own \`server.maxLoadPerCore\`. A machine past its limit is skipped like a
+full one and the next in order is tried; the first machine fills to its caps before
+the next one gets a build. A machine that already holds the exact completed
+artifact goes ahead of the order, since that needs no build. With \`auto\` the
+build leaves this machine only when it is busy:
 
   auto   (default) here while this machine has capacity: a free
          \`concurrency.maxBuilds\` slot (always, with no build limit) and a
-         load per core under \`server.maxLoadPerCore\`. Otherwise on a
-         remote machine that accepts the build and is expected to be faster:
-         while every slot here is busy, any remote machine that accepts; while only
-         the load is high, one whose load per core is lower than this
-         machine's. A machine too old to report its load counts only while every
-         slot here is busy.
-  force  on a remote machine whenever one accepts it
-  off    here when local remains enabled in the automatic build pool
-
-For React Native and Expo, among machines that can take a new build, a matching dependency installation
-ranks before load. The worker checks the requested project, lockfile, install
-arguments and the major of the Node the app pins, and verifies that its modules
-and install marker remain present.
-Older workers' dependency hints and mere checkout or build-folder presence do
-not influence this ranking. Exact completed-artifact hits still come first.
+         load per core under \`server.maxLoadPerCore\`. Otherwise on the first
+         remote machine in order that accepts the build. A machine too old to
+         report its load counts only while every slot here is busy.
+  remote on the first remote machine in order that accepts the build, whatever
+         load this machine is under; here only when none does
+  remote-only  as remote, but when none does the build refuses
+
+A worker that holds a matching dependency installation does not rank ahead of an
+earlier machine in the order; it only saves the install on the machine that gets
+the build. The worker checks the requested project, lockfile, install arguments
+and the major of the Node the app pins, and verifies that its modules and install
+marker remain present.
 
 The worker installs dependencies with the lockfile nearest the app: the first
 pnpm-lock.yaml, yarn.lock or package-lock.json in its directory or above it in
@@ -10518,10 +10935,12 @@ Load per core is the 5-minute load average divided by the CPU count; a machine's
 native builds are its Stim runs in prebuild, pods or compile on that machine, not
 the ones it offloaded.
 \`server.maxLoadPerCore\` (default 2) is also the busy threshold for
-automatic iOS and Android device placement. It is the load per core at which a machine
-counts as saturated, both here and on a remote machine.
+automatic iOS, Android and macOS placement. It is the load per core at which a
+machine counts as saturated: each machine applies its own value, and a remote
+machine past it is skipped like a full one. \`stim status\` shows this machine's
+load per core against it, as \`capacity.load\` in JSON.
 
-STIM_REMOTE_BUILD_MODE overrides it for one command. Device, Release and
+Device, Release and
 \`--remote eas|proxy\` builds, Android builds with the Apple Clang CAS compiler cache,
 and iOS/Android runs with the build cache off, always build here. Hosted iOS
 Debug builds can use a separate --remote-build, targeting the hosting Mac's
@@ -10534,7 +10953,7 @@ verified compile; remote output is not published under an unverified client key.
 An offloaded iOS/Android build first runs prebuild (and \`pod install\` for iOS) here,
 then asks every paired machine what it can build. It takes one whose Stim
 build matches this Mac and, for iOS and macOS, CPU matches the target simulator, with enough disk, that does not decline,
-preferring the one that already holds this repository, then the least loaded,
+taking the first in remote.machines order that qualifies,
 and moves to the next one in that order when a machine that offered fails the
 sync or refuses to start the build.
 After a local and configured-provider miss, native Xcode simulator builds can
@@ -10566,7 +10985,7 @@ xcodebuild -downloadPlatform iOS -buildVersion <version>, or a pointer to the
 Xcode problem when xcode-select is the cause. A stim-server that reports no
 developerDir keeps the prose fix. It also needs an
 iPhone simulator on the target runtime. A missing or different global CocoaPods
-keeps automatic placement from choosing the machine for a project that does not
+keeps auto, remote and remote-only placement from choosing the machine for a project that does not
 pin it, unless the machine already holds the exact artifact; the placement line
 says why and doctor shows the install command. A named --remote-build still
 sends the build, and a pod install that fails there reports "pod install failed"
@@ -10730,6 +11149,9 @@ be setup steps are supplied by Stim on the command lines it composes itself:
                SWIFT_OTHER_PREFIX_MAPPINGS on a Swift 6.4+ toolchain -- so no
                Podfile post_install block (Xcode 26+ only, and skipped when the
                project configured ccache, which defeats it)
+               Debug builds for the iOS simulator also get
+               DEBUG_INFORMATION_FORMAT=dwarf, which skips the dSYM bundle;
+               Release and device builds keep the project's setting
   gradlew      --build-cache -- so no org.gradle.caching=true in a committed
                gradle.properties. Debug builds add
                -PreactNativeArchitectures=<target ABI> when the owned
@@ -11188,7 +11610,7 @@ var macos_default = {
 
 If Stim is not installed globally, replace stim with npx stim.
 
-ios --remote <machine> shares remote.machines and its separate device-host
+ios --remote <placement> shares remote.machines and its separate device-host
 approval. Read guide lifecycle hosted-ios for simulator placement and Metro.
 
 Run from the directory containing Package.swift. This prototype builds one
@@ -11248,7 +11670,10 @@ 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.
+STIM_MACOS_OWNER_UNVERIFIED or a failure, and removal keeps the workspace. For
+a hosted session the same rule covers every app bundle the session received, so
+stop and a replacement launch also end a copy that LaunchServices started from
+an earlier attempt.
 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, including for reopen events from open -g. An app that
@@ -11292,7 +11717,7 @@ Apple Swift, xcrun and xcodebuild selections can be reproduced; custom launchers
 require the checkout and otherwise miss safely. SWIFT_EXEC and SWIFT_EXEC_MANIFEST
 compiler overrides are resolved and versioned separately and require the checkout.
 The SDK selected by SDKROOT or SWIFTPM_SDKROOT_macosx is checked by real path and build version. Explicit local placement,
-remote build mode off, disabled pool members and remoteBuildCache
+disabled pool members and remoteBuildCache
 false skip peer lookup. Older workers keep their normal compilation path.
 --plan validates the Swift Package directory, macos settings, development plist
 and declared resources without building, signing, stopping or launching
@@ -11324,17 +11749,16 @@ line instead of when the app exits.
 
 BUILD OFFLOAD
 
---remote-build <auto|local|name> overrides STIM_REMOTE_BUILD and the
+--remote-build <local|auto|remote|remote-only|name> overrides STIM_REMOTE_BUILD and the
 machine setting remote.build (default auto). local builds here; a name
-requires the matching configured and paired remote Mac, ignoring remote.buildMode
-and this Mac's capacity. Any failure is STIM_OFFLOAD_REFUSED without a local xcodebuild, Gradle or
+requires the matching configured and paired remote Mac, ignoring this Mac's capacity. Any failure is STIM_OFFLOAD_REFUSED without a local xcodebuild, Gradle or
 SwiftPM compile or another machine. Invalid, unlisted or unpaired selections
 refuse before stopping the app or changing its build record. See stim guide errors STIM_OFFLOAD_REFUSED.
 
-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 builds here when local remains in the automatic
-build pool. remote.buildPoolDisabled excludes members from automatic placement,
+remote.build places these SwiftPM Debug builds: auto builds here while this Mac has
+capacity, remote uses the first approved build machine in remote.machines order that
+accepts and otherwise builds here, remote-only never builds here and refuses when none
+accepts, and local builds here. 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
@@ -11356,8 +11780,8 @@ identity comes from the worker's toolchain. Any other combination keeps the matc
 The client validates the development plist and resource entries before asking a machine. It verifies
 the returned archive's sha256, bundle identifier, executable, declared resources
 and ad hoc signature
-before replacing the owned bundle, then launches locally as usual. With auto, every offload
-failure falls back to the local build, including force. Failed staging preserves
+before replacing the owned bundle, then launches locally as usual. With auto or remote, every offload
+failure falls back to the local build. Failed staging preserves
 the previous bundle. No failed artifact is promoted or cached. The build record
 is unchanged by invalid, unlisted or unpaired setup refusals. It
 carries buildMachine (selected) and builtOn (here or the machine, absent until
@@ -11519,19 +11943,40 @@ used.
 
 ON ANOTHER MAC
 
-stim macos --remote <machine> builds the Debug app on this Mac and runs it on an
+stim macos --remote <machine> or macos.remote builds the Debug app on this Mac and runs it on an
 approved remote Mac over the tailnet, without SSH. The Mac must be listed
 in remote.machines and approved: stim doctor --fix makes a setup ticket, a
 person on that Mac runs stim-server setup with that ticket and expiry (guide
 settings), and stim doctor then pins that Mac's stim-server key. Stim goes ahead
 only with the stim-server that proves it holds that key.
-A refusal or an unreachable host fails the command; it never launches here
+A refusal or an unreachable host fails the command; with a named Mac it never launches here
 instead.
 
-The --remote value is a remote Mac name from remote.machines. macOS refuses
-eas and proxy because it has neither backend. It also refuses auto until
-automatic placement ships. These reserved names are case-insensitive and
-trimmed; they refuse with STIM_BAD_ARG before state access or a connection.
+The --remote flag and the macos.remote setting take the placement words of
+ios.remote and a remote Mac name from remote.machines; the flag overrides the
+setting:
+
+  local        launch here (the default when neither is set)
+  auto         launch here unless this Mac is busy (host memory pressure or load
+               per core at or above server.maxLoadPerCore), then on the first
+               approved Mac in remote.machines order that has room
+  remote       on the first approved Mac in remote.machines order that has room
+               and a load per core under its own server.maxLoadPerCore, here only
+               when none does
+  remote-only  the same, never here, so a macOS app never takes focus on this Mac:
+               when every Mac that answered is only full or loaded it waits up to
+               600 seconds for one with room and then refuses with STIM_AT_CAPACITY;
+               with no Mac that could ever take it (none configured, unreachable,
+               declined for another reason) it refuses at once with
+               STIM_HOSTING_REFUSED and the reason each Mac was skipped
+  <machine>    exactly that Mac, with no fallback
+
+A placement word picks the Mac on a new launch and keeps the recorded one while an
+app runs there, until stim stop. The command prints a placement: line with the
+choice and the skipped Macs. macOS refuses eas and proxy because it has neither
+backend. Reserved names are case-insensitive and trimmed; they refuse with
+STIM_BAD_ARG before state access or a connection. The device pool switches
+(remote.devicePoolDisabled) also apply to automatic macOS placement.
 
 Logs: the host records the hosted app's stdout, stderr and exit like a local run.
 stim logs, including --errors, --json and --follow, asks the host over the same
@@ -11618,6 +12063,12 @@ method the relay does not forward, is refused with an agent-device UNAUTHORIZED
 error whose details.reason is STIM_AGENT_REQUEST_REFUSED and whose message names
 the refused command or method; do not retry it.
 
+longpress, swipe, back and the other gestures are not in that list; the
+longpress and swipe that stim guide lifecycle lists belong to hosted Android and
+iOS sessions. click <ref> --button secondary reaches agent-device, but its native
+macOS backend, which the lease requires, answers UNSUPPORTED_OPERATION, so a
+hosted macOS app has no right click or context menu yet.
+
 Agents that built, launched and drove test copies on another Mac with an SSH
 script such as mini-desktop.sh use these instead:
 
@@ -11626,7 +12077,8 @@ script such as mini-desktop.sh use these instead:
   launch                     the same command; the host launches it under the
                              session's own home
   shot <out.png>             agent-device screenshot --remote-config <path>
-  click, rclick, key, type   agent-device click, press or type --remote-config <path>
+  click, key, type           agent-device click, press or type --remote-config <path>
+  rclick                     unavailable: secondary click is not supported
   quit                       stim stop (verified stop; the host frees the slot
                              and removes the app's defaults)
   clean                      stim worktree remove
@@ -11637,6 +12089,15 @@ The host's own owned devices count toward concurrency.maxDevices.
 
 The agent-device rows work once the host's agent field names agent-device.
 
+On macOS 27, agent-device screenshot of a hosted app can return an image of the
+window-sharing indicator (66x20 points, 132x40 pixels) instead of the app
+window. macOS adds that small window to the app while something captures the
+app, and agent-device picks it as the front window (callstack/agent-device#3961).
+snapshot -i lists it as an axdialog named "Window" with a
+WindowSharingSessionButton before the real window. Read the UI with snapshot
+until agent-device selects the app's main window. Commands that use the front
+window's frame, such as scroll, may also target the indicator.
+
 DESKTOP DOGFOOD
 
 This repository's apps/desktop/.stim.json selects the full StimDesktop app,