stim 1.25.0 → 1.27.0

package/dist/{guide-DR0K0xW9.mjs → guide-_rfEh_zM.mjs}

@@ -1,8 +1,8 @@
-import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-B5tCoq9N.mjs";
-import { i as findProjectRoot$1 } from "./project-BiC68mIp.mjs";
-import { h as RECENT_LAUNCH_MS } from "./eas-session-ledger-BMCA1gdO.mjs";
-import { o as guideStatus, t as WATCHMAN_NESTED_WORKTREES } from "./doctor-watchman-BovI1y3-.mjs";
-import "./status-watch-Bc2J4TZn.mjs";
+import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-BDVI8Ivc.mjs";
+import { i as findProjectRoot$1 } from "./project-DYj-HVx6.mjs";
+import { h as RECENT_LAUNCH_MS } from "./eas-session-ledger-DrP4OuuM.mjs";
+import { o as guideStatus, t as WATCHMAN_NESTED_WORKTREES } from "./doctor-watchman-CxDbyrrt.mjs";
+import "./status-watch-BfabQn03.mjs";
 import { SETTINGS, SETTINGS_SCHEMA_URL, TUTORIAL_VERSION } from "@stim-cli/core/state";
 import chalk from "chalk";
 //#region src/guide/agent.ts
@@ -188,6 +188,11 @@ RULES DURING THE LOOP
   you do other work.
 - Run ios or android again after a native input changes. A JavaScript-only
   change does not need one.
+- The build cache counts an installed package by its name and version, so it
+  cannot see a file you edit inside node_modules/. Change a dependency's native
+  code with a patch (patch-package or pnpm patch), which is hashed, or run ios or
+  android with --no-build-cache --remote-build local to compile it here. See
+  guide lifecycle builds.
 - For stale Metro transforms or file-map state, use stim start --reset-cache.
   It restarts only this app's verified owned Metro, preserving devices and other
   apps' caches. See guide lifecycle for reset scope.
@@ -292,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
@@ -322,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
@@ -395,7 +406,7 @@ FULL TOPIC LIST
   stim guide errors fallbacks     # swap, cache, and install notes on a release cache hit
   stim guide lifecycle            # the ordered flow, consent rules, and capacity
   stim guide lifecycle verification # reproduce, edit, verify the UI, and retain proof
-  stim guide lifecycle readiness  # add optional app readiness logs; no package required
+  stim guide lifecycle readiness  # add recommended app readiness logs; no package required
   stim guide lifecycle builds     # build optimizations, optional cache warm-up, fingerprints
   stim guide lifecycle concurrency # shared builds, wait timeouts, capacity limits
   stim guide lifecycle budget     # disk and memory budgets, automatic reclaim
@@ -1009,7 +1020,7 @@ leased until <time>" for each one.`,
                                  JavaScript running -- the first screen may
                                  still be rendering\` (\`stable for 3s\` when
                                  no \`Running\` log arrived). Poll the UI
-                                 before you trust a screenshot. Optional
+                                 before you trust a screenshot. Recommended
                                  app-declared readiness adds a separate
                                  stderr readiness phase; it does not change
                                  this field. See
@@ -1256,13 +1267,27 @@ leased until <time>" for each one.`,
                   pins Node (bin, version and match are null when no install
                   fits the pin; match is "exact", or "major" for the newest
                   install of the pinned major not older than the pin), else null
-  remoteMachines  one { machine, state, dnsName?, deviceId?, requestedAt?,
+  remoteMachines  one { machine, state, diagnosis?, dnsName?, deviceId?, requestedAt?,
                   expiresAt?, offloadable?, reasons?, problems?, capacity?, host? } per
                   remote.machines entry, for its build approval; state is "approved", "pending", "not-asked",
                   "revoked" (revoked or denied), "lapsed" (the request lapsed
                   before approval), "key-changed", "outdated",
                   "not-on-tailnet", "tailscale-off", "unreachable" or
-                  "invalid". host has the same shape and presence rule as in
+                  "invalid". diagnosis is { layer, code, title, message, remedy }
+                  for the first layer that stopped this machine, present for
+                  "tailscale-off", "not-on-tailnet", "outdated" and "unreachable"
+                  (deviceHosts carries it too); the codes are
+                  tailscale-stopped, tailscale-logged-out, tailscale-unavailable
+                  (this machine's Tailscale), peer-not-found, peer-ambiguous,
+                  peer-offline (with last seen), peer-no-answer (the connection
+                  got no reply and tailscale ping fails), route-missing (nothing accepts
+                  connections on the serve port), route-tls, route-http-error
+                  (any HTTP status but 502 and 503), server-not-running (502:
+                  nothing behind the route), server-not-ready (503: running but
+                  not serving; its message gives the cause the server reports),
+                  server-no-answer (silent route while tailscale ping reaches the Mac), server-outdated and connect-failed (none of the above).
+                  Tailscale's own "offline" flag lags a reachable peer, so an
+                  answer from the machine outranks it. host has the same shape and presence rule as in
                   deviceHosts, as do expiresAt (a pending request's lapse
                   time) and "lapsed" (--fix asks again). An approved machine also carries offloadable,
                   true when it would take this app's builds now (iOS
@@ -1278,7 +1303,16 @@ leased until <time>" for each one.`,
                   checkout, stim-build, arch, xcode, simulator-sdk, macos-sdk,
                   cocoapods, bundler, runtime, jdk, android-sdk, ndk,
                   build-tools, compile-sdk, disk, busy or platform). problems lists the same
-                  reasons as { code, reason } with that code. capacity
+                  reasons as { code, reason } with that code; an ndk, build-tools,
+                  compile-sdk, jdk, xcode or runtime problem can also carry commands and a
+                  lead, the lines to run on that machine (sdkmanager, the JDK install,
+                  xcode-select, xcodebuild or xcodes) and what they do, or followsFrom, the
+                  code of the problem whose fix also clears it. notes lists what a build there does without stopping:
+                  { code, reason, commands, lead } for an ndk, build-tools or compile-sdk package its
+                  Android SDK lacks and Gradle downloads on the first build (licenses
+                  accepted there, no android.builder.sdkDownload=false in the app), with the sdkmanager
+                  command that installs it ahead of time; each
+                  also a build-machine-<code> finding at level note. capacity
                   is the machine's offer: { running, max, diskFreeBytes,
                   minDiskFreeBytes, cpus?, loadPerCore?, builds?, maxBuilds?,
                   maxLoadPerCore?, memoryUsedBytes?, memoryTotalBytes?, declined? }; an older stim-server omits the
@@ -1289,6 +1323,7 @@ leased until <time>" for each one.`,
                   with an abnormally large footprint and, when it is safe to
                   restart, the command
                   offload-candidate is a note after 3+ successful local cold builds in 7 days average over 3 min, with no remote.machines and an online tailnet Mac; open Stim Desktop Settings > Remote Machines > Add
+                  readiness-markers-missing is a note when no JS or TS source under the app directory contains [stim:readiness]; the scan skips node_modules, native and build output directories and dot-directories, and reports nothing past 5000 source files; see stim guide lifecycle readiness
 
 ON FAILURE
   \`start\`, \`ios\`, \`android\` and \`web\` all print the error contract instead,
@@ -1306,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,
@@ -1503,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
@@ -1571,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
@@ -1672,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
@@ -1742,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
@@ -2244,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:
 
@@ -2440,6 +2494,8 @@ RULES
     lastPass carries startedAt, durationMs, trigger, mode, freedBytes
     (0 in report mode), actions, stopped (0), blocked. recent holds the last 20 action, failure
     and blocked NDJSON records from maintenance/maintenance.ndjson.
+    What each run cleared, kept or failed is in $STIM_HOME/gc/gc.ndjson,
+    read with \`stim logs --source gc --json\` (\`guide logs\`, GC LOG).
     invalid names invalid settings; invalid cache caps use their defaults,
     while invalid maintenance settings disable passes. claim contains an
     unresolved claim's path and reason, plus removeCommand from the claim
@@ -2519,9 +2575,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
@@ -2676,9 +2733,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.
@@ -3168,6 +3225,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);
+                   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
@@ -3220,7 +3279,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
@@ -3338,12 +3398,99 @@ 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;
 failures before a later launch marker are hidden. Machine passes are reported in
 status and maintenance/maintenance.ndjson; this command reads workspace logs.
 
+GC LOG
+stim logs --source gc reads $STIM_HOME/gc/gc.ndjson from any directory: one
+record per item that a gc run, a maintenance action or the budget gate
+cleared, kept or failed to clear. It cannot be combined with other sources,
+and --source all does not include it. --errors shows the failed items.
+Each record has src: gc, level (info, or error for a failed item), msg and
+  runId    the stim invocation, or the pass id of maintenance.ndjson
+  trigger  manual (stim gc in a terminal), desktop (STIM_DESKTOP_APP is set, so also a gc run through a stim-server Desktop started),
+           maintenance, or budget (the disk, memory or workspace check before
+           start, ios and android)
+  via      maintenance only: the command whose run started the pass
+  options  gc only: delete, worktrees, olderThan, cache, idleMs
+  kind     what the item was (the kind of gc --json results, plus devServer
+           for a dev server the budget gate stops; maintenance also writes
+           buildDirectory and dependencies)
+  status   done, kept or failed
+  label, id, path, bytes, detail
+           name, identifier, absolute path when the item is one, bytes freed,
+           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
+  stimVersion     the stim that ran the build
+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,
@@ -3373,16 +3520,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
@@ -3403,6 +3579,10 @@ they stay in the local logs. These records carry no tokens.
 
 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,
@@ -3425,7 +3605,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:
 
@@ -3436,7 +3617,7 @@ WHAT WRITES WHAT
                        The count does not attribute unknown OS errors to the app.
                        Known JavaScript errors also print individually: Android
                        ReactNativeJS records, and iOS com.facebook.react.log /
-                       javascript records. These can interrupt an optional
+                       javascript records. These can interrupt a recommended
                        readiness wait even without a client or Metro copy.
                        Client and Metro errors still print individually.
                        A native app that loaded its bundle but reported app errors
@@ -3618,7 +3799,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
@@ -3740,9 +3926,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",
@@ -3980,6 +4171,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
@@ -3987,7 +4183,12 @@ too old to speak protocol 2, incompatible
 toolchain/runtime/CPU, low disk, busy, sync/build failure, artifact failure,
 or a checkout that changed while it built. Unsupported build kinds also refuse.
 No local xcodebuild, Gradle or SwiftPM compile or alternate machine follows a
-refusal. Prebuild and pod install still run on this machine before a named offload.
+refusal. For stim ios, a toolchain difference on the named machine, such as Xcode,
+the simulator runtime or the CPU, refuses before this machine runs prebuild or pod
+install, even when prebuild would have produced an app the local cache already holds, or the
+machine already holds the exact artifact. A
+missing or different global CocoaPods never refuses a named machine; a pod install
+that fails on it reports "pod install failed" with the command to run there.
 Unlisted or unpaired names refuse at setup before consulting the cache, without
 a build record or failed-run stats. A listed paired name with a cache hit needs
 no build and does not contact the selected machine.
@@ -4003,7 +4204,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.
 `
 		},
@@ -4098,6 +4299,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.`
 		},
@@ -4379,6 +4587,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
@@ -4481,6 +4699,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
@@ -4920,8 +5143,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
@@ -4930,8 +5153,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: {
@@ -5144,8 +5370,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",
@@ -5442,10 +5669,11 @@ simulators to volume zero through Xcode's devicectl, and Android 15 and later
 emulators to media volume zero. The iOS mute runs after SimSlim has applied its
 profile and once SpringBoard has finished starting, because both a SimSlim
 reboot and SpringBoard's startup reset the volume. A device that is already
-running keeps its volume, except that SimSlim reboots a running simulator whose
-profile changed. Turn sound on for one device with Sound (iOS) or
-Media sound (Android) in its Stim Desktop options; the choice lasts until that
-device next boots. Android 14 and older images have no shell command that can
+running keeps its volume, except that a running simulator SimSlim reboots (a
+first slim, a profile change, or restoring stock services) is muted again once
+SpringBoard is back; an already slim simulator is not touched. Turn sound on
+for one device with Sound (iOS) or Media sound (Android) in its Stim Desktop
+options; the choice lasts until that device next boots. Android 14 and older images have no shell command that can
 set media volume, so startup warns, as it does whenever a mute is not
 confirmed. Host volume, Android alarm and ringtone volumes, hosted devices and
 physical devices are unchanged.
@@ -5840,9 +6068,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
@@ -5969,8 +6197,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.`
@@ -5990,28 +6218,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)
@@ -6028,7 +6272,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
@@ -6040,8 +6284,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.
@@ -6320,8 +6564,8 @@ command before any EAS lookup. stim doctor reports it in a project with eas.json
 If another run holds the artifact claim, wait for it to finish and retry.`
 		},
 		readiness: {
-			summary: "implement optional pending/ready app logs, deadlines, errors, and platform isolation",
-			body: () => `OPTIONAL APP READINESS
+			summary: "implement recommended pending/ready app logs, deadlines, errors, and platform isolation",
+			body: () => `RECOMMENDED APP READINESS
 
 No package or SDK is needed. This applies to debug ios/android launches with
 Metro verification enabled, not release builds or --no-metro-check.
@@ -6382,7 +6626,10 @@ Only exact standalone info/debug messages captured from this app's device log
 for this platform and current launch are accepted. Stale, other-platform,
 error-level, and embedded example messages are ignored. Unlabelled shared
 Metro output cannot identify a platform. If pending is not captured in time,
-including when device logs are unavailable, the default check applies.
+including when device logs are unavailable, the default check applies. On a
+device hosted on another Mac (--remote <machine>), the device log is the copy
+pulled from that Mac during the launch check, and each window waits up to 10
+seconds for the copy to cover it.
 
 The app declares readiness; Stim does not inspect a rendered frame. This does
 not change launched JSON semantics or the need to inspect the expected UI and
@@ -6674,7 +6921,8 @@ result as proof instead of requiring an unrelated screenshot.`
 
   \`gc --older-than <days>\` reports and deletes, or with \`--cache parked\`
   erases, only the devices parked at least that long; one parked at an unknown
-  time stays.
+  time stays. Automatic maintenance's daily age sweep deletes the devices
+  parked for maintenance.olderThanDays (7; 0 never) the same way.
 
   If simulator listing or deletion fails, \`gc --delete\` reports the failure
   and keeps that entry. It never turns an unverified absence into a dropped
@@ -6846,11 +7094,27 @@ IOS SCHEME SELECTION
 
 AN ARTIFACT THE DEVICE ALREADY HOLDS IS NOT INSTALLED AGAIN
   Both platforms store the artifact verbatim, so its hash is its identity.
-  Before installing, Stim hashes the artifact it is about to install and the
-  one the device already has -- \`pm path\` then \`sha256sum\` on Android, the
-  \`simctl get_app_container\` bundle on iOS. Byte-identical means the install
-  is skipped. The phase still reports the cost of proving that identity, but
-  avoids the ~43s a 400MB APK can cost to copy and install over USB.
+  Before installing, Stim compares the artifact it is about to install with
+  the one the device already has. On iOS it hashes both bundles: the
+  \`simctl get_app_container\` bundle and the one about to be installed.
+  Byte-identical means the install is skipped. The phase still reports the
+  cost of proving that identity, but avoids the ~43s a 400MB APK can cost to
+  copy and install over USB.
+
+  On Android the proof is one \`adb shell\` call that returns the installed
+  APK's path, size, and the SHA-256 of its tail: the v2 or v3 signing block,
+  the central directory, and the end record. That tail carries the signed
+  digests of every other byte, and Android verified them when it installed
+  the APK. Stim verifies the local APK against the same digests once, with
+  \`apksigner verify\`, and keeps the size and tail digest in
+  \`apk-signed-tail.json\` beside the APK in its build cache entry (stored with
+  the build; an older entry gets it on first use). The same size and tail
+  digest mean the same file, on an owned emulator, an adopted one, a
+  \`--device\` phone and a plain rerun. A different size or tail digest
+  installs without hashing the whole APK. An APK outside a build cache entry,
+  one without a v2 or v3 signing block, an apksigner that is missing or fails,
+  and a device whose \`tail\` or \`stat\` does not answer as expected fall back
+  to \`pm path\` then \`sha256sum\` of the whole installed APK.
 
     install     unchanged (emulator-5584 already has this build) (0.4s)
 
@@ -6863,8 +7127,9 @@ AN ARTIFACT THE DEVICE ALREADY HOLDS IS NOT INSTALLED AGAIN
     install     unchanged (stim-app already has this build) (0.4s)
     install     dev client prepared (0.9s)
 
-  The skip needs PROOF. A package that is not installed, a split install, an
-  image without \`sha256sum\`, and any adb or simctl failure all read as
+  The skip needs PROOF. A package that is not installed, a split install, a
+  device that answers neither probe (no \`tail\` and no \`sha256sum\`), and any
+  adb or simctl failure all read as
   "cannot determine", and the run installs exactly as it always did. A release
   run swaps this workspace's JS into a COPY of the artifact, which is a
   different artifact and is therefore always installed.
@@ -7065,6 +7330,67 @@ THE BUILD CACHE HAS THREE LEVELS
   trims, and clears local caches only: the provider contract has no delete
   operation, so no local command can remove data a team or CI system shares.
 
+  WHAT THE KEY COUNTS. Stim runs @expo/fingerprint with its default
+  \`balanced\` preset, the one the project's own Expo uses. An installed
+  dependency, and a config plugin loaded from node_modules, counts by its name
+  and version, not by its files. A package whose real path is outside
+  node_modules -- a workspace package, a link: dependency, a local Expo module
+  -- counts by its files, and so do patches/, the app's committed ios/ or
+  android/, the evaluated app config and its local plugins. patches/ and
+  .yarn/patches/ next to a monorepo's lockfile count too, and so do the patch
+  hashes pnpm-lock.yaml records, wherever the patch files live. The app's
+  version, ios.buildNumber and android.versionCode, eas.json, .easignore and
+  the path overrides of react-native.config.js are left out, so a Release
+  cache hit keeps the version it was built with. A project that wants native
+  package files hashed sets \`preset: 'strict'\` in fingerprint.config.js, at
+  about twice the fingerprint's CPU.
+
+  AN EDIT INSIDE node_modules/ IS NOT SEEN. Editing a dependency's native file
+  in place (node_modules/<pkg>/ios, android, cpp, a podspec or build.gradle)
+  leaves the key unchanged, so the next run installs the cached app without
+  the edit. Make the change a patch (patch-package's patches/, or pnpm patch,
+  whose patches the fingerprint hashes), or build it with
+  \`--no-build-cache --remote-build local\`. --no-build-cache alone can still
+  place the build on another machine, which installs dependencies from the
+  lockfile and so builds without the edit. The fresh build is stored under the
+  unchanged key in the machine-wide cache and handed to any cache provider, so
+  every worktree reuses it, edit included, until the dependency's version or
+  patches change; undo the edit with another --no-build-cache build.
+
+  A KNOWN TREE SKIPS THE FULL FINGERPRINT. After a full fingerprint at the
+  first lookup of a React Native or Expo run, Stim records it in
+  $STIM_HOME/fingerprint-memo (~/.stim by default) under a static digest of
+  the tree: git blob ids of the native inputs git tracks, the contents of the
+  untracked, modified and ignored ones, the app config's sources and the files
+  and directories it names, each installed package's path, version and native
+  markers, the lockfile, and the environment variables the config and its
+  .env files read. Any worktree whose tree has the same digest, a fresh one
+  included, reuses the record instead of evaluating the config and running
+  autolinking:
+
+    fingerprint matches a recorded fingerprint of this tree; confirming it in the background
+
+  A full fingerprint then runs at low priority while the app installs and
+  launches. The record is put back only when it agrees. If the run reaches its
+  end first, it waits up to 3 seconds more, then gives the check up and leaves
+  no record, so the next run fingerprints in full. A disagreement prints a
+  warning naming both hashes at the end of the run and writes a
+  fingerprint_memo_stale record to the build log; run the command again to use
+  the current tree.
+
+  A config the digest cannot follow always fingerprints in full: a dynamic
+  require or import, process.env used other than by literal name, file,
+  process or network access while it is evaluated, a dotenv import, a
+  fileHookTransform, or a preset that hashes package files. A local config
+  plugin counts as evaluated too, with one exception: the digest does not
+  track the files a plugin that applies mods reads, assuming it reads them in
+  its mods at prebuild. A plugin that also puts what it reads into the config
+  is a gap only the background check catches. So does a project outside git or on Yarn Plug'n'Play. The record is
+  never consulted after prebuild or pod install, by a build worker, by doctor,
+  or with --no-build-cache; ios --plan and android --plan read one without
+  writing. Records are 0600, at most 256 per platform, and gc prunes them by
+  age with the other caches.
+
   A MISS EXPLAINS ITSELF. Each local cache entry keeps the per-source hashes
   of its fingerprint (hashes only, pruned with the entry). Before compiling,
   Stim compares the sources it is about to store with a baseline: the entry
@@ -7301,8 +7627,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",
@@ -7380,7 +7708,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
@@ -7397,9 +7732,13 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   status\` shows "shut down after 30m idle" on the device until the next
   \`ios\` or \`android\` run boots it again. When metro.idleStopMinutes is
   shorter, the dev server's idle stop first shuts down the devices idle that
-  long, because no supervisor is left to check afterwards. The supervisor
-  path does not check without a supervisor: release runs, and after
-  \`stim stop\`. The setting is read when the supervisor starts. Stim Desktop's simulator view is not a
+  long, because no supervisor is left to check afterwards. Devices with no
+  supervisor (release runs, a dev server that exited) are shut down by
+  automatic maintenance while maintenance.mode is on (guide cleanup): every maintenance.idleCheckMinutes
+  (5) a command starts a background check that applies each workspace's
+  current setting with the same idle rules, native-run lock recheck, status
+  and log record, and skips the workspace of the command that started it.
+  The supervisor reads the setting when it starts. Stim Desktop's simulator view is not a
   stim-server client and does not count as a viewer. Change it with
   \`stim settings set devices.idleShutdownMinutes <minutes> --scope machine\`;
   0 turns it off, and an explicit 0 stays 0.
@@ -7445,8 +7784,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
@@ -7554,12 +7893,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
@@ -7624,7 +7975,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.
 
@@ -8160,17 +8515,23 @@ THE POOL: WHICH DEVICE AN ID-LESS \`--device\` PICKS
   \`ios.simslim off\` opts that app out and restores stock services on its
   simulator. The defaults disable push, StoreKit, iCloud, Safari sync, Mail,
   Calendar and Contacts services, among others; move an app that needs them
-  to a profile that keeps those categories, or to \`off\`. A running or
-  parked simulator is slimmed the next time Stim boots or adopts it, and an
-  already slim simulator is left alone, so only the first slim reboots it.
+  to a profile that keeps those categories, or to \`off\`. A running
+  simulator is slimmed on the next \`stim ios\`, without a boot first, and a
+  parked simulator when Stim adopts it. An already slim simulator is left
+  alone, so only the first slim reboots it.
   Without the \`simslim\` command, doctor reports it and \`stim ios\` boots
   the simulator unslimmed with a one-line note. Hosted simulators on a named
   Mac are never slimmed, whatever either Mac's setting says.
 
   SimSlim 0.8 requires iOS 18.5 or newer. On each local \`stim ios\`,
   Stim reconciles that profile on the owned simulator before the app build.
-  The first change can update services and reboot the simulator. A matching
-  profile is a fast no-op on later launches. The settings persist across normal
+  The first change can update services and reboot the simulator. Stim records
+  the applied profile (the default categories, or a hash of the profile file)
+  and the boot of the simulator it was applied on, so a later launch on the
+  same boot with the same profile skips the \`simslim\` call. A changed
+  profile, a reboot, or a missing record reconciles again. A manual
+  \`simslim off\` on a running simulator is not noticed until the simulator
+  reboots or the profile changes. The settings persist across normal
   shutdowns and reboots. Removing the setting restores stock services when
   Stim applied the profile. Stim never changes an unowned or remote simulator.
   Each SimSlim operation has a 12-minute outer deadline, including discovery.
@@ -8267,13 +8628,14 @@ and logs, and never deletes anything. off disables it. It is off in CI and
 scoped STIM_HOME homes unless STIM_MAINTENANCE is explicit, so a scratch home
 or CI run never deletes on its own.
 Commands trigger a detached pass when a check is due: disk and memory pressure
-(every minute), directory sizes (hourly), finished worktrees (every 15
-minutes) and the age sweep (daily). guide, settings, help and every gc
+(every minute), idle devices (every 5 minutes, maintenance.idleCheckMinutes),
+directory sizes (hourly), finished worktrees (every 15 minutes) and the age
+sweep (daily). guide, settings, help and every gc
 invocation do not trigger it; gc without --delete prints the maintenance plan
 itself.
 status --watch and every running dev server supervisor also trigger checks
 each minute, so the disk check runs while no command does.
-Size, worktree and sweep checks defer under high load. Attempts back off for at
+Size, idle, worktree and sweep checks defer under high load. Attempts back off for at
 least one minute. Measured directories are workspace build outputs and Stim's
 shared native, Metro, ccache, Swift compilation and registered caches. The size
 check also records the disk of each owned and parked simulator and emulator
@@ -8282,7 +8644,10 @@ Pressure checks read free disk on the Stim home, projects and worker root
 volumes. On macOS the memory signal is the sysctl pressure level, with no
 signal if sysctl fails. Other platforms use os.freemem(); macOS never falls
 back to it. Memory pressure is recorded only; stopping devices, dev servers
-and helpers is not automatic. While the level is warning or critical, the
+and helpers for memory is not automatic. The idle check shuts down (never
+deletes) owned simulators and emulators idle for their workspace's
+devices.idleShutdownMinutes, also with no supervisor running, through the
+supervisor's idle rules and records (guide lifecycle budget). While the level is warning or critical, the
 check also names abnormally large processes (guide lifecycle simslim) in
 status's maintenance block and the maintenance log.
 
@@ -8299,13 +8664,28 @@ In on mode a pass runs, cheapest to rebuild first:
      claim (taken for each xcodebuild run that compiles with it) or that
      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)
-  6. owned simulators and emulators of a finished worktree that is kept, such
+     worktree rules and gc.worktreeGraceMinutes; maintenance.removeFinishedWorktrees),
+     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
+     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
      as a dirty one (not one locked with git worktree lock), once it finished
      and was idle for gc.worktreeGraceMinutes (at least protectRecentHours),
      and of any
      workspace idle for maintenance.deviceIdleDays (3; 0 turns it off) in the
      age sweep. Devices are recreated on the next run.
+The age sweep runs every maintenance.sweepHours (24) in the background of
+commands, never at a set hour.
+maintenance.olderThanDays (7) is its age for steps 2, 3, 5 and 6; with 0 the
+sweep removes nothing in them by age, while step 1, step 7, finished
+worktrees and the cap and disk-driven parts of steps 2 and 3 still run.
 Disk-driven steps stop once free space is back above the floor. Kept for
 every pass: a workspace that is in use, holds a lock, was used within
 maintenance.protectRecentHours, is pinned with maintenance.keep, or is the
@@ -8328,14 +8708,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)
@@ -8345,12 +8732,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
@@ -8363,8 +8752,11 @@ DISK PRESSURE LEVELS
        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
+  lock or build 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.
@@ -8401,6 +8793,23 @@ claim fails with ENOSPC or EDQUOT, the pass deletes it and retries once, so a
 pass starts at zero free disk as long as an earlier pass left the reserve; the
 pass writes it again at its end.
 
+WHAT WAS CLEARED
+Every run that deletes or changes something appends one record per item to
+the machine gc log, $STIM_HOME/gc/gc.ndjson: gc --delete with any flags, gc
+--idle, gc --cache --delete, each maintenance action taken, and what the budget gate
+reclaims before stim start, ios or android. A dry run writes nothing, and a
+gc run that only kept items writes nothing. Failed and kept items carry their
+reason. The file rotates at maintenance.logMaxMb and its old generation is
+kept for maintenance.logRetentionDays, like the maintenance log.
+  stim logs --source gc           the retained records, oldest first
+  stim logs --source gc --json    one record per line
+  stim logs --source gc --errors  only the items that failed
+gc works from any directory because the log is machine-wide; it cannot be
+combined with other --source values and --source all leaves it out. Fields
+(\`guide logs\`, GC LOG): runId, trigger (manual, desktop, maintenance or
+budget), options, kind, status (done, kept or failed), label, id, path,
+bytes, detail.
+
 CLEANUP AND DISK
 
 worktree remove stops the agent-device daemon when the workspace's
@@ -8478,6 +8887,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.
 
@@ -8668,7 +9082,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
@@ -8677,11 +9094,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
@@ -8698,14 +9118,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
@@ -8736,14 +9159,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
@@ -8798,18 +9224,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
-  only 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
@@ -9201,9 +9665,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
@@ -9254,18 +9719,35 @@ 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 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,
@@ -9282,6 +9764,30 @@ 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
+  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
@@ -9341,6 +9847,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.`
 		}
@@ -9461,12 +9973,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).
@@ -9495,9 +10011,9 @@ KEYS STIM READS
                         iOS work after reviewing service tradeoffs; see
                         \`stim guide lifecycle simslim\`. Each local \`stim ios\`
                         reconciles the profile on its Stim-owned simulator.
-                        The first change can reboot it; a matching profile is a
-                        fast no-op. Removing the setting restores stock services
-                        when Stim applied the profile. Absolute paths, root or
+                        The first change can reboot it; an unchanged profile on
+                        the same boot is skipped. Removing the setting
+                        restores stock services when Stim applied the profile. Absolute paths, root or
                         symlink escapes, and missing files are refused before
                         simulator creation. Remote and unowned simulators are
                         never changed.
@@ -9687,14 +10203,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
@@ -9828,6 +10343,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
@@ -9885,8 +10410,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
@@ -10088,6 +10614,11 @@ never decide who the worker is. With --fix, a pending entry is replaced when
 STIM_ACCESS_TICKET names another ticket.
 Approved doctor entries under remoteMachines and deviceHosts include host
 { name, screenRecording, accessibility } when the worker reports it.
+A remote machine doctor cannot use carries a diagnosis { layer, code, title,
+message, remedy } naming the first layer that failed: Tailscale on this machine,
+the peer, the serve route, stim-server, or compatibility. Tell the user its
+message and remedy; the remedies run on the remote machine or in Tailscale, so
+agents do not run them. \`stim guide facts doctor\` lists the codes.
 
 REMOTE MACHINES AND PHONE APP
 When the user mentions slow builds, a busy machine, a full disk or device limit, or
@@ -10107,6 +10638,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;
@@ -10194,9 +10740,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.
@@ -10243,18 +10789,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
@@ -10263,7 +10826,8 @@ at setup before consulting the cache; they create no build record or failed-run
 stats. A listed paired name with a cache hit compiles nothing, contacts no worker
 and records buildMachine with builtOn absent. Build failures retain the selected
 value; builtOn is here or the configured machine entry when compilation ran.
-Prebuild and pod install still run on this machine before a named offload. A refusal
+Prebuild and pod install still run on this machine before a named offload; stim ios
+checks the machine's toolchain first. A refusal
 starts no local xcodebuild, Gradle or SwiftPM compile.
 A React Native offload sends the tracked and untracked files, and the gitignored
 files the native fingerprint hashes or the Expo config reads, such as .env.local
@@ -10280,26 +10844,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
@@ -10324,10 +10891,11 @@ 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_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
@@ -10340,7 +10908,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
@@ -10360,18 +10928,44 @@ match. Completed archives survive worker checkout changes or removal; hits
 need no source upload or build slot. Disabled remote artifact reads skip this
 lookup. Release and physical-device builds keep their existing paths.
 SwiftPM, compiler and dependency caches use their existing paths.
-For iOS the machine's Xcode and simulator SDK must match, and it needs an
-iPhone simulator on the target runtime. Its project-selected CocoaPods must match too, unless
-the app's Gemfile.lock, in ios/ or the project root, pins CocoaPods: both machines then run that version through
-bundler, so the machine needs only Bundler on its stim-server PATH and
+For iOS the machine's Xcode and simulator SDK must match. Its offer reports the
+developerDir xcode-select prints and the Xcode apps in /Applications (version,
+build, and license and first-launch checks while no Xcode works), so doctor's
+fix for no usable Xcode is the exact command to run there: sudo xcode-select -s
+<the Xcode with this machine's build, else the newest>/Contents/Developer when
+the Command Line Tools or another Xcode is selected, sudo xcodebuild -license
+accept and sudo xcodebuild -runFirstLaunch for the checks that fail, or xcodes
+install <version> with no Xcode app. A runtime the machine lacks gets
+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 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"
+with the fix on that machine. When the app's Gemfile.lock, in ios/ or the project
+root, pins CocoaPods, both machines run that version through
+bundler, so the machine needs Bundler on its stim-server PATH and
 installs the pinned gems itself on the first build. This Mac's side of the
 comparison runs \`pod --version\` in the directory pod install runs in. The comparison selects
 the app's .ruby-version when installed, otherwise rvm's or rbenv's default Ruby, and only when neither exists the GEM_HOME, GEM_PATH and Ruby-related PATH entries of the machine's login shell (read once with $SHELL -lic), unless the caller already sets GEM_HOME, with pod install's UTF-8 locale defaults. pod install, including the Bundler run, uses the same environment.
 For Android its CPU may differ, since the APK's ABIs come from the NDK, so an
 x86_64 Linux or Windows machine running stim-server can build for an Apple silicon Mac. Its JDK major
-version must match, and its Android SDK must hold the NDK, build-tools and
+version must match this machine's, which can be an installed JDK that is not the
+worker's default: its offer lists \`jdks\`, and a build sent with the build-jdk
+feature runs with JAVA_HOME at the one of that major. A major no installed JDK
+has gets the install command for the worker's OS as doctor's fix. A nearby major
+never counts (Gradle, AGP and Kotlin support and the shared build cache assume
+one JDK). Also, its Android SDK must hold the NDK, build-tools and
 compile platform that the project's React Native version names in
-gradle/libs.versions.toml; Gradle and AGP come from the synced project. When
+gradle/libs.versions.toml; Gradle and AGP come from the synced project. A
+package the SDK lacks is a note, not a blocker, when its offer reports the SDK
+licenses accepted (\`licenses/android-sdk-license\`) and the app's
+Gradle root's gradle.properties does not set android.builder.sdkDownload=false:
+Gradle downloads the package on the first build there (the NDK is about 1-2 GB).
+Otherwise it blocks, and doctor's fix is the sdkmanager commands to run on that
+machine; a stim-server that does not report its licenses keeps that rule. When
 no machine takes the build in auto placement, the run prints one line with each machine's
 reason, such as \`janics-mac-mini: busy (load at or above 2/core; load
 8.2/core, 2 builds) -> building here\`, and compiles here. It sends the files
@@ -10510,6 +11104,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
@@ -10968,7 +11565,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
@@ -11072,7 +11669,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
@@ -11104,17 +11701,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
@@ -11136,8 +11732,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
@@ -11299,19 +11895,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