stim 1.20.2 → 1.22.0

package/dist/{guide-G9cAbVAc.mjs → guide-Br0LEfKy.mjs}

@@ -1,8 +1,8 @@
-import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-B717odTD.mjs";
-import { r as findProjectRoot } from "./project-_phNIJfs.mjs";
-import { s as RECENT_LAUNCH_MS } from "./watchman-CPQFZLXY.mjs";
-import { o as guideStatus, t as WATCHMAN_NESTED_WORKTREES } from "./doctor-watchman-BRyV2adA.mjs";
-import "./status-watch-C23ILtf9.mjs";
+import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-C7O8A6ZI.mjs";
+import { i as findProjectRoot$1 } from "./project-wM_XFTvE.mjs";
+import { h as RECENT_LAUNCH_MS } from "./eas-session-ledger-DlY_serQ.mjs";
+import { o as guideStatus, t as WATCHMAN_NESTED_WORKTREES } from "./doctor-watchman-N2wDotwQ.mjs";
+import "./status-watch-Bg_u-pwR.mjs";
 import { SETTINGS, SETTINGS_SCHEMA_URL, TUTORIAL_VERSION } from "@stim-cli/core/state";
 import chalk from "chalk";
 //#region src/guide/agent.ts
@@ -117,7 +117,7 @@ other apps or other workspaces' devices.
   stim ios                             # or: stim android, or: stim web
 
 When Stim Desktop is installed, worktree warm, start, ios, android and web
-print "Open in Stim Desktop: <link>" on stderr (links.desktop in JSON). The
+print "Open in Stim: <link>" on stderr (links.desktop in JSON). The
 first time one prints it in a workspace, tell the user once: "You can watch
 this workspace in Stim Desktop: <link>". Do not repeat it after later
 commands. When no command prints it, do not mention Stim Desktop.
@@ -146,9 +146,9 @@ lifecycle builds.
 Agents never set STIM_ACCESS_TICKET, run stim-server setup, edit remote.*,
 server.* or hosting.* for the user, or approve requests. Read stim guide settings for
 Desktop access tickets and person-owned approval.
-Read stim guide settings to select a remote Mac. Keep a requested named
+Read stim guide settings to select a remote machine. Keep a requested named
 placement when recovering STIM_OFFLOAD_REFUSED: report its reason and remedy.
-When the user mentions slow builds, a busy Mac or wanting updates away from the desk, tell them about Stim Desktop > Settings > Remote Macs > Add or Phones > Pair a Phone; see stim guide settings.
+When the user mentions slow builds, a busy machine or wanting updates away from the desk, tell them about Stim Desktop > Settings > Remote Machines > Add or Phones > Pair a Phone; see stim guide settings.
 
 Read stim guide lifecycle concurrency when a build waits on another workspace
 or a build call times out. A native build can outlive a shell timeout; if the
@@ -260,6 +260,12 @@ holds it across runs; stim device unlock gives it back. Never delete another
 workspace's lease file under ~/.stim/device-locks; gc --delete removes expired
 ones.
 
+stim device provision ios [udid] registers a phone with the project's Apple
+Developer team and creates or refreshes its Development profile. It changes
+the team's developer account, so never run it, and never pass it --yes,
+without the user's explicit go-ahead for that step. When ios --device fails
+on signing, report the remedy and ask the user.
+
 stop and worktree remove release this workspace's leases. On a physical
 iPhone, stop also closes the app by ending its log collector; it does not
 shut down the phone or uninstall the app.
@@ -412,7 +418,7 @@ FULL TOPIC LIST
 //#endregion
 //#region src/guide/api.ts
 var api_default = {
-	summary: "Typed lifecycle API: createStim, build, run, stop, diagnostics, and cancellation",
+	summary: "Typed lifecycle API: createStim, build, run, reload, stop, warmWorktree, removeWorktree, diagnostics, doctor, GC, settings, stats, logs, and cancellation",
 	body: () => `PROGRAMMATIC API
 
 Install stim as a project dependency: npm install --save-dev stim.
@@ -430,18 +436,156 @@ Import { createStim, StimError } from 'stim'. Node 22.12 or later is required.
     }
   }
 
-createStim takes projectRoot, optional absolute home and buildCache paths,
-and onProgress({ stream, message }). message is an output chunk. Without
-onProgress, operations write nothing to the caller's stdout or stderr. Each
-operation uses a bundled worker that calls the same lifecycle operations as
-the CLI; it never parses CLI arguments or changes the caller's cwd/environment.
+createStim takes projectRoot, optional absolute home and buildCache paths, an
+env object (default process.env) that Stim reads its settings overrides from
+and passes to its child processes, and onProgress({ stream, message }). message is an
+output chunk. Without onProgress, operations write nothing to the caller's
+stdout or stderr. The home is fixed when the client is created: home, else
+STIM_HOME from env, else the default home. All operations run in the calling
+process against the client's home and project and call the same lifecycle
+operations as the CLI. None parses CLI arguments or changes the caller's
+cwd/environment.
+Custom Expo buildCacheProvider modules are not supported. Use EAS or a Stim
+cache provider.
+
+settings() returns the stim settings --json payload: every setting with its
+effective value, origin and per-layer values. An invalid environment override
+rejects with StimError STIM_BAD_ARG and its remedy. stats() returns the
+stim stats --json payload with the last recorded agent-device and SwiftPM cache
+usage instead of measuring them again.
+
+setSetting(key, text, { scope?, signal?, beforeWrite? }) and
+unsetSetting(key, { scope?, signal?, beforeWrite? }) share CLI validation and
+return its masked JSON write result. beforeWrite(workspace) runs once after
+resolving the target and before mutation or recording-lock waits; throwing
+refuses the write. Server adapters use it to admit that exact workspace.
+Later registry changes do not redirect the write or its returned setting.
+Pending writes cancel. After commit, recording deletion finishes before the
+promise settles, including when cancellation arrives during cleanup.
+
+plan({ platform, slot?, signal? }) returns the configured ios/android/macos next-build
+report, matching --plan --json, without building, launching or taking a device.
+slot applies to ios/android. A predicted build refusal stays in the report;
+a failure to produce a report rejects with StimError. Fingerprinting uses the
+existing cancellable report helper. Native probes and cache downloads drain
+before the report settles. Plans use the report budgets below. Providers must settle on abort;
+cleanup exceeding 35 seconds refuses with STIM_CLAIM_UNAVAILABLE and retains
+the download directory rather than deleting files a provider may still write.
+
+doctor({ platform? }) and gc({ cache?, olderThan?, worktrees? }) read reports in
+process with a 60 second execution budget. They accept signal and attempt
+owned cleanup before rejecting. Deadline expiry rejects with
+STIM_REPORT_TIMEOUT; a caller abort rejects with STIM_CANCELLED. A thrown
+onProgress callback cancels the report and is propagated unchanged.
+If child identity cannot be verified after a one-second retry budget, cleanup
+refuses with STIM_CLAIM_UNAVAILABLE instead of cancellation or timeout. The
+child cleanup error names the launcher PID; unverifiable processes and descendants are left
+untouched. On POSIX, a launcher that exited before identity capture can only finish
+successfully once its process group is proven gone.
+After a termination request, cleanup waits at most one second for a child to
+close. Overall cleanup has a 35 second budget, including temporary-worktree
+removal; unfinished cleanup returns STIM_CLAIM_UNAVAILABLE and leaves unresolved
+resources in place. Credential refresh waits asynchronously and checks
+cancellation before writing.
+On Windows, report probes require the built-in Windows PowerShell for process-tree containment.
+
+requestMachineAccess({ ticket?, signal? }) requests build and device-host access
+from configured remote machines without granting capabilities or repairing project
+state. It returns the iOS doctor report and records the completed project check
+after owned cleanup. A supplied ticket encodes 32 random bytes; omitting it
+generates or reuses a pending ticket instead of inheriting the process environment.
+A person approves each capability on the worker. Execution has a 120 second
+budget and cleanup uses the report's 35 second budget. Desktop requests access
+only through its matching-home bundled server's private desktop-machine-access
+subscription; cancellation waits for cleanup and reconnect never repeats it.
+
+warmWorktree({ signal?, beforeWarm? }) copies missing ignored state from the source
+checkout into the client's linked worktree in process. It returns { exitCode },
+0 or 1, without changing process.exitCode. Existing entries and tracked paths
+remain untouched. Copies share a source read claim and hold an exclusive target
+claim. beforeWarm(workspace) admits each canonical workspace in the resolved
+warming scope before registration or copying; throwing refuses warming.
+Progress uses onProgress. Cancellation drains the copy child before removing
+its partial entry or releasing claims. Unknown cleanup retains those claims
+and returns STIM_CLAIM_UNAVAILABLE with exact recovery paths. The execution
+budget is 90 minutes; cleanup still has the 35 second budget above. The API
+does not refresh the source or install dependencies; use CLI worktree warm
+--refresh for that.
+
+removeWorktree({ target?, force?, signal?, beforeRemove? }) runs the CLI's worktree removal
+safety checks and cleanup in process. target defaults to projectRoot; relative
+paths resolve against it. It returns { removed, exitCode } without changing
+process.exitCode. removed is true once a linked Git worktree is deleted, even
+if later branch cleanup fails. Source checkout environment cleanup can succeed
+with removed: false and exitCode: 0. force has the same destructive meaning as
+CLI --force. Cancellation stops pending work and waits for owned cleanup;
+completed actions remain applied. It uses the report budgets above.
+beforeRemove(workspace) runs for every canonical workspace in the resolved
+cleanup scope before effects, including registered descendants and pending
+branch cleanup. Throwing refuses the operation.
+
+gc() stays read-only. collectGarbage({ cache?, olderThan?, worktrees?, delete?,
+idleMs?, signal? }) runs the same GC selections and actions as the CLI, including
+an unscoped sweep. It returns { report, exitCode }; exitCode is 0 or 1 and does
+not change process.exitCode. delete: true enables deletion. idleMs reclaims
+owned devices idle for that many milliseconds, including without delete.
+The existing CLI rules for cache selection, workspace safety and scoped homes apply.
+
+A deletion or idle sweep takes this home's exclusive maintenance claim;
+concurrent maintenance rejects with STIM_CLAIM_REFUSED and names the held claim.
+Execution and cleanup use the report budgets above. Cancellation stops pending
+lock waits and further actions; completed actions remain applied. An archive
+whose history has started moving finishes publication before cancellation.
+Unresolved owned cleanup rejects with STIM_CLAIM_UNAVAILABLE and retains its
+actual ownership claims for recovery. Progress uses onProgress; GC does not
+replace the caller's console methods.
+
+doctor returns the doctor --json findings and metadata, with runningPath null
+because the caller imports the library rather than executing a Stim CLI. It
+never repairs the project. By default it does not record a check; record: true
+registers a supported iOS/Android project and records the checked platforms only
+after the report and owned cleanup succeed. Recording waits asynchronously for
+the config lock, honors signal, and rejects unavailable state. Existing remote approval
+checks can refresh their own pending credential records. gc returns the GC
+JSON dry-run report; it never deletes or shuts down idle devices. Report reads
+can refresh their own measured-usage caches. Supplying home or STIM_HOME retains
+the CLI's scoped-home restrictions on machine-global resources.
+
+logs({ tail, sources, minLevel, slot, since, grep, errorsOnly }) returns the raw
+stim logs --json records, including native crash capture, agent actions and Expo
+error context. It runs in process, with asynchronous chunked reads and bounded
+record selection when tail is supplied. A new file generation gets a compact
+metadata index; later queries reuse it and index only appended bytes.
+Matching agent actions are also selected within tail; attribution still scans
+each retained session generation to establish device ownership.
+followLogs(options, onRecord) emits the requested backfill followed by new records
+and returns a stop function. AbortSignal also stops the subscription.
+An optional third callback, onBackfill(records), receives initial records instead
+of onRecord. Its promise is awaited before reading another batch; with that
+callback and no tail, the timeline is selected in batches of at most 500.
+Appends still go to onRecord.
+Agent attribution still retains its matching records during this initial read.
+Local appends use filesystem hints with a ten-second repair scan; while a
+directory watch is unavailable, attachment and reads retry every 500 ms.
+Attachment also schedules one 500 ms recovery scan for watch startup.
+Expo context uses a settle timer only while an error is pending. The separate
+agent-action cursor and active hosted log queries keep their current sampling.
 
 run takes platform plus its options:
-  ios:     configuration, scheme, deviceType, runtime
+  ios:     configuration, scheme, deviceType, runtime, simulatorApp
   android: variant, systemImage, deviceProfile
-  macos:   remoteBuild
+  macos:   remoteBuild, remote
   web:     headed (default false)
-iOS and Android also accept slot, metroCheck, buildCache, and remoteBuild.
+iOS and Android also accept slot, metroCheck, buildCache, remoteBuild, remote,
+device, wait and easProfile. device: true auto-selects a physical device; a
+string pins its UDID or serial. wait takes seconds as a string, such as '30'.
+wait: false refuses a full owned-device slot immediately; on a physical device
+it bypasses another workspace's lease and can replace its running app, as CLI
+--no-wait does. easProfile downloads an existing compatible development build;
+it never starts an EAS build. iOS simulatorApp selects the simulator viewer.
+remote selects the launch host using the CLI's existing placement and approval
+rules; remoteBuild independently selects where compilation runs. macOS requires
+a named hosting Mac; auto, eas and proxy are not supported there.
 All methods accept signal. run builds, installs and launches.
 Web requires a running server, just like stim web.
 
@@ -449,6 +593,12 @@ build produces an artifact without acquiring a device, starting a runtime, or
 stopping an existing session. Its result is inferred from platform:
   const result = await stim.build({ platform: 'ios' });
   console.log(result.facts.appPath);
+  console.log(result.facts.links.workspace);
+
+Successful builds include facts.links.workspace, an HTTPS link to this workspace
+on this Stim home. Agents can share it with an already-paired phone or Desktop,
+including when Desktop is not installed on the build machine. Opening it only
+navigates; it does not install or launch the built app.
 
 Build options:
   ios:     scheme, configuration, arch (arm64, x86_64, all), buildCache, remoteBuild
@@ -464,22 +614,64 @@ writes its own build-artifact-<platform>.ndjson. No distribution archive or web
 pipeline is inferred. Use @stim-cli/ci's buildCI to export a portable artifact and
 diagnostics for your CI provider.
 
+Unresolved native Metro cleanup keeps error.details.cause.retainedClaimRoots and
+STIM_CLAIM_UNAVAILABLE even after cancellation. Web cancellation stops pending
+browser-lock and verification waits. A new browser launch is accounted for and
+stopped before cancellation finishes, or refuses with retained ownership when
+cleanup cannot be confirmed.
+
 run returns { platform, facts }. iOS facts include udid; Android includes
 serial; both include bundleId, appPath, metroPort, cacheHit and launched.
 macOS facts include bundle, bundleId, executable, pid, build and launched.
+A hosted macOS result has a null local pid and preserves true or 'unverified'
+from the host's launch evidence.
 Web facts contain the owned browser's existing launch and page facts.
 Do not interpret 'bundling' or 'unverified' as proven application readiness.
 
-stop({ slot? }) returns { ok, outcomes, summary }. It acts on the workspace,
-including resources from earlier runs. Use a dedicated workspace in CI.
-Cancellation waits for the operation worker to exit; stop with a fresh signal
+start({ remote?, resetCache?, waitSeconds?, signal?, beforeStart? }) starts or
+reuses the managed dev server, using the same settings and ownership rules as
+stim start. remote requests the configured public URL or tunnel. resetCache
+restarts the server with a cleared transform cache. waitSeconds is a positive
+whole number, defaulting to 60. The flat result is port, supervisorPid, mode,
+logsDir, agentDevice and alreadyRunning.
+beforeStart(workspace) runs once with the resolved app before usage recording
+or effects; throwing refuses startup. Cancellation stops pending probes and lock
+waits, then accounts for new children before returning. A verified supervisor
+handed off to the workspace may remain running. Unconfirmed cleanup refuses with
+STIM_CLAIM_UNAVAILABLE, taking precedence over cancellation or callback failure;
+follow its remedy before retrying. Startup never retries automatically.
+
+reload({ platform?, signal?, beforeReload? }) requests a JavaScript reload in
+the live iOS/Android app or reloads the owned Chrome page. It returns the flat
+stim reload --json facts: platform, deviceId, deviceName, appId, metroPort,
+strategy, targets and reverseRestored. Choose ios, android or web when more
+than one platform is live. A request does not prove completion; verify the UI
+and inspect logs. A Metro broadcast can reach other connected clients.
+beforeReload(workspace) runs once after resolving the workspace and before
+usage recording or dispatch; throwing refuses the action. Reload uses the
+60 second execution and 35 second cleanup budgets described above, including
+STIM_REPORT_TIMEOUT and STIM_CLAIM_UNAVAILABLE. Cancellation stops pending
+probes and dispatch, but cannot retract a reload already sent. It never retries.
+
+stop({ slot?, beforeStop? }) returns { ok, outcomes, summary }. It acts on the
+workspace, including resources from earlier runs. Use a dedicated workspace in CI.
+beforeStop(workspace) runs once with the resolved workspace before teardown;
+throwing refuses the operation.
+From a child directory, start and stop resolve the enclosing supported app.
+Cancellation drains the operation's owned work, a read kills its child
+processes, and both reject with STIM_CANCELLED. Cancelling stop while it waits
+for another native operation ends that wait. Once teardown starts, stop finishes
+cleanup before rejecting with STIM_CANCELLED. Its config, workspace-state, and lease lock waits are asynchronous.
+Stop with a fresh signal
 after cancellation or partial failure. Always inspect cleanup.ok.
 
 diagnostics({ tail: 200, errors: false }) returns { directory, records } from
 the local timeline, even before a successful run. tail: 0 returns paths only.
 It does not fetch remote logs or capture new crashes. Stim failures reject with
 StimError carrying code, message, remedy and details (including the log path).
-An exception thrown by onProgress cancels its worker and propagates unchanged.
+An exception thrown by onProgress stops further progress and propagates
+unchanged: build or run is cancelled, and stop or a read
+finishes its work first.
 
 Normal ownership, device creation, cache locks and coordination remain active.
 All concurrent artifact-cache writers must share the same coordinating home.
@@ -667,10 +859,10 @@ leased until <time>" for each one.`,
   agentDevice     { stateDir }: absolute workspace agent-device state path;
                   set AGENT_DEVICE_STATE_DIR to it (see guide logs)
   alreadyRunning  true when nothing needed starting
-  links           { desktop }: a stim-desktop://workspace?path=<workspace>
-                  link that shows this workspace in Stim Desktop. Absent when
-                  no app on this Mac opens stim-desktop links. Plain output
-                  prints it on stderr as "Open in Stim Desktop: <link>"; so
+  links           { desktop }: an HTTPS link containing this Stim home and
+                  workspace IDs, opened by Desktop here or an already-paired phone. Absent when
+                  no app on this machine opens stim-desktop links. Plain output
+                  prints it on stderr as "Open in Stim: <link>"; so
                   does worktree warm, which has no JSON payload
 
   stim macos --json
@@ -733,7 +925,7 @@ leased until <time>" for each one.`,
                   configuration is part of it: -release-sim vs
                   -debug-sim-arm64). A single-architecture simulator build
                   ends in its architecture (-arm64 or -x86-64): a local Debug
-                  build compiles this Mac's, a --remote build the remote
+                  build compiles this machine's, a --remote build the remote
                   host's. A local non-Debug simulator build compiles every
                   architecture the project lists and has no suffix
   With --eas-profile, fingerprint is computed by EAS CLI using the selected
@@ -756,7 +948,7 @@ leased until <time>" for each one.`,
                   looked up", which is a different fact from "nothing was found"
   buildMachine    selected auto, local or machine name, including cache hits
   builtOn         here or machine name when a build ran; absent otherwise
-  offloadedTo     only on an app a remote Mac compiled: its
+  offloadedTo     only on an app a remote machine compiled: its
                   remote.machines entry (see \`guide settings\`). cacheHit is
                   false for it. The Android payload carries it too
   offloadFallback only on an app compiled here after the run considered
@@ -909,7 +1101,7 @@ leased until <time>" for each one.`,
                   sets its own CMake compiler launcher, or a Gradle run whose
                   native work was all up to date. None of the three is an
                   error, and this field is separate from cacheHit. On an
-                  offloaded APK it is the remote Mac's ccache
+                  offloaded APK it is the remote machine's ccache
   logs            the workspace log directory
   agentDevice     { stateDir }: absolute workspace agent-device state path
   durationMs      wall time for the whole run
@@ -1010,21 +1202,39 @@ leased until <time>" for each one.`,
                   freedMb, and is empty while under budget
   deviceHosts     one { machine, state, dnsName?, deviceId?, requestedAt?, expiresAt?,
                   host? } per remote.machines entry. state is "approved",
-                  "pending", "not-asked", "revoked", "lapsed", "node-changed", "not-on-tailnet",
-                  "tailscale-off", "unreachable", "invalid",
-                  "credentials-unavailable" or "busy". Tokens stay private.
-                  Only --fix asks for access or forgets removed names.
-                  A remote Mac approved for device hosting does not imply
+                  "pending", "not-asked", "revoked", "lapsed", "key-changed", "outdated",
+                  "not-on-tailnet", "tailscale-off", "unreachable", "invalid",
+                  "credentials-unavailable" or "busy". Setup tickets stay private.
+                  Only --fix asks for access or forgets removed names. A
+                  peer that Tailscale reports as running an OS other than
+                  macOS is never asked or contacted and reports
+                  "not-asked" with no finding, even with a saved approval,
+                  since it can never host.
+                  A remote machine approved for device hosting does not imply
                   build approval; see \`guide settings\`.
                   host is { name, screenRecording, accessibility }, present
                   only for approved machines whose worker reports it.
-                  expiresAt is when a pending request lapses; "lapsed" is
-                  a pending request whose expiry passed. --fix asks again.
+                  expiresAt is when a pending request's setup ticket
+                  expires, absent for a Stim Desktop ticket; "lapsed" is a
+                  pending request whose expiry passed. --fix asks again.
+                  "key-changed" means the worker did not prove the
+                  stim-server key pinned at approval. "outdated" means its
+                  stim-server speaks protocol 1; the finding names the
+                  stim-server service update command to run there.
+  toolchain       { entries, projectNode } on macOS, else null. entries is one { name, value,
+                  source, from? } for node, ANDROID_HOME, JAVA_HOME, stim,
+                  brew and adb: source "environment" when this process's
+                  environment provides it, "discovered" when stim-server's
+                  toolchain discovery would find it (from says where), or
+                  "missing". projectNode is { pin, spec, bin, version } when
+                  .nvmrc, .node-version, .tool-versions or package.json volta
+                  pins Node (bin and version are null when no install
+                  satisfies the pin), else null
   remoteMachines  one { machine, state, 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), "node-changed",
+                  before approval), "key-changed", "outdated",
                   "not-on-tailnet", "tailscale-off", "unreachable" or
                   "invalid". host has the same shape and presence rule as in
                   deviceHosts, as do expiresAt (a pending request's lapse
@@ -1033,13 +1243,15 @@ leased until <time>" for each one.`,
                   simulator unless --platform android, Android emulator when
                   --platform android or the app has android/ or uses Expo,
                   plus macOS SwiftPM when Package.swift exists and no platform
-                  is selected on a Mac), and reasons, each reason it would not,
+                  is selected on a Mac; a platform the machine cannot build at
+                  all, such as iOS on Linux, is left out while it can build
+                  another), and reasons, each reason it would not,
                   prefixed "iOS: ", "Android: " or "macOS: " when only one platform
                   has it, with a finding
                   per reason (code build-machine-<reason>: unreachable,
                   checkout, stim-build, arch, xcode, simulator-sdk, macos-sdk,
                   cocoapods, bundler, runtime, jdk, android-sdk, ndk,
-                  build-tools, compile-sdk, disk or busy). problems lists the same
+                  build-tools, compile-sdk, disk, busy or platform). problems lists the same
                   reasons as { code, reason } with that code. capacity
                   is the machine's offer: { running, max, diskFreeBytes,
                   minDiskFreeBytes, cpus?, loadPerCore?, builds?, maxBuilds?,
@@ -1050,7 +1262,7 @@ leased until <time>" for each one.`,
                   memory-culprit is a costs-time finding naming a process
                   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 Macs > Add
+                  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
 
 ON FAILURE
   \`start\`, \`ios\`, \`android\` and \`web\` all print the error contract instead,
@@ -1067,8 +1279,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 SIGINT, a physical-device
-  lease, Ctrl-C with no build tool running) exits 130 with no payload.
+  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.
 
   \`stop --json\` prints { root, ok, supervisor, collectors, metro, device,
   port, metroTunnel, releasedLeases, macos? }. macos is { status: stopped | failed,
@@ -1267,7 +1479,9 @@ RULES
                   deviceRecord,
                   workspaceOutputs, recording, workspaceDirectory, project,
                   buildLock, buildSlot, deviceLease, easSession, worktree,
-                  cache.
+                  cache, gradleVersion, tempLeftover (one "done" labelled
+                  with the TMPDIR it cleared, plus a "kept" or "failed" per
+                  entry gc checked again or could not delete).
                   label is a device, path or cache name; id is the UDID,
                   AVD name or path behind it, or null. Under --cache
                   parked, a "done" parkedDevice was erased and stays
@@ -1316,7 +1530,7 @@ RULES
                               whole workspace directory
     linkedWorktrees         { path, idleDays, mergedInto, pullRequest,
                               pullRequestUnknown, willRemove, reason,
-                              detail, eligibleAt }  mergedInto is the
+                              detail, eligibleAt, buildState }  mergedInto is the
                               default branch HEAD is merged into
                               ("origin/main"), or null. pullRequest is the
                               branch's pull request { number, state:
@@ -1327,8 +1541,33 @@ RULES
                               origin/main", "PR #12 closed", "idle 9d") or
                               kept. eligibleAt is the ISO time a
                               recent-activity worktree becomes removable,
-                              else null. Without --worktrees, the source
-                              checkout and roots outside git are left out
+                              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
+                              project root, or apps/* and packages/* for
+                              build directories) and a root .pnpm-store,
+                              paths relative to the worktree, largest
+                              first; du counts APFS clones in full. A bytes
+                              is null when du could not measure it within
+                              10 seconds; sizes are cached for up to an
+                              hour while no entry of the directory was
+                              added or removed. null
+                              for a root outside git. Without --worktrees,
+                              the source checkout and roots outside git
+                              are left out
+    unlistedWorktreeDirectories
+                            { path, repository, bytes, remedy }  a
+                              directory directly under a repository's
+                              .worktrees/ that \`git worktree list\` does
+                              not show and that has no .git, or a .git file
+                              whose gitdir is gone; a worktree of another
+                              repository is left out. bytes is null when du
+                              fails. Report-only, never deleted: it may
+                              hold work. remedy is the rm -rf command to
+                              run after checking it
     parkedSimulators        { udid, name, model, runtime, parkedAt, app,
                               bytes, listed }  app is the bundle id recorded
                               at park, else null; with --older-than, only
@@ -1351,6 +1590,20 @@ RULES
                               for AVD data with no registration)
     staleDevices            { kind, id, name, project, slot, idleDays,
                               bytes }  only with --older-than
+    finishedDevices         { kind, id, name, project, slot, bytes, reason }
+                              owned devices of a workspace whose linked
+                              worktree gc keeps although its branch is
+                              merged or its pull request ended; --delete
+                              deletes them unless the workspace is in use,
+                              leased, driven, locked, pinned by
+                              maintenance.keep or used within
+                              gc.worktreeGraceMinutes
+    ownedDeviceDisk         { kind, count, bytes, unmeasured }  disk of the
+                              owned simulators and emulators of registered
+                              workspaces, per platform; unmeasured counts the
+                              ones whose size could not be read; parked
+                              devices are under parkedSimulators and
+                              parkedEmulators
     staleDeviceRecords      { kind, id, project, slot }  --delete clears
                               the record only
     staleLedgerEntries      { kind: "ios" | "android" | "web", id }
@@ -1412,6 +1665,51 @@ RULES
                               null with any --cache scope
     swiftpmCache            <SwiftpmCacheUsage|null> report-only, never deleted;
                               null with any --cache scope
+    gradleVersions          { home, olderThanDays, blocked, gradleRunning,
+                              gradleRunningPids, versions: [{ version, dirs,
+                              bytes, lastModifiedAt, willDelete, reason,
+                              detail }], leftovers } | null; only with
+                              --cache gradle-versions. blocked is null or
+                              { reason, detail } with machine-global,
+                              no-registry, unsafe-layout, listing-failed,
+                              unreadable-project, gradle-running or
+                              processes-unknown; gradleRunning is the
+                              gradle-running detail or null and
+                              gradleRunningPids the pids behind it; a
+                              version's reason is null, one of those,
+                              not-a-directory, walk-failed, too-many-entries
+                              or recently-modified. leftovers lists
+                              .stim-delete-* directories --delete finishes
+                              removing
+    machineCaches           { measuredAt, complete, notices, gradle, simRuntimes,
+                              deviceSupport, runnerBuilds } | null
+                              report-only, never deleted; null with any
+                              --cache scope. gradle: { home, unusedVersions:
+                              [{ version, bytes, dirs, remedy }],
+                              usedVersions: [{ version, projects }],
+                              unreadableProjects, modules }. simRuntimes:
+                              { checked, runtimes: [{ identifier,
+                              runtimeIdentifier, version, build, bytes,
+                              deletable, lastUsedAt, devices, remedy }] }.
+                              deviceSupport: { entries: [{ dir, bytes }],
+                              remedy }. runnerBuilds: { agentDeviceVersion,
+                              xcodeBuildVersion, groups: [{ packageVersion,
+                              xcodeBuildVersion, current, entries, inUse,
+                              bytes, oldestUseAt }], remedy }. Sizes and
+                              versions come from
+                              $STIM_HOME/machine-cache-usage.json, at most
+                              10 minutes old
+    tempLeftovers           { root, groups: [{ kind, count, bytes,
+                              deleteCount, deleteBytes, kept: [{ reason,
+                              count }], remedy }] } | null  recognized
+                              entries directly in TMPDIR (root, resolved).
+                              kind is stim (stim-claim-*, stim-host-*,
+                              stim-fakehome-*, stim-hosted-macos-*,
+                              stim-server-*, stim-ws-* directories), xctrace
+                              (instruments*.ktrace) or jest (Jest's
+                              jest_<uid in base 36> cache, never deleted). deleteCount
+                              is what --delete removes. null with STIM_HOME
+                              set or any --cache scope
     caches                  { name, dir, source, bytes, note, willEmpty,
                               emptySkipped, scopedEmpty }  alive, not
                               garbage; willEmpty marks the ones --delete
@@ -1454,7 +1752,8 @@ RULES
                             stim-server
     linkedWorktrees         not-a-worktree | bare-repository |
                             source-checkout-unknown | source-checkout |
-                            locked | in-use | status-unreadable | dirty |
+                            locked | nested-worktree | in-use |
+                            status-unreadable | dirty |
                             unpushed-unchecked | unpushed | submodules |
                             not-merged | merge-unknown | last-use-unknown |
                             recently-used | activity-unknown |
@@ -1798,7 +2097,7 @@ RULES
                    device: its boot, adoption cleanup, or a physical
                    device's lease and connection check. A boot that
                    finishes during the build adds no device time. For a
-                   device hosted on another Mac, device covers reserving
+                   device hosted on another machine, device covers reserving
                    and preparing it there, install covers delivering the
                    app, and launch starts when the host launches it. An
                    --eas-profile run has no cache lookup, so its outcome
@@ -1940,7 +2239,7 @@ RULES
   lookup, and create no lastBuild record or failed-run stats.
   buildMachine selected auto, local or configured machine entry; always on new build records
   builtOn      here or machine name; absent when no build ran (cache/refusal)
-  offloadedTo  only on a run a remote Mac compiled: its name
+  offloadedTo  only on a run a remote machine compiled: its name
   offloadFallback
                only on a run that considered offloading and built here: one
                reason per machine when none took the build, or why the
@@ -2180,7 +2479,7 @@ RULES
                 baseline. rekeyedBy is empty.
   placement     with ios.remote or android.remote set to auto or a Mac,
                 where the plan assumes the device runs: "on <machine>" or
-                "this Mac; auto may use <machines>"; absent otherwise
+                "this machine; auto may use <machines>"; absent otherwise
   refusal       { code, message, remedy } when the run would refuse:
                 STIM_PREBUILD_FAILED for a tracked native dir the fingerprint
                 leaves out, STIM_EAS_BUILD_MISSING for an EAS miss
@@ -2212,7 +2511,7 @@ RULES
   A bucket carries runs, failed, hits, misses, coldRuns, coldRunMs, hitRuns,
   hitRunMs, timeSavedMs, firstRunAt and lastRunAt, plus lastColdBuildMs and
   lastPodsMs once the project has compiled or installed pods, and
-  offloadedRuns, offloadedRunMs and lastOffloadHost once a remote Mac
+  offloadedRuns, offloadedRunMs and lastOffloadHost once a remote machine
   compiled one. An offloaded run is a miss but not a cold run, so the cold
   average, time saved and build estimates stay local. Milliseconds are
   integers.
@@ -2332,10 +2631,10 @@ BUILD PLACEMENT (\`offload\`)
   decision, reason, machine?, buildMs?, slotWaitMs?, deviceSlotWaitMs?, localEstimateMs?, failed? }.
   slotWaitMs and deviceSlotWaitMs are whole milliseconds waiting for build
   and owned-device slots respectively, present only when positive.
-  decision is "here", "offloaded", or "fell-back" (it tried a remote Mac
+  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 Mac has room) or "remote.buildMode is off" (which prints no line),
+  while this machine has room) or "remote.buildMode is off" (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
   total (offer, sync, build and fetch); localEstimateMs is this project's
@@ -2344,7 +2643,7 @@ BUILD PLACEMENT (\`offload\`)
   placements lists them newest first: the last 100 from the last 7 days.
   Per machine, \`total\` keeps { offloaded, offloadedMs, savedMs, fallbacks,
   lastOffloadAt?, lastFallbackAt? } for good and \`today\` counts { offloaded,
-  offloadedMs, savedMs, fallbacks } from the placements on this Mac's local
+  offloadedMs, savedMs, fallbacks } from the placements on this machine's local
   calendar day. savedMs sums localEstimateMs minus buildMs over offloaded
   builds that had an estimate, so it is an ESTIMATE and is negative when the
   machine was slower. \`offload.today\` counts the day's placements by
@@ -2382,7 +2681,7 @@ comes from \`start --remote\`, eas/proxy in \`ios.remote\`, or \`android.remote\
 HOSTED IOS METRO
   ios --remote <machine> keeps Metro local and needs no start --remote.
   The supervisor watches private gateway requests in workspace state, binds
-  only this Mac's Tailscale address and accepts only the pinned hosting peer
+  only this machine's Tailscale address and accepts only the pinned hosting peer
   with a per-session secret. The host's bridge is loopback-only. Port and secret
   stay in 0600 workspace state and never appear in status, JSON or logs.
   metro.tunnel and metro.publicUrl are ignored. Supervisor restart recreates
@@ -2522,6 +2821,12 @@ WHAT THE SUPERVISOR IS
                  launches stay UNVERIFIED: read \`stim logs --source metro\`
                  for the bundle lines.
 
+  expo-child and command-child put the Node the app pins (.nvmrc,
+  .node-version, .tool-versions nodejs, or package.json volta.node) first
+  on PATH when an nvm, fnm, Volta, asdf or mise install satisfies the pin
+  and the node already on PATH does not; the metro log then records a
+  project_node event naming it. bare-inproc runs on the supervisor's Node.
+
   In expo-child mode, remote intent plus metro.tunnel "expo" makes \`start\` pass
   \`--tunnel\` and EXPO_UNSTABLE_TUNNEL_V2=1 (the legacy ws-tunnel path is
   locked to port 8081, which every reserved port but the first collides with)
@@ -2829,6 +3134,18 @@ FLAGS
                    mode only, on stderr. With --errors, an Expo error record
                    also carries context (see THE RECORD).
 
+Local follow uses filesystem change hints with a ten-second repair scan for
+missed events or a replaced directory. Until a directory watch is available,
+it retries and scans every 500 ms, with one recovery scan 500 ms after attachment.
+On Windows a moved log directory can require the ten-second repair scan.
+Expo context settling uses a timer only
+while an error is pending; otherwise idle files are not repeatedly scanned.
+Local agent actions also follow their state and claim directories, coalescing file
+changes instead of re-reading every 500 ms while idle.
+While following, hosted targets join and leave from local state notifications.
+Missed notifications are reconciled about every 10 seconds. Active hosts still
+serve bounded log queries.
+
 --ERRORS, PRECISELY
   Level error or fatal, from metro, client and build, plus device records with
   event native_crash (app/device/time-correlated OS reports or fatal app console output)
@@ -2916,7 +3233,7 @@ FLAGS
   responses, do not cut the stack short. Human output joins the lines to the
   message. --json leaves msg as captured and adds them to the error record as
   a context array of strings; each record is still one line. --follow holds an
-  Expo error until a poll, about every 500 ms, adds no more of its lines, so
+  Expo error until a 500 ms settle check adds no more of its lines, so
   it can print up to about a second after Expo does. Non-follow human output
   also shows bare React Native symbolication as separate context, because
   Metro does not provide an error correlation identifier. Context never
@@ -2965,16 +3282,16 @@ failures before a later launch marker are hidden. Machine passes are reported in
 status and maintenance/maintenance.ndjson; this command reads workspace logs.
 
 REMOTE REQUEST RECORDS
-A request to another Mac that fails is a warn record with src: build in the
+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,
-code } (could not connect or say hello, e.g. "no reply in time" when the Mac
+code } (could not connect or say hello, e.g. "no reply in time" when the machine
 did not answer hello) and remote_request_failed { method, ms, code, msg }.
 Timings of requests that succeed are debug records (below).
 stim-server writes to its service log (~/Library/Logs/Stim/<label>.log), with
 no tokens or tickets: "request failed method=<m> client=<device id> run=<runId>
 ms=<n> error=<code>" for an error reply (once a minute per client, method and
 code) and "host_connect ... error=<reason_with_underscores>" when its connection to a hosting
-Mac fails. With debug.logs on or STIM_DEBUG=1 for the server it logs every
+machine fails. With debug.logs on or STIM_DEBUG=1 for the server it logs every
 request instead: "debug request method=<m> client=<id> run=<runId> ms=<n>
 slow=true error=<code> whois=<ms> probe=<ms>" (slow means 1000 ms or more;
 whois and probe are the hello's Tailscale identity lookup and its wait for
@@ -2991,14 +3308,14 @@ stim logs does not show them. Read them with jq:
   jq -c 'select(.event=="exec" and .ms>1000)' ~/.stim/logs/debug/cli.ndjson
 Events: run_start, run_end { exit, ms }, exec { program, ms, ok, exit? }, and
 remote_connect and remote_request { ms, ok, code? } for requests to another
-Mac. They carry no arguments, tokens or tickets.
+machine. They carry no arguments, tokens or tickets.
 
 Placement records use src: placement and sit in the run's build log
 (build-*.ndjson), so a new run replaces the previous run's. A run writes one
-record per decision it makes (a build that compiles and has a remote Mac to
+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,
 device_placement or placement_fallback. A cache hit, a project with no paired
-remote Mac and a named --remote target write none:
+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
@@ -3006,7 +3323,7 @@ from flag, env, setting or default (remote.build and remote.buildMode for a
 build, ios.remote or android.remote, plus remote.easFallback when it is on, for
 a device), candidates [{ machine, code,
 msg, detail? }], choice { machine, code, msg } with machine local when the run
-stays on this Mac, and fallback { code, msg, machine? } when a remote Mac that
+stays on this machine, and fallback { code, msg, machine? } when a remote machine that
 was meant to take the run did not (level warn). The msg is the same text the
 placement: and build: phase lines print.
 Candidate codes: accepted, unreachable, busy, disk, load, version-mismatch
@@ -3204,6 +3521,13 @@ WHAT WRITES WHAT
 };
 //#endregion
 //#region src/guide/errors.ts
+const PROVISION_CONTEXT = `\`stim device provision ios [udid]\` is the one Stim command that changes an Apple
+Developer account: it registers the phone with the project's team and creates
+or refreshes the iOS App Development profile (and, when the keychain holds
+none, an Apple Development certificate) by running xcodebuild with
+-allowProvisioningUpdates -allowProvisioningDeviceRegistration. No build, and
+no \`ios --device\` run, ever does this. Agents run it only when the user
+explicitly asks for this step.`;
 const errors = {
 	summary: "Every refusal Stim can print: an index of codes, and one section for each",
 	sectionHint: "<CODE>",
@@ -3215,10 +3539,11 @@ Branch on the code, never on the message.`,
 		STIM_HOSTING_REFUSED: {
 			summary: "a hosting Mac refused or could not confirm its native session; no fallback after reservation",
 			body: () => `STIM_HOSTING_REFUSED
-  The message names the hosting Mac and its reason: unreachable or changed
-  tailnet node, no installed simulator or emulator choice, no capacity, elevated or unknown
+  The message names the hosting Mac and its reason: unreachable, a changed
+  server key, a stim-server too old to speak protocol 2 (stim doctor names
+  the update command), no installed simulator or emulator choice, no capacity, elevated or unknown
   memory pressure, or an unresolved reservation or delivery. Stim boots nothing
-  locally and never tries another Mac after choosing a named host or creating a
+  locally and never tries another machine after choosing a named host or creating a
   hosted session. Auto skips declined offers before building, then uses the
   local queue if none admits. A reserve refusal after an accepted offer fails
   with this code and asks to retry; it does not re-place the built architecture.
@@ -3236,7 +3561,7 @@ Branch on the code, never on the message.`,
   on the host to enable handoff and native logs (hello features hosted-ios-data
   for iOS and hosted-android-data for Android).
   A name outside remote.machines is STIM_BAD_ARG. Missing or pending hosting
-  approval keeps the doctor --fix and stim-server devices grant remedies.`
+  approval keeps the doctor --fix and stim-server setup remedies.`
 		},
 		STIM_EAS_BUILD_MISSING: {
 			summary: "no completed EAS development build matches; build only with session authorization",
@@ -3340,7 +3665,7 @@ Branch on the code, never on the message.`,
   the source checkout, then warm again.`
 		},
 		STIM_BUILD_FAILED: {
-			summary: "xcodebuild or gradle failed; the Android missing-SDK and APK refusals; a damaged compilation-cache object",
+			summary: "xcodebuild or gradle failed; the Android missing-SDK and APK refusals",
 			body: () => `STIM_BUILD_FAILED
   xcodebuild or gradle failed. The EXTRACTED diagnostics are printed (capped),
   not the transcript. Read the log path on the next line for the rest.
@@ -3367,17 +3692,40 @@ Branch on the code, never on the message.`,
   reports UP-TO-DATE and repackages nothing. Stim installs it. Gradle owns task
   freshness and the fingerprint owns cache freshness; Stim does not second-guess
   either from the file's mtime.
-
-"failed to scan dependencies for source ..." on pods you did not touch  (ios)
-  The compilation cache holds a damaged object. Xcode reports it per source
-  file, so it names whichever targets reach the object first -- often pods such
-  as sqlite3, nanopb or libwebp -- and the list changes between runs. The
-  transcript carries the cause:
+  A damaged compilation-cache object stays STIM_BUILD_FAILED when Stim did
+  not give the build its shared cache; STIM_COMPILATION_CACHE_CORRUPT lists
+  the messages and the gc remedy.`
+		},
+		STIM_COMPILATION_CACHE_CORRUPT: {
+			summary: "an iOS build failed on a damaged shared compilation cache; Stim emptied it, rerun the command",
+			body: () => `STIM_COMPILATION_CACHE_CORRUPT  (ios)
+  The build used the shared compilation cache ($STIM_HOME/compilation-cache)
+  and the compiler reported a damaged object in it. A cache write that a full
+  disk or a killed build cut short leaves such an object, and every later build
+  that reaches it fails the same way. Stim matches only the compiler's own
+  corruption errors in the transcript:
+    LLVM ERROR: OnDiskCAS: corrupt internal reference
+    error: CAS operation failed: ...
     error: CAS-based dependency scan failed: not a IncludeTreeRoot node kind
-  A cache write that a full disk or a killed build cut short leaves such an
-  object, and upgrading the CLI does not clear it. Empty that one cache with
-  \`gc --delete --cache "compilation cache"\`, then build again. The next
-  build is a cold one.`
+  Xcode reports them per source file, so the failing targets are whichever
+  reach the object first -- often pods you did not touch -- and they change
+  between runs.
+  Stim empties the whole cache at once, the way
+  \`gc --delete --cache "compilation cache"\` does, and fails the build. It
+  does not retry. RUN THE SAME COMMAND AGAIN: that build starts with an empty
+  cache, so it is a cold one. The emptying is recorded in the maintenance log.
+  Every iOS build that compiles with the cache holds a shared claim on it,
+  <cache>.claims beside the cache directory, while xcodebuild runs. Stim
+  empties the cache only under that set's exclusive claim, here, in gc and in
+  maintenance. When another build holds it or its claim is unresolved, Stim
+  leaves the cache alone, because that build may be using it, and the message
+  says so. Once nothing else is building, run
+  \`gc --delete --cache "compilation cache"\`, then run the command again.
+  A build on a build worker gets the same handling on the worker, which
+  empties its own cache for that client. With --remote-build <machine> the
+  build fails with this code and the worker's message; otherwise it falls
+  back to building here, and the fallback line names this code. Xcode builds
+  run outside Stim take no claim, so a cache they share is not guarded.`
 		},
 		STIM_PATH_TOO_LONG: {
 			summary: "Windows only: the project root leaves no room for the NDK object paths ninja must open",
@@ -3387,12 +3735,17 @@ Branch on the code, never on the message.`,
   after their mangled absolute source path, so each carries the project root
   twice unless CMake shortens it, and CMake only shortens a name that then
   fits the object path limit Stim's Gradle shim sets. The message names the
-  longest known object (measured on the e2e fixture, for the ABI being
-  built) and the longest root it leaves room for. Refused BEFORE Gradle runs
-  -- a cache hit still installs -- because the build would otherwise fail
-  deep inside ninja ("mkdir ... No such file or directory" or "Filename
-  longer than 260 characters"). Map the project to a drive letter (\`subst
-  X: <root>\`, then run Stim from X:\\) or move it under a shorter root.
+  longest known object for the ABI being built and the longest root it
+  leaves room for. A project with react-native-gesture-handler 3, whose
+  shared shadow nodes have the longest known object path, fits a root of at
+  most 24 characters for an x86_64 Debug build and 21 for arm64-v8a; other
+  projects fit 51 and 48. Refused BEFORE Gradle
+  runs -- a cache hit still installs -- because the build would otherwise
+  fail deep inside ninja ("mkdir ... No such file or directory" or
+  "Filename longer than 260 characters"). Move or clone the project under a
+  short real path such as C:\\src\\<name> and run Stim there. A subst drive
+  does not help: Node's realpath and Expo autolinking resolve it back to the
+  long path, and Gradle then sees two roots.
   A custom Gradle buildStagingDirectory can be shorter than the default; this
   preflight does not inspect that configured path and may refuse it too.
   \`doctor --platform android\` reports the same root as a finding for the
@@ -3534,7 +3887,7 @@ Branch on the code, never on the message.`,
   works. See stim guide macos.`
 		},
 		STIM_OFFLOAD_REFUSED: {
-			summary: "the selected remote Mac or automatic build pool cannot build this app",
+			summary: "the selected remote machine or automatic build pool cannot build this app",
 			body: () => `STIM_OFFLOAD_REFUSED
 
 Automatic placement also refuses when local is excluded in remote.buildPoolDisabled
@@ -3544,20 +3897,20 @@ builds are not interrupted and a cache hit needs no compiler.
 
 A named --remote-build selection is strict. The message names the machine
 and why it cannot take or finish the build: not configured or paired, approval
-pending or denied, unreachable or changed pinned identity, incompatible
+pending or denied, unreachable, changed pinned server key, a stim-server
+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 Mac before a named offload.
+refusal. Prebuild and pod install still run on this machine before a named offload.
 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.
 
 Run stim doctor --fix to ask for build access if not paired. Check
-stim settings get remote.machines. A person on the worker finds the id with
-stim-server devices and approves this Mac with stim-server devices grant <id> --build,
-or runs stim-server setup on the worker with its node, ticket and expiry
-(guide settings). Agents never run setup or approve requests.
+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
 --remote-build local to keep the build here.
 `
@@ -3565,12 +3918,14 @@ Rerun with --remote-build auto for normal placement and local fallback, or
 		STIM_WORKTREE_SERVICE: {
 			summary: "worktree remove refuses a folder a stim-server service runs from",
 			body: () => `STIM_WORKTREE_SERVICE
-  A LaunchAgent that \`stim-server service install\` wrote (it carries a
-  StimService marker in ~/Library/LaunchAgents/<label>.plist, default label
-  dev.stim.server) runs a program from inside this worktree. Removing the
-  folder would delete the running server's code. The refusal also covers a
-  service that is installed but stopped, because launchd loads it again at the
-  next login, and a marked plist Stim could not read. \`--force\` does not
+  A service that \`stim-server service install\` wrote runs a program from
+  inside this worktree: on macOS a LaunchAgent with a StimService marker in
+  ~/Library/LaunchAgents/<label>.plist, on Linux a systemd user unit with an
+  [X-Stim] Managed=true section in ~/.config/systemd/user/<label>.service
+  (default label dev.stim.server). Removing the folder would delete the
+  running server's code. The refusal also covers a service that is installed
+  but stopped, because launchd or systemd starts it again, and a marked file
+  Stim could not read. \`--force\` does not
   override it, and gc leaves the worktree in place.
   Reinstall the service from another build (stim-server service install --label
   <label> from a checkout that stays), or remove it with stim-server service
@@ -3671,10 +4026,11 @@ spending a build or a bundle, that the check can succeed.`,
   The built or cached .app has no embedded.mobileprovision, or
   \`openssl smime\` could not decode the one it has. The first means the build
   produced an unsigned app -- almost always a simulator-sliced artifact.
-  Set a team and a Development profile for the target's configuration in
-  Xcode > Signing & Capabilities, then BUILD ONCE FROM XCODE to install the
-  profile. Stim will not do that step: registering a device or minting a
-  profile changes your Apple Developer account, so Stim never passes
+  Set a team for the target's configuration in Xcode > Signing &
+  Capabilities, then run \`stim device provision ios [udid]\` (see
+  STIM_PROVISION_UNCONFIRMED) or BUILD ONCE FROM XCODE to install the profile.
+  No build does that step: registering a device or minting a profile changes
+  your Apple Developer account, so builds never pass
   -allowProvisioningUpdates.`
 		},
 		STIM_PROFILE_MISMATCH: {
@@ -3692,8 +4048,10 @@ spending a build or a bundle, that the check can succeed.`,
       refuses rather than guessing. Local device runs need a development
       profile;
     - it is a development or ad hoc profile whose device list does not name
-      this UDID. Register the UDID at developer.apple.com, regenerate the
-      profile, and build once from Xcode.
+      this UDID. Run \`stim device provision ios <udid>\`, which registers
+      the UDID and refreshes the Development profile after asking, or
+      register it at developer.apple.com, regenerate the profile, and build
+      once from Xcode.
   With --eas-profile, follow the EAS device:create and build commands in the
   refusal instead. Registration, signing changes and cloud builds need session
   authorization. See stim guide lifecycle eas.`
@@ -3727,6 +4085,44 @@ spending a build or a bundle, that the check can succeed.`,
   and confirm exactly one identity matches the name. The cache entry itself is
   never modified -- the failure is on a temporary copy, and the run builds
   fresh.`
+		},
+		STIM_PROVISION_UNCONFIRMED: {
+			summary: "device provision ios listed its account changes and nobody confirmed them; nothing changed",
+			separator: "--- iOS PROVISIONING CODES (`stim device provision ios`, and only there) ---",
+			context: PROVISION_CONTEXT,
+			body: () => `STIM_PROVISION_UNCONFIRMED
+  The command printed what it would change -- the team, the phone, each bundle
+  id whose Development profile it would create or refresh, and whether it uses
+  the Xcode account or an App Store Connect API key -- and nobody confirmed:
+  the terminal prompt was answered with anything but y, or there was no
+  terminal (or --json) and no --yes. Nothing changed. \`--json\` adds the plan.
+  Confirm in a terminal, or pass --yes once the account owner agreed. Agents
+  never add --yes on their own.`
+		},
+		STIM_PROVISION_FAILED: {
+			summary: "device provision ios could not provision: no account or key, team not accessible, or project signing",
+			context: PROVISION_CONTEXT,
+			body: () => `STIM_PROVISION_FAILED
+  Before xcodebuild runs: the app has no Xcode project, xcodebuild cannot
+  report the scheme's build settings, a signed target names no development
+  team or uses manual signing (xcodebuild creates profiles only for automatic
+  signing), the temporary DerivedData cannot be created, or a native app uses
+  Swift packages that Stim has not resolved yet (no workspace-state.json in
+  its package directory): run \`stim ios\` or \`stim ios --device <udid>\` once
+  to resolve them, then provision. Packages resolved for an older
+  Package.resolved fail inside xcodebuild, whose error is quoted. The remedy
+  names the Xcode or app-config change. From xcodebuild: "No Accounts" means Xcode has no Apple
+  ID signed in and no App Store Connect key is set -- sign in under Xcode >
+  Settings > Accounts, or set ios.appStoreConnectKeyPath,
+  ios.appStoreConnectKeyId and ios.appStoreConnectIssuerId (stim guide
+  settings); "No Account for Team" means that account or key cannot reach the
+  project's team; a 401 means Apple rejected the key. Any other xcodebuild
+  error is quoted, with the key path replaced. An interrupt or the 15-minute
+  timeout also ends here. Once xcodebuild has run, the refusal still lists
+  any profile it installed and any new keychain identity (\`--json\`:
+  \`changes\`), because Apple may already have registered the phone; running
+  the command again is safe. A phone that is not paired or has Developer Mode
+  off refuses earlier, with STIM_NO_DEVICE.`
 		},
 		STIM_NO_LAN_ADDRESS: {
 			summary: "the Mac has no non-internal IPv4 interface; a tunnel cannot help a phone",
@@ -4324,7 +4720,8 @@ captured"  (in metro.ndjson, bare RN)
   a changed pin while this workspace's dev server runs or its supervisor
   cannot be verified,
   \`--device\` with an empty
-  serial or UDID, \`--device\` together with \`--remote\`, \`ios --runtime\`
+  serial or UDID, \`--device\` together with \`--remote\` other than
+  \`local\`, \`ios --runtime\`
   on an eas/proxy run (\`--remote\` or ios.remote; that backend picks the
   iOS version), \`ios --device-type\` on the proxy backend or with an
   eas-cli older than 22.2.0 on the eas backend, \`android --system-image\` or
@@ -4392,20 +4789,34 @@ captured"  (in metro.ndjson, bare RN)
   \`workspace removal\` -- both are \`stim worktree remove\`). Let it finish,
   then run the command again. \`start --remote\` reports this same case as
   STIM_WORKTREE_REMOVAL_IN_PROGRESS instead.`
+		},
+		STIM_REPORT_TIMEOUT: {
+			summary: "An in-process report or lifecycle operation exceeded its execution budget",
+			body: () => `STIM_REPORT_TIMEOUT
+
+An API operation exceeded its execution budget: 90 minutes for warmWorktree(),
+60 seconds for doctor(), gc(), collectGarbage(), reload(), plan() and removeWorktree().
+Stim attempts only that operation's cleanup before rejecting, with a 35 second
+cleanup budget. Unfinished cleanup returns STIM_CLAIM_UNAVAILABLE instead.
+Other clients are unaffected. Retry after the machine is less busy, or narrow
+the report with doctor({ platform }) or gc({ cache }). doctor() and gc() remain
+read-only. collectGarbage() can mutate resources; completed actions remain applied.
+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)
   "The ios run was cancelled by \`stim stop\` (pid <n>) before it finished."
-  The run received SIGINT: from \`stim stop\`, which interrupts a build it
-  leaves with nothing to deploy to, or from Ctrl-C. It forwarded the interrupt
+  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
   to the build tool it was running (xcodebuild, Gradle, pod install, expo
   prebuild) and failed through its own cleanup; the next line names the step it
   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 SIGINT exits at once, and so does a run that holds a physical-device
-  lease; those exits print no payload. Run the same command again when you want the
+  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
   app on a device.`
 		},
 		STIM_STOP_BLOCKED: {
@@ -4416,6 +4827,10 @@ captured"  (in metro.ndjson, bare RN)
   - "... did not exit within 60s of SIGINT": the run was interrupted but is
     still running. Wait for it, or end it with the \`kill <pid>\` the remedy
     prints, then run \`stim stop\` again.
+  - "... did not exit within 60s of the stop request": the run is inside a
+    process that embeds Stim, such as stim-server, and runs other work too.
+    Stop does not signal that process. Wait for the run, or cancel it from
+    the client that started it, then run \`stim stop\` again.
   - "... pid <n> is no longer that run; the build tool it started (pid <m>)
     still holds the claim": the run itself died and its build tool keeps the
     claim. Stim signals only a claim owner whose recorded identity it can
@@ -4773,14 +5188,6 @@ not on any remote"  (worktree remove)
   Expo build-cache provider would each use a different store. Set the named
   variable to an absolute path, or unset it to use the default. Metro and the
   cache provider, which cannot refuse, ignore a relative value with a warning.`
-		},
-		STIM_WORKER_FAILED: {
-			summary: "a programmatic API worker exited without returning an operation result",
-			body: () => `STIM_WORKER_FAILED  (programmatic API)
-  The worker process ended without a structured result. StimError.details
-  includes its final stderr output. Inspect that output and call diagnostics()
-  for existing workspace logs, then stop() with a fresh signal to clean up
-  any resources created before the failure. See stim guide api.`
 		},
 		STIM_RUN_FAILED: {
 			summary: "a programmatic operation failed without a more specific Stim code",
@@ -4915,6 +5322,16 @@ with eas or proxy starts it the way \`stim start --remote\` does. A named
 hosting Mac keeps Metro local through a private bridge; see hosted-ios. Step 2 remains useful to warm
 Metro while other work happens.
 
+Each time Stim boots an owned local simulator or emulator, it mutes it: iOS
+simulators to volume zero through Xcode's devicectl, and Android 15 and later
+emulators to media volume zero. A device that is already running keeps its
+volume. 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.
+
 Repeat step 3 whenever a NATIVE input changes. A JS-only edit needs nothing --
 that is what Fast Refresh over the running dev server is for. \`stim reload\` is
 not part of the normal workflow. It is the explicit recovery path when Fast
@@ -5036,9 +5453,10 @@ STOP DURING A BUILD
     lock        waiting for \`stim ios\` (pid 41233, running for 12m04s) in this workspace to finish
   \`stop\` does not wait out a build it leaves with nothing to deploy to: a
   plain \`stop\`, \`stop --slot <name>\` for the slot the build targets, or
-  for the workspace's only device. It sends that run SIGINT, only after
-  proving the run's recorded process identity, and waits up to 60 seconds for
-  it to exit. The run stops its build tool, stores nothing from the
+  for the workspace's only device. It asks that run to stop through the
+  workspace state and, when the run is a CLI process, also sends it SIGINT,
+  only after proving the run's recorded process identity. It waits up to 60
+  seconds for the run to exit. The run stops its build tool, stores nothing from the
   interrupted build, and exits 130 with STIM_CANCELLED. A run that does not
   exit in time, or whose build tool outlived it, is refused with
   STIM_STOP_BLOCKED naming its pid and claim. \`stop --slot <name>\` while the
@@ -5068,11 +5486,20 @@ WAITING FOR A CHANGE
   changes, never two identical ones in a row. In a watch line, a usage
   figure repeats its value in the previous line until it moves by a step: an owner's cpuPercent 5 points, an
   owner's or environment's memoryMb and capacity.committedMb 16 MB. An owner's row
-  changes as a whole, so its residentMb and processes update with it. It reacts to Stim state files,
-  the EAS session ledger, adb device arrivals and departures, and simulator
-  state, and recomputes every 30 seconds as a fallback. A log append updates
-  only the log error count and device activity, no sooner than 15 seconds
-  after the previous refresh. Ctrl+C, SIGTERM or closing its stdout ends it
+  changes as a whole, so its residentMb and processes update with it. A change
+  in only a bookkeeping timestamp prints no line: each pullRequest.checkedAt,
+  maintenance.lastChecks, maintenance.lastPass.startedAt and durationMs, and
+  maintenance.running.startedAt. A line that prints carries their current
+  values. It reacts to Stim state files,
+  the EAS session ledger, git HEAD, index and ref changes in the worktrees'
+  repositories, the exit of a recorded supervisor, Metro, build, browser or
+  macOS app process (checked every 2 seconds), adb device arrivals and
+  departures, and simulator boots, shutdowns, creations and deletions (from
+  CoreSimulator's device set and metadata files, with a simctl check every 30 seconds), and
+  recomputes every 30 seconds as a fallback. A log append updates the log-derived facts
+  within about a second; device activity follows at most every 5 seconds. The
+  first line does not wait for git: worktree git summaries can be null in it,
+  and the next line carries them. Ctrl+C, SIGTERM or closing its stdout ends it
   with exit 0. On Linux, so does the exit of the process that started it
   when its stdout is a pipe. It notices within a few seconds even when
   nothing changes, except a closed stdout pipe on Linux whose starter is
@@ -5121,7 +5548,7 @@ C-family header graphs, Swift package graphs and unresolved external input
 paths or compiler overrides. The miss reason explains the exclusion. --plan
 refuses such a prediction; omit --plan to prepare and build the app.
 
-A compatible approved build Mac can compile a native Xcode app with
+A compatible approved remote Mac can compile a native Xcode app with
 --remote-build auto or --remote-build <name>. Both peers must support
 native-xcode-build. This first worker path requires a verified artifact identity
 and all inputs contained in the repository and visible to git. Ignored or
@@ -5168,8 +5595,34 @@ density/split APK sets and EAS/proxy targets are unsupported. Set
 org.gradle.configureondemand=false; configuration cache remains supported.
 Stim verifies the existing APK signature; it does not sign it.
 
-Stim artifact caching is unavailable because arbitrary Gradle inputs are not fully
-tracked. Build workers require a project-scoped \`android.offloadInputs\` declaration:
+Local APK caching requires project-scoped \`android.artifactInputs\`:
+\`{"complete":true,"ignored":[],"outputs":["build","app/build"],"localFiles":["../signing/release.keystore"],"environment":["SIGNING_PASSWORD"]}\`.
+complete promises a repeatable build from Git-visible source, declared ignored
+files, exact local files and named environment values, with pinned dependencies
+and unmodified pinned toolchains. Declare custom signing, JVM user.home, alternate
+toolchain and external configuration inputs; arbitrary Gradle reads cannot be
+inferred. Local files may be absolute or project-relative; absence is hashed.
+Default debug keystores, JDK release, SDK version metadata, Gradle user properties
+and init scripts also contribute. SDK directory paths alone do not change the
+key; other local.properties contents do. Keys must be plain and unescaped, and
+values must fit on one line; Java Properties escapes in sdk.dir values are supported.
+Unsupported syntax disables artifact caching. The AGP SDK must match ANDROID_HOME.
+Inputs are checked again after compilation; a change prevents publication.
+Cached APK bytes, package, signing certificate and target ABI are verified.
+A configured provider with a files capability shares the completed APK and
+verification receipt. Stim checks the local cache first, verifies downloaded
+bytes, then fills the local cache. Invalid shared entries are cache misses;
+providers without files are skipped. Private input contents are neither logged
+nor transferred. This contract grants no build-worker transfer access.
+Without it, native builds remain uncached and Gradle retains its incremental and
+task caches. optimizations.buildCache=false disables artifact reads and writes.
+--no-build-cache skips reads and shared-build waits, but stores the fresh build.
+Native Android --plan verifies the same key and cached APK without running Gradle;
+unresolved ABI (including legacy unowned emulator assignments), missing declarations,
+hosted placement and CAS setup refuse it.
+
+
+Build workers require a project-scoped \`android.offloadInputs\` declaration:
 \`{"complete":true,"ignored":["app/src/main/assets/generated.json"],"outputs":["build","app/build"]}\`.
 Use \`stim android --remote-build <approved-mac>\` after reviewing this declaration.
 Paths are exact repository-relative paths. complete affirms that Git-visible
@@ -5179,8 +5632,17 @@ homes. External inputs, directory links, submodules and custom local.properties
 refuse; an SDK-only local.properties stays local. Only declared directories
 reported by AGP and previously produced by this worker remain warm, along with
 worker project .gradle/.kotlin state. Undeclared bytes are removed. Gradle owns
-incremental, task-cache and configuration-cache reuse; transfer digests never
-become reusable APK cache keys. Older hosts refuse before source upload.
+incremental, task-cache and configuration-cache reuse. A transferred
+android.artifactInputs declaration also lets the worker reuse verified APKs under
+its own complete inputs: worker toolchain, signing files and environment values,
+not the caller's. The returned fingerprint remains null; transfer digests never
+become reusable APK cache keys. Workers with native-gradle-peer-cache can offer a
+completed APK for declared source and resolved variant, ABI and build options,
+rechecking current private inputs against the saved receipt at offer and fetch.
+A hit skips source upload and compilation even while that worker is busy or
+this machine has room. A miss follows normal placement; older Gradle workers
+still build normally. Off mode, explicit local builds and disabled remote cache
+reads skip peer lookup. Hosts without native-gradle-build refuse before upload.
 
 outputs must list every build directory of this build's projects that the build
 creates: the root build directory and each module's, library modules included.
@@ -5190,7 +5652,7 @@ Included builds (includeBuild, such as a build-logic plugin build) and
 externalNativeBuild staging (.cxx) are not reported by AGP and cannot be
 declared, so a remote build that creates them fails and Stim builds locally.
 
-Native Android \`--plan\` refuses without executing Gradle; \`doctor\` reports native
+Native Android \`--plan\` requires a complete artifact input declaration and does not execute Gradle; \`doctor\` reports native
 prerequisites. \`reload\` refuses because the app has no Metro runtime. Re-run
 \`stim android\` after an edit and use \`stim stop\` for scoped cleanup.`
 		},
@@ -5252,12 +5714,13 @@ A person on the host approves device-host access, separately from build, read
 and control. The setup in hosted-ios also serves Android. android.remote sets
 a workspace default. eas and proxy remain backends. --remote auto or
 android.remote = auto places automatically; see hosted-ios for the shared
-policy. No flag or setting runs on this Mac.
+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, a different recorded
-machine, a running local owned emulator in the slot, and --no-metro-check for
-hosted Metro development apps refuse STIM_BAD_ARG. Run stim stop before switching placement.
+returns STIM_HOSTING_REFUSED without fallback. --device with --remote
+<machine>, a different recorded machine, a running local owned emulator in
+the slot, and --no-metro-check for hosted Metro development apps refuse
+STIM_BAD_ARG. Run stim stop before switching placement.
 Unreadable android.host blocks only its slot; restore its recorded machine and
 session from the host before stopping that slot.
 
@@ -5273,7 +5736,7 @@ bridge; the host reverses the client's Metro port into that bridge on its exact
 ledger-owned serial and sets debug_http_host to localhost:<clientMetroPort>.
 Each run and stim reload android restores the reverse, including after a host
 adb server restart. Reload broadcasts through the local Metro and never runs
-adb against the host serial on this Mac. Release variants skip Metro. Launch
+adb against the host serial on this machine. Release variants skip Metro. Launch
 is true only with client bundle evidence or a live host release process;
 bundling requires a bundle request and unverified has no launch evidence.
 
@@ -5303,7 +5766,7 @@ arrive through local Metro.
 
 AGENT CONTROL
 
-Set hosting.agentDriver to agent-device on the hosting Mac. Both Macs need
+Set hosting.agentDriver to agent-device on the hosting Mac. Both machines need
 agent-device 0.21.22 or later. The host advertises hosted-android-agent and
 starts one loopback daemon per installed Android session. Its policy allows
 only the exact ledger-owned emulator serial and denies device shutdown.
@@ -5344,8 +5807,8 @@ on the owned emulator until Stim deletes it. A daemon exit rotates only that
 session's grant; rerun stim android to refresh its config.
 
 Stim Desktop and the phone app view and control the emulator through this
-Mac's local stim-server relay, with an "on <machine>" label. Turn on Serve to
-phones in Desktop and pair the phone with this Mac, not the hosting Mac.
+machine's local stim-server relay, with an "on <machine>" label. Turn on Serve to
+phones in Desktop and pair the phone with this machine, not the hosting Mac.
 frames.subscribe and control.begin address workspace, platform android and
 slot, including named slots. The host verifies its exact ledger-owned serial,
 AVD identity and ABI before capture or input; clients never use that serial
@@ -5359,9 +5822,9 @@ are unavailable through the scrcpy path.
 
 Reruns send only missing manifest and APK digests from the session-scoped blob
 store. The host verifies reused bytes; each new attempt still installs the APK.
-When an Android build ran on the hosting Mac's pinned node, the host takes only
+When an Android build ran on the hosting Mac's own stim-server, the host takes only
 the single App.apk matching the client's manifest. The build and hosting approvals
-must belong to the same tailnet node. Handoff failure falls back to upload,
+must belong to the same client key. Handoff failure falls back to upload,
 retrying a busy host for at most one minute.
 
 stim logs, including --errors and --json, pulls native logcat records as src: device.
@@ -5392,8 +5855,7 @@ If Stim is not installed globally, replace stim with npx stim.
 
   stim settings set remote.machines '["janics-mac-mini"]'
   stim doctor --fix
-  # A person there approves: stim-server devices grant <id> --device-host
-  # Or runs stim-server setup on the worker with its client node, ticket and expiry.
+  # A person there runs the stim-server setup command doctor printed.
   stim doctor
   stim ios --remote janics-mac-mini --device-type "iPhone 17 Pro" --runtime "iOS 27.0"
   stim status --json
@@ -5401,7 +5863,7 @@ If Stim is not installed globally, replace stim with npx stim.
   stim stop
 
 The same setup serves macos --remote. Approval is separate from build, read
-and phone control. Set ios.remote to the machine name for a default (machine scope for the whole Mac);
+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
@@ -5413,7 +5875,8 @@ members from new automatic placement only; an excluded local member is never a
 fallback. Existing sessions keep their owner and named placement bypasses the pool.
 See stim guide settings for separate build/device membership controls.
 
-Otherwise Stim asks every approved remote.machines host in parallel, with a
+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;
@@ -5422,11 +5885,11 @@ Hosts rank by the build preference (flag > STIM_REMOTE_BUILD > remote.build)
 when it names a machine, then lowest load, most free memory and remote.machines order. Automatic build
 offload resolves later, after the device architecture is known.
 
-When no host admits and this Mac is at its concurrency.maxDevices cap (or runs
+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)
 runs the device on an EAS Simulator exactly as --remote eas would: the build
 stays here, nothing starts an EAS cloud build, stop ends the session, and
-status reports it under remoteDevices. A busy Mac with a free slot never uses
+status reports it under remoteDevices. A busy machine with a free slot never uses
 it. Before choosing it Stim checks, without starting a session, that eas-cli
 has simulator commands (and 22.2.0+ for --device-type), eas
 simulator:availability says this project's account can use it, agent-device
@@ -5434,7 +5897,7 @@ is on PATH, the slot is default, no --runtime, --system-image or
 --device-profile flag is given, no EAS Simulator session of this workspace runs
 another platform or model, and a Debug run's Metro is reachable (not
 metro.tunnel off; on an Expo tunnel, run stim start --remote first). A recorded
-EAS session is not sticky: once this Mac has room, auto runs here and the
+EAS session is not sticky: once this machine has room, auto runs here and the
 session bills until stim stop. If any check fails, or the
 setting is off, auto runs here and may wait in the existing FIFO device
 slot queue; --no-wait and --wait 0 refuse with STIM_AT_CAPACITY. The placement
@@ -5449,7 +5912,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 auto. eas/proxy and macOS placement are unchanged.
+cannot combine with --remote auto, and a --device run ignores ios.remote and
+android.remote. eas/proxy and macOS placement are unchanged.
 --simulator-app is honoured locally with auto and ignored with a note on a host.
 Placement measures budgets without reclaiming; only a new local run reclaims.
 Android --remote <machine> uses an owned emulator on that Mac; see hosted-android.
@@ -5459,7 +5923,7 @@ here or elsewhere. --device cannot use a hosting Mac, and --simulator-app
 refuses. The host boots headless and ignores this Mac's iosSimulatorApp setting.
 --slot, --device-type and --runtime select the hosted simulator; --scheme,
 --configuration and --eas-profile select the app as usual. The build targets
-the offered simulator architecture, not this Mac's. --remote-build remains
+the offered simulator architecture, not this machine's. --remote-build remains
 independent and selects a compatible build worker for a Debug cache miss.
 
 The host's own owned devices count toward concurrency.maxDevices.
@@ -5482,7 +5946,7 @@ sessions.
 
 Stim builds or fetches before reserving, records the session immediately, then
 uploads the app on every run. React Native and Expo Debug keep Metro here; the supervisor owns a
-private gateway bound to this Mac's Tailscale address, pinned to the host peer
+private gateway bound to this machine's Tailscale address, pinned to the host peer
 and protected by a per-session secret. The host exposes only a loopback bridge.
 No start --remote is needed; metro.tunnel and metro.publicUrl are ignored.
 Debug requires a running supervisor with private gateway support before reserving
@@ -5494,7 +5958,7 @@ apps use process mode in every configuration and require no Metro; see native-io
 
 A rerun on the same named Mac reattaches and delivers a new app attempt. A
 stopped or missing session is replaced; an unreachable or unknown owner refuses
-replacement. Switching between this Mac and a hosting Mac, or to a different
+replacement. Switching between this machine and a hosting Mac, or to a different
 hosting Mac, refuses for that slot: run stim stop first.
 Status adds ios.host { machine, session, selected, device: { name, runtime },
 agent, state } per slot. A shutdown local simulator is replaced in status; a
@@ -5562,7 +6026,8 @@ tail before parking or deletion, including on revocation or server close; stop c
 back afterwards. If the final collection drops a backlog interval and eventually
 succeeds, a device warning record names that interval. A damaged collection checkpoint is ignored and
 rebuilt; it never blocks reading collected records. The client waits up to
-180 seconds for stop. The final collection and worker termination paths fit within
+280 seconds for stop. The final collection, parking, the stop that follows a failed
+park and worker termination paths fit within
 that wait; an in-flight handoff copy and closing Metro or view transports are
 outside those worker bounds.
 Collected records remain in the session home after parking or deletion;
@@ -5574,7 +6039,7 @@ host gets an update note, uses uploads and shows logs already copied here.
 
 AGENT CONTROL
 
-On the hosting Mac, set hosting.agentDriver to agent-device. Both Macs need
+On the hosting Mac, set hosting.agentDriver to agent-device. Both machines need
 agent-device 0.21.20 or later (the policy and remote-config contract). The host
 starts one loopback daemon per installed iOS session under a child-aware
 ownership claim. Its daemon policy pins exactly that simulator UDID and denies
@@ -5631,8 +6096,8 @@ daemon startup or grant issuance on client support. The client checks the host's
 hosted-ios-agent feature before using a grant.
 
 Stim Desktop and the phone app view and control the simulator through this
-Mac's stim-server relay, with an "on <machine>" label. Turn on Serve to phones
-in Desktop; pair the phone with this Mac, not the hosting Mac. frames.subscribe
+machine's stim-server relay, with an "on <machine>" label. Turn on Serve to phones
+in Desktop; pair the phone with this machine, not the hosting Mac. frames.subscribe
 and control.begin address workspace, platform ios and slot, including named
 slots. The relay shares one authenticated host connection with hosted macOS
 viewers. Stopped sessions show a rerun remedy; unavailable hosts report why
@@ -6202,8 +6667,8 @@ PREDICTING THE NEXT BUILD (--plan)
   architecture or ABI from that Mac's device offer, the question a run asks
   before it reserves anything. With auto it repeats the placement decision a
   run would make now and reports where in the payload's placement field, for
-  example "this Mac; auto may use janics-mac-mini". When the plan stays on
-  this Mac and a listed Mac would build for another architecture, placement
+  example "this machine; auto may use janics-mac-mini". When the plan stays on
+  this machine and a listed Mac would build for another architecture, placement
   says so, since that Mac's key differs. The plan only predicts the key: a
   run reads the architecture of the device it actually gets. A Mac that does
   not answer, ios.remote or android.remote set to eas or proxy, or auto that
@@ -6399,7 +6864,8 @@ then compiles through the cache the selection leaves -- ccache, or none when
 compilerCache is none. It never refuses. See
 https://stim.appandflow.com/docs/android-cas for setup, evidence, and limits.
 Compiler/PCH modes have separate generated directories under each module's
-.cxx/stim-<profile> (or custom staging root). Switching modes in Stim selects
+.cxx/stim-<profile> (.cxx/<first 4 profile characters> on Windows, or custom
+staging root). Switching modes in Stim selects
 the matching directory; direct Gradle builds keep their own configuration.
 Generated CAS directories still depend on Stim's environment and adapter paths.
 
@@ -6431,8 +6897,8 @@ THE BUILD CACHE HAS THREE LEVELS
      @stim-cli/cache contract (see \`guide settings\`). Consulted only when
      level one misses, and its hit is stored into level one before install.
      The same contract serves the Metro transform cache.
-  3. On an EXPO project only, the provider the project ALREADY configured for
-     Expo (\`expo.buildCacheProvider\` -- "eas", or a module of its own).
+  3. On an EXPO project only, EAS when the project configures it through
+     Expo (\`expo.buildCacheProvider\` -- "eas").
      Consulted only when levels one and two miss, bounded so a slow or expired
      remote cannot stall the loop, and a hit is copied into level one on the
      way past so the next workspace on this machine gets it for free. After a
@@ -6441,6 +6907,14 @@ THE BUILD CACHE HAS THREE LEVELS
      tier because its run-options contract cannot distinguish ABIs; levels one
      and two remain ABI-keyed and active.
 
+  The "eas" tier needs eas-build-cache-provider in the app and an installed
+  eas-cli in the app or on PATH. Stim runs its fixed EAS CLI commands without
+  loading the provider SDK into the caller. Fingerprint generation uploads
+  fingerprint metadata to EAS. Fingerprint and transfer commands share one deadline per phase; timeout or
+  cancellation stops that phase's CLI process before returning.
+  Stim never installs eas-cli during cache lookup. A custom Windows batch
+  launcher needs a project eas-cli installation so Stim can stop Node directly.
+
   Stim never configures a provider and never suggests changing one: a
   project without one is a perfectly ordinary local-only project (doctor does
   not ask for one either -- a provider only serves builds run OUTSIDE Stim).
@@ -6935,6 +7409,8 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   install requires an exclusive claim. It releases shared before waiting for
   exclusive, then checks the checkout again before fetching or writing. Every
   copy holds shared, so no copy reads a node_modules a refresh is rewriting.
+  Each copy also holds an exclusive claim on its target, so concurrent warms
+  into the same linked worktree wait instead of racing destination checks.
   The lock is keyed on the repository root, so
   two apps of one monorepo share it. It is the same ownership claim the build
   locks take: the holder's process IDENTITY decides, so a holder that dies frees
@@ -6964,9 +7440,10 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   paths eligible under the source checkout's Git ignore rules, including .env
   and local configuration. The source's nonempty
   .worktreeexclude replaces its resolved worktree.exclude setting. Nested
-  registered worktrees, .DS_Store, .DerivedData, .idea, .jj, and
-  android/build/generated/autolinking caches are excluded, including inside
-  newly copied directories. Gradle regenerates autolinking
+  registered worktrees, .DS_Store, .DerivedData, .idea, .jj, a project-local
+  .pnpm-store, and android/build/generated/autolinking caches are excluded,
+  including inside newly copied directories; pnpm refills its store from the
+  network or its global store. Gradle regenerates autolinking
   for the destination checkout on its next build. 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.
@@ -7015,8 +7492,9 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   filled in. Warm does not copy tracked changes, switch branches, or build,
   and it installs dependencies only under \`--refresh\`, in the source checkout. stdout stays empty; stderr reports copied, kept,
   and failed entry counts. A copy failure exits 1 and reports incomplete;
-  files copied before a failure remain. Inspect the named failed entry
-  before retrying: a partially copied directory will be kept on the retry.
+  completed entries remain. After its child drains, warm removes its own
+  failed partial entry so a retry can copy it again. Unverifiable child cleanup
+  leaves that entry and its ownership claims in place with recovery instructions.
   A completed copy is not proof that dependencies match this branch. Follow
   any lockfile remedies before building, and install missing dependencies
   with the project's package manager when the source has none to copy.
@@ -7105,7 +7583,8 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
 			body: () => `  \`android --device [serial]\` installs and launches on a physical device
   connected to this machine instead of this workspace's owned emulator. With
   no serial it takes the first device it can lease (\`guide lifecycle lease\`).
-  It cannot be combined with --remote.
+  It ignores android.remote and cannot be combined with --remote other than
+  --remote local.
 
   A \`--device\` run LEASES the device from just after the build until it
   exits, so a second workspace cannot install over it mid-run
@@ -7121,7 +7600,8 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   \`android --device\` selects a connected phone: with no UDID it takes the
   first device it can lease (\`guide lifecycle lease\`), and an iPhone
   that is unpaired or has Developer Mode off is refused with the fix. It
-  cannot be combined with --remote, and it never creates, boots, or deletes
+  ignores ios.remote, cannot be combined with --remote other than --remote
+  local, and never creates, boots, or deletes
   hardware -- there is no capacity check, no simulator creation, no boot wait,
   and no owned-device registry entry. Like
   \`android --device\`, it leases the phone for the run
@@ -7183,6 +7663,33 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   a CACHED app falls back to a full build; on a freshly built one it exits on
   its own code, because building again would produce the same app.
 
+  PROVISIONING A NEW PHONE is a separate, explicit step, never part of a
+  build: \`stim device provision ios [udid]\` finds the Xcode project the way
+  \`ios\` does (ios/ for React Native and Expo, the app's own .xcodeproj or
+  .xcworkspace for a native app), reads every target of the scheme that is
+  signed with a profile, on any platform (\`--scheme\`, \`--configuration\`,
+  or ios.scheme / ios.configuration), prints the team, the phone and each
+  bundle id whose Development profile it would create or refresh, and asks
+  [y/N]; Ctrl+C or end of input is no, and \`--yes\` replaces the prompt
+  without a terminal. It then runs xcodebuild -allowProvisioningUpdates
+  -allowProvisioningDeviceRegistration for that phone in a throwaway
+  DerivedData and stops it at the first build task, which xcodebuild starts
+  only once planning has resolved signing, before compilation. A native app
+  with Swift packages uses the packages \`ios\` already resolved, with
+  automatic package resolution off, and refuses until \`stim ios\` has
+  resolved them. That stop and a Ctrl+C send xcodebuild
+  SIGINT, then SIGTERM after 10s and SIGKILL 5s later; a SIGTERM sent to Stim,
+  and the 15-minute timeout, send SIGTERM, then SIGKILL after 5s. A second
+  signal kills xcodebuild before Stim exits. The DerivedData is always
+  removed. It authenticates with the Xcode account, or with
+  the App Store Connect API key in ios.appStoreConnectKeyPath,
+  ios.appStoreConnectKeyId and ios.appStoreConnectIssuerId (or
+  STIM_ASC_KEY_PATH, STIM_ASC_KEY_ID, STIM_ASC_ISSUER_ID, each overriding its
+  own setting); it never reads the key and never prints its path. It reports
+  the installed profile and any new keychain identity, and on a failure or
+  interrupt it still reports what had already changed. It changes the team's
+  developer account: agents run it only on the user's explicit go-ahead.
+
   DEBUG REACHES METRO OVER THE LAN, because a phone shares no loopback with
   the host and USB carries no reverse forward. Stim picks a non-internal IPv4
   address (en0 first, RN's own order from react-native-xcode.sh), gates it as
@@ -7558,11 +8065,16 @@ scoped STIM_HOME homes unless STIM_MAINTENANCE is explicit, so a scratch home
 or CI run never deletes on its own.
 Commands trigger a detached pass when a check is due: disk and memory pressure
 (every minute), directory sizes (hourly), finished worktrees (every 15
-minutes) and the age sweep (daily). guide, settings and help do not trigger
-it; gc --delete also skips the hook. status --watch also triggers checks.
+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
 least one minute. Measured directories are workspace build outputs and Stim's
-shared native, Metro, ccache, Swift compilation and registered caches.
+shared native, Metro, ccache, Swift compilation and registered caches. The size
+check also records the disk of each owned and parked simulator and emulator
+(category owned-devices); status prints the total as "owned devices".
 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
@@ -7580,20 +8092,83 @@ In on mode a pass runs, cheapest to rebuild first:
      maintenance.capTargetPercent of caches.buildCacheMaxGb or
      caches.metroCacheMaxGb, and entries unused for olderThanDays
   4. the Swift compilation cache, emptied whole, only below
-     budget.hardFloorDiskGb and with no build lock or slot held
+     budget.hardFloorDiskGb, and kept while an iOS build holds its shared
+     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
+     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.
 Disk-driven steps stop once free space is back above the floor. Kept for
 every pass: a workspace that is in use, holds a lock, was used within
 maintenance.protectRecentHours, is pinned with maintenance.keep, or is the
 workspace of the command that started the pass; cache entries used within
 protectRecentHours, named by a project's last builds, a parked device or a
 live build lock, or in a Metro store with a running or unverifiable dev
-server. Anything the pass cannot verify is kept. A pass never shuts down idle devices or dev servers or stops watchman; removing a
+server. Anything the pass cannot verify is kept. A device is deleted only when
+its workspace is idle: no dev server, native run, build, lease, managed lock,
+driven or busy device, and no recorded use within the window. Below disk
+pressure level 3 a pass never stops a dev server or watchman; removing a
 finished worktree or orphaned directory does tear down that workspace's own
 dev server, owned devices and Chrome profile, as gc --delete does. ccache evicts by itself under
 caches.ccacheMaxGb.
 
+DISK PRESSURE LEVELS
+  Level 1 is free disk under the floor above (budget.minFreeDiskGb, 20 GB).
+  Level 2 is under maintenance.urgentFreeDiskGb (12), and level 3 is under
+  maintenance.criticalFreeDiskGb (6) or budget.hardFloorDiskGb, where builds
+  refuse. When level 1 leaves free disk under the floor, a pass goes on with
+  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.
+  Level 2:
+    1. build outputs of workspaces unused for the short window
+    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/*
+    4. owned simulators and emulators of workspaces idle for the short window
+    5. Stim temp directories and xctrace recordings in TMPDIR unmodified for
+       24 hours, with gc --delete's checks (see stim guide cleanup gc)
+  Level 3:
+    1. the Swift compilation cache, emptied whole under the same build rule;
+       when a build keeps it, the last pass's blocked reasons name its size
+       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)
+    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
+    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
+       process that keeps step 6 from running is such a daemon; the pass
+       waits up to 3 seconds for them to exit
+    6. Gradle version caches and wrapper distributions no registered project
+       pins, once unmodified for maintenance.gradleVersionIdleDays days (7;
+       0 turns steps 5 and 6 off), with the same checks as gc --cache
+       gradle-versions, run again after step 5 so a daemon that did not exit
+       still keeps them
+  A directory is cleared only when it is a real directory inside its
+  worktree, git tracks nothing in it, its worktree is not in use, holds no
+  lock or build and is not pinned, and nothing under it, nor the worktree's
+  git index, HEAD or Stim state, changed within the short window. A dirty or
+  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.
+  status shows the level and, at level 3, the shortfall in the last pass;
+  every command prints one stderr line while the last check, at most 10
+  minutes old, measured level 3.
+
   stim status                     last checks, plan and running pass
   stim status --json              maintenance observations and recent records
   stim logs --source maintenance  this workspace's maintenance records
@@ -7608,6 +8183,9 @@ In report mode actions and explaining skips are logged only when newly
 planned; in on mode every action taken, failure and explaining skip is logged
 with its bytes, and a pass record carries the bytes freed. Removal of a
 worktree or orphaned directory is logged to the machine log only.
+An iOS build that fails on a corrupt compilation cache logs the emptying,
+or why Stim left the cache alone, with trigger "ios build", in every mode;
+see \`stim guide errors STIM_COMPILATION_CACHE_CORRUPT\`.
 maintenance.logChecks enables debug observations; default false.
 status and doctor report invalid settings and unresolved claims with a removal
 command to run only after confirming the holder is gone. Invalid cache caps
@@ -7615,6 +8193,10 @@ fall back to their own defaults; invalid maintenance settings disable passes.
 Pin a workspace with \`stim settings set maintenance.keep true\` in its project.
 The run claim serializes passes with gc --delete; gc refuses a held claim
 with the holder and recovery guidance instead of waiting.
+Each pass keeps a 1 MiB file, maintenance/disk-reserve. When taking the run
+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.
 
 CLEANUP AND DISK
 
@@ -7630,15 +8212,22 @@ See stim guide logs for AGENT_DEVICE_STATE_DIR examples.
 WHAT RECLAIMS AN OWNED DEVICE
   stim worktree remove    parks eligible owned simulators and emulators
                             (\`guide lifecycle pool\`); deletes them when
-                            parking is disabled or their setup cannot be verified
+                            parking is disabled, their setup cannot be
+                            verified, or free disk is at pressure level 2 or 3
   stim gc --delete        sweeps devices this Stim home created that no project
                             references (\`guide cleanup gc\`), clears
                             verified parked simulators and emulators, and
-                            runs \`stim worktree remove\` on every clean,
-                            Stim-managed linked worktree whose branch is merged,
+                            runs \`stim worktree remove\` on every clean
+                            linked worktree of a registered repository whose
+                            branch is merged,
                             or whose pull request was merged or closed, and
                             that shows no activity within
-                            gc.worktreeGraceMinutes
+                            gc.worktreeGraceMinutes, and deletes the owned
+                            devices of a finished worktree it keeps (dirty,
+                            unpushed, locked) when its workspace is idle for
+                            that grace and not pinned by maintenance.keep
+  automatic maintenance   deletes the owned devices of idle workspaces
+                            (MAINTENANCE above)
   stim gc --delete --older-than <days>
                             also reaps the device of a workspace no Stim
                             command has used in that long, even though the
@@ -7716,7 +8305,7 @@ to stats.json.corrupt-<unix ms> and starts a new one.`,
   Archived log subscriptions send retained records, then logs-ended.
   Archived frame subscriptions need at and cannot be physical or go live.
   Replay ranges report recording disabled.
-  Reads stay on this Mac.
+  Reads stay on this machine.
   An updated server is required; older servers refuse with bad-request when
   workspace is omitted. There is no CLI archive log flag.
   archive.enabled defaults true and accepts every settings layer. STIM_HOME
@@ -7789,6 +8378,69 @@ caches, never changes actionable, and --delete and --older-than never select
 it. Any --cache scope, including all, omits measurement and reports
 sections.swiftpmCache: null. Only stats and unscoped gc measure it.
 
+GRADLE VERSIONS
+\`stim gc --cache gradle-versions\` lists, and with --delete removes, the
+caches/<version> and wrapper/dists/gradle-<version>-* directories under
+GRADLE_USER_HOME of each Gradle version no registered project pins, read from
+the wrapper of each project's Android Gradle root and root. Nothing is deleted
+while a process that may be Gradle using this home runs: a Gradle main
+class, a Gradle wrapper or distribution jar, or a java process naming a path
+under the home, unless it names no such path and every gradle.user.home or
+-g it names is an existing Gradle home elsewhere, while ps fails, while no Stim config
+exists, while a registered project is missing or its pin cannot be read,
+while a Gradle directory cannot be listed, or while caches, wrapper or
+wrapper/dists is a symlink or resolves outside the home;
+sections.gradleVersions.blocked names the reason. A version is also kept
+when one of its paths is not a plain directory inside the home, when an
+entry under it cannot be listed or stat'd, when it holds more than 500000
+entries, or, with --older-than <days>, when anything under it changed within
+that many days.
+Right before removal gc lists processes and reads pins again, then renames
+each directory to a .stim-delete-* sibling and deletes it. A later gc
+--delete --cache gradle-versions finishes any .stim-delete-* left by a failed
+removal, even while the versions are blocked (not while the home is outside
+a scoped STIM_HOME or its layout is unsafe), since nothing uses those
+directories, and reports it again when that fails; plain gc --delete and
+automatic maintenance never touch them. modules-2, build-cache-1, jdks and
+other shared Gradle caches are never deleted, and --cache all never includes these versions.
+With STIM_HOME set, gc deletes nothing in a Gradle home outside it. At disk
+pressure level 3 automatic maintenance first stops the idle Gradle and Kotlin
+daemons gc --delete --cache gradle-daemons would stop, only when every Gradle
+process that keeps a version is such a daemon, then does the same for
+versions unmodified for maintenance.gradleVersionIdleDays days (7; 0 turns
+both off). A manual gc --delete --cache gradle-versions never stops daemons.
+
+OTHER TOOLS' MACHINE-WIDE CACHES (REPORT ONLY)
+Unscoped gc also reports large caches other tools keep for the whole machine,
+each with its size and the owning tool's own remedy:
+- Gradle version caches and wrapper dists under GRADLE_USER_HOME (default
+  ~/.gradle) for versions no registered project pins in the
+  gradle/wrapper/gradle-wrapper.properties of its Android Gradle root
+  (android.gradleRoot, default android, relative to the app, inside the
+  repository; a custom root must hold settings.gradle and the module's build
+  script) or of the project root, and caches/modules-2. A registered project
+  that is missing, whose settings cannot be resolved, or whose wrapper cannot
+  be read or names no Gradle version is named, since it may still pin a
+  listed version; every version a readable wrapper of it pins still counts as
+  pinned. A directory that cannot be listed adds a notice and marks the
+  section incomplete.
+  Gradle removes version caches and modules-2 entries unused for 30 days on
+  its own. The remedy for a version is stim gc --delete --cache
+  gradle-versions (see GRADLE VERSIONS); modules-2 stays report only.
+- iOS simulator runtimes with their simulator count. Only a deletable
+  runtime no simulator uses gets the remedy xcrun simctl runtime delete <id>.
+- Xcode device support entries under ~/Library/Developer/Xcode/*DeviceSupport.
+  Xcode copies an entry again when that device next connects.
+- agent-device runner builds grouped by agent-device and Xcode build version,
+  compared with the installed agent-device and Xcode. agent-device has no
+  prune command; remove an entry not in use by hand.
+$STIM_HOME/machine-cache-usage.json caches the sizes, simulator runtimes and
+tool versions for 10 minutes and measures again when the measured
+directories change. Stim never deletes any of these. They are never in
+caches, never change actionable, and --delete and --older-than never select
+them. Any --cache scope omits measurement and reports sections.machineCaches:
+null.
+
 LINKED WORKTREES
   \`stim worktree remove\` works with any linked worktree, warmed or not.
   Git registration identifies the worktree; a Stim registry entry is not
@@ -7819,20 +8471,43 @@ IN USE
   existence cannot be read (a permission error) is never treated as deleted.
 
 SWEEPING FINISHED WORKTREES
-  Every \`gc\` without --cache looks at every registered project root and
-  every workspace.json root, grouped by git worktree, and reports each linked
+  Every \`gc\` without --cache looks at every registered project root,
+  every workspace.json root, and every linked worktree \`git worktree list\`
+  shows for a registered project's repository, whether or not a stim command
+  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
   one that is idle: no recorded use for --older-than days, 7 without it; a
-  worktree whose last use is unknown is kept. Both need the same clean state;
-  a worktree is kept when it is the source checkout, bare, locked, in use,
+  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;
+  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
   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
   source checkout and roots outside git.
 
+  Each worktree line also shows its in-tree build state: the size of the
+  build and dependency directories maintenance clears (DISK PRESSURE LEVELS
+  above) and a root .pnpm-store, largest first (APFS clones count in full).
+  A size comes from the disk-usage cache while it is under an hour old and
+  no entry was added to or removed from its directory since (a build that
+  only grows files deeper inside shows within the hour); otherwise gc runs
+  one du per directory, 4 at once, 10 seconds each, and a directory du did
+  not finish shows "size unknown". du counts hard links shared between two
+  directories in both. gc never deletes them on their own;
+  the JSON field is buildState. Only directories of this worktree count,
+  not those of a worktree nested inside it.
+
+  A directory directly under a registered repository's .worktrees/ that
+  \`git worktree list\` does not show and that no git knows (no .git, or a
+  .git file whose gitdir is gone, as after a prune) is listed under "Directories under .worktrees that git does
+  not list as worktrees" with its size and the rm -rf command, and never
+  removed: gc cannot check it for uncommitted work. Look through it first.
+
   IN USE means its dev server supervisor runs, a stim ios, android or stop
   run holds its native-run lock, a live build lock or slot names it, a
   managed tunnel or remote lock is held, an owned simulator or emulator of
@@ -7854,9 +8529,32 @@ SWEEPING FINISHED WORKTREES
   activity cannot be read, the worktree is kept (reason activity-unknown).
   0 turns the grace period off.
 
+  FRESH STATE: \`gc --delete\` and the maintenance worktree check fetch the
+  default branch and ask gh as MERGED and PULL REQUESTS below describe. The
+  worktree check runs in the background when a stim command starts a
+  maintenance pass that has it due, every maintenance.worktreeCheckMinutes;
+  plain gc never starts one. It writes each pull request lookup into the
+  cache \`status --watch\` also writes. A report without --delete runs no
+  fetch and no gh: it judges merges from the existing origin/<default> ref and
+  takes a pull request from that cache when it records the worktree's current
+  branch and HEAD. Both count as fresh while they are younger than twice the
+  worktree check interval, and never less than 10 minutes. A merge found
+  against the existing ref stays true as the default branch moves on, so a
+  report calls a worktree removable only on facts fresh state keeps, with
+  three exceptions: a force-push that dropped the merge from the default
+  branch, a pull request reopened since the lookup, and the grace period of a
+  pull request merged or closed after its merge commit was made. A kept worktree whose
+  verdict fresher state could change says "merge state not refreshed", and
+  its reason not-merged becomes merge-unknown. With maintenance.mode off or
+  maintenance.removeFinishedWorktrees false the check never runs, and only
+  \`gc --delete\` refreshes. \`gc --delete\` always collects fresh state
+  before it removes anything; \`stim worktree remove\` run from a report
+  checks only for uncommitted and unpushed work.
+
   MERGED means, with the default branch taken from origin/HEAD, after a
   \`git fetch origin <default>\` per repository (30s timeout, no credential
-  prompt; skipped when that checkout fetched in the last 10 minutes):
+  prompt; skipped when that checkout fetched in the last 10 minutes; FRESH
+  STATE above for a report):
   - HEAD is reachable from origin/<default> through a merge commit, and the
     branch's reflog shows a commit made on it that HEAD contains. A branch
     with no commit of its own -- fresh, cut from another branch, or reset
@@ -7877,8 +8575,23 @@ SWEEPING FINISHED WORKTREES
   not block removal, because their change is on the default branch, and the
   branch is kept.
 
-  PULL REQUESTS: gc runs one \`gh api graphql\` query per repository that
-  asks for the 20 newest pull requests of each linked worktree's branch, as
+  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.
+
+  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
   \`gh pr list --head <branch> --state all\` would, and for each worktree
   takes the pull request whose head is HEAD, else one whose head contains
   HEAD. A pull request whose head HEAD is past ("PR #12 merged, and HEAD has
@@ -7896,14 +8609,15 @@ SWEEPING FINISHED WORKTREES
   not looked up. \`stim worktree remove\` makes the same check when
   local-only commits alone would refuse the removal, and accepts a merged
   pull request whose head is or contains HEAD.
-    stim gc                                        # report merged worktrees
-    stim gc --delete                               # remove them
+    stim gc                                        # report merged worktrees from local state
+    stim gc --delete                               # refresh, then remove them
     stim gc --delete --worktrees --older-than 3    # also the clean idle ones
   --cache with --worktrees is refused with STIM_BAD_ARG; run them separately.
   With --delete it runs the \`stim worktree remove\` pipeline, never --force,
   on each removable worktree. That pipeline re-inspects the worktree and
   re-checks use and recent activity under the removal locks, and idleness
-  for an idle worktree or an unchanged HEAD for a merged one, then parks
+  for an idle worktree, an unchanged HEAD for a merged one, or both for one
+  with no commits of its own, then parks
   devices through the same teardown and handles the
   branch exactly as a manual \`stim worktree remove\`, which keeps the
   checkout when its HEAD moves while devices are reclaimed. A worktree that
@@ -7935,9 +8649,27 @@ ORPHANED WORKSPACE DIRECTORIES
   it. A directory with a missing or unparseable workspace.json, or a root on
   an unmounted volume, is reported under Skipped and never deleted.
 
+TMPDIR LEFTOVERS
+  \`gc\` without --cache reports recognized entries directly in the user's TMPDIR
+  under "TMPDIR leftovers", with their count, size and a remedy: Stim temp
+  directories (stim-claim-*, stim-host-*, stim-fakehome-*,
+  stim-hosted-macos-*, stim-server-*, stim-ws-*), xctrace recordings
+  (instruments*.ktrace) and Jest's jest_<uid in base 36> cache. \`gc --delete\` checks
+  them again and deletes a Stim temp directory or recording only when nothing
+  in it changed for 24 hours. It keeps a Stim temp directory that contains or
+  sits inside a registered project, holds a live or unverifiable ownership
+  claim or a .lock directory that is not a claim set, or cannot be listed. It
+  keeps a recording that cannot be read, and every recording while an xctrace
+  or Instruments process runs or the process list cannot be read. Jest's cache and every other entry
+  are never deleted. gc never follows a symlink and never acts outside TMPDIR.
+  With STIM_HOME set it neither reports nor deletes them, because TMPDIR is
+  shared by every Stim home. Automatic maintenance runs the same deletion at disk pressure
+  level 2.
+
 STALE STATUS CACHE ENTRIES
   \`stim status\` caches each folder's size under $STIM_HOME/disk-usage and
-  each worktree's pull request under $STIM_HOME/pull-requests. \`worktree
+  each worktree's pull request under $STIM_HOME/pull-requests, which the
+  maintenance worktree check and \`gc --delete\` also write. \`worktree
   remove\` drops the entries of the worktree it removed (its checkout,
   node_modules and workspace folder, and its pull request), not the size
   entries of its owned devices' data folders. \`gc\` reports the
@@ -8037,6 +8769,12 @@ run drops the dead config ENTRIES those projects left behind and frees their
 Metro ports. \`stim gc --json\` prints the same report as one payload
 (\`guide facts gc\`); show the user its sections before \`gc --delete\`.
 
+Ctrl-C stops pending GC actions and drains verified owned children before exiting
+130. Completed actions remain applied. Unverifiable child cleanup keeps its
+ownership claims and prints STIM_CLAIM_UNAVAILABLE with a recovery remedy.
+With --json, cancellation prints one STIM_CANCELLED payload, or the cleanup
+refusal when cleanup cannot be verified.
+
 REMOTE EAS SESSIONS
   Plain \`stim gc\` is a dry run. \`gc --delete\` can stop active stim-* EAS
   sessions after workspace state is missing. The stop needs verified
@@ -8303,8 +9041,11 @@ WORKSPACE BUILD OUTPUTS
   and worktree warm record in state.json, lastBuild.startedAt,
   supervisor.startedAt and the mtimes under logs/, so a dev server that keeps
   logging keeps its workspace in use.
-  The same time decides \`--older-than\` device reaping, and a workspace with
-  no evidence of use keeps its device.
+  A workspace with none of those was last used when its workspace.json was
+  written, which happens once, when the workspace is created; only a
+  workspace with no readable workspace.json has an unknown last use. The
+  same time decides \`--older-than\` device reaping and automatic device
+  deletion, and a workspace whose last use is unknown keeps its device.
   The next build of an unchanged app installs from the shared build cache.
   After a native change the Xcode compilation cache speeds the rebuild, but on
   React Native 0.86 Swift does not use it (explicit modules are off), so that
@@ -8492,9 +9233,10 @@ KEYS STIM READS
                         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 Mac is full or
+                        "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. See lifecycle hosted-ios.
+                        lower layer says otherwise. 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).
@@ -8535,6 +9277,19 @@ KEYS STIM READS
                         name: Stim is non-interactive, so it refuses an
                         ambiguous identity rather than picking one. It wins
                         over ios.signingIdentity.
+  ios.appStoreConnectKeyPath, ios.appStoreConnectKeyId, ios.appStoreConnectIssuerId
+                        machine scope only; STIM_ASC_KEY_PATH, STIM_ASC_KEY_ID
+                        and STIM_ASC_ISSUER_ID each override their own
+                        setting when set and non-empty. The absolute
+                        path of an App Store Connect API key (.p8), its key
+                        ID and its issuer ID. Only \`stim device provision
+                        ios\` reads them, passing them to xcodebuild as
+                        -authenticationKeyPath/-authenticationKeyID/
+                        -authenticationKeyIssuerID instead of the Xcode
+                        account, so provisioning works on a Mac where nobody
+                        signs in to Xcode. Set all three or none; Stim never
+                        reads the key file or prints its path. Builds never
+                        use them.
   ios.lanHost           e.g. "192.168.1.42" -- the address a phone uses to
                         reach this workspace's Metro on an \`ios --device\`
                         Debug run, pinning the interface on a multi-NIC Mac
@@ -8653,6 +9408,18 @@ ${ANDROID_AVD_CONFIG_HELP.map((line) => `                          ${line}`).joi
                         build: embedded JS, no Metro, cache keyed on the
                         variant, and an APK re-pack on cache hits. See
                         \`guide lifecycle release\`.
+  android.artifactInputs a native Gradle APK cache declaration:
+                        complete: true, ignored: [exact repository-relative files],
+                        outputs: [generated repository-relative directories],
+                        localFiles: [exact project-relative or absolute files],
+                        environment: [variable names]. complete promises all
+                        inputs are repeatable and dependencies pinned. Include
+                        signing keys and every external or environment input.
+                        Missing local files and environment values are hashed
+                        as absent. Configured files providers can share the APK
+                        and verification receipt. Input values stay local;
+                        this is not build-worker transfer authorization.
+                        See the native Android guide.
   android.offloadInputs a native Gradle build-worker declaration:
                         {"complete":true,"ignored":[],"outputs":["build","app/build"]}.
                         complete confirms Git-visible source plus the exact
@@ -8660,7 +9427,7 @@ ${ANDROID_AVD_CONFIG_HELP.map((line) => `                          ${line}`).joi
                         build. outputs names generated directories reported
                         by AGP; recorded outputs can survive worker sync.
                         Omitted optional inputs can change build results.
-                        Stim artifact caching remains unavailable. See
+                        Worker APK caching also requires artifactInputs. See
                         \`stim guide lifecycle native-android\` for input,
                         privacy and worker requirements.
   android.keystore      the keystore a RE-PACKED release APK is signed with,
@@ -8685,16 +9452,17 @@ ${ANDROID_AVD_CONFIG_HELP.map((line) => `                          ${line}`).joi
                         the debug keystore's fixed "android".
   android.remote        "proxy", "eas", or a named approved Mac in
                         remote.machines; "auto" places on an approved Mac when
-                        this Mac is full or busy. Unset runs here; "local"
+                        this machine is full or busy. Unset runs here; "local"
                         runs here even when a lower layer says otherwise.
-                        See lifecycle hosted-android.
+                        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
-                        billed EAS Simulator when this Mac is at its
+                        billed EAS Simulator when this machine is at its
                         concurrency.maxDevices cap (or has runs queued) and no
-                        remote.machines Mac takes the run, instead of waiting
+                        remote.machines entry takes the run, instead of waiting
                         or refusing with STIM_AT_CAPACITY. Default false. A
-                        busy Mac with a free slot never uses it. Stim checks
+                        busy machine with a free slot never uses it. Stim checks
                         first that the run could use --remote eas (eas-cli
                         with simulator commands, eas simulator:availability,
                         agent-device, the default slot, a reachable Metro);
@@ -8802,6 +9570,8 @@ ${ANDROID_AVD_CONFIG_HELP.map((line) => `                          ${line}`).joi
                         Debug by stim macos
   macos.infoPlist       development Info.plist relative to Package.swift,
                         without shared URL schemes or an update feed
+  macos.artifactInputs  complete pinned, repeatable inputs producing a relocatable
+                        app for completed build caching. See stim guide macos.
   macos.arguments       string array passed directly to the executable;
                         see stim guide macos for the prototype's limits
   macos.assetCatalog    optional .xcassets directory relative to Package.swift,
@@ -9052,51 +9822,61 @@ test suites and the end-to-end harness use one -- and a scoped config must not
 leave simulators on the machine it cannot account for. A redirected home that
 wants a pool says so with the variable.
 
-DESKTOP ACCESS TICKETS
-Stim Desktop's Add wizard sets STIM_ACCESS_TICKET for one \`doctor --fix\`
-run. Agents never set it, never run \`stim-server setup\`, never edit
+SETUP TICKETS
+A remote machine approves this one when a person there runs
+\`stim-server setup\` with this machine's setup ticket (32 random bytes, 43
+base64url characters) in STIM_SETUP_TICKET. Stim Desktop's Add wizard makes the
+ticket and sets STIM_ACCESS_TICKET for one \`doctor --fix\` run; without it,
+\`doctor --fix\` makes one and prints the setup command to run on the worker.
+Agents never set STIM_ACCESS_TICKET, never run \`stim-server setup\`, never edit
 \`remote.*\`, \`server.*\` or \`hosting.*\` for the user, and never approve requests.
-Stim sends the ticket (43 base64url characters) only in build and device-host access
-requests and stores only its SHA-256 ticketHash. With --fix, a still-pending
-request is replaced when its ticketHash is missing or differs from the current
-ticket; matching hashes and approved credentials are preserved.
+Until setup approves, the worker answers unknown-secret and the entry stays
+pending; every doctor run tries again. The first connection after approval pins
+the worker's stim-server key in build-machines.json or device-host-machines.json,
+and every later connection must prove that key; the tailnet node and address
+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.
 
-REMOTE MACS AND PHONE APP
-When the user mentions slow builds, a busy Mac, a full disk or device limit, or
+REMOTE MACHINES AND PHONE APP
+When the user mentions slow builds, a busy machine, a full disk or device limit, or
 wanting updates away from the desk, tell them about Stim Desktop > Settings >
-Remote Macs > Add (a Mac on the tailnet that builds or hosts simulators for
-this one) or Phones > Pair a Phone (the Stim phone app). Stim Desktop also
-suggests these itself, at most once a day and never during a build. Agents only
-tell the user: they never run \`stim-server setup\`, never edit \`remote.*\`,
-\`server.*\` or \`hosting.*\` for the user, and never approve requests.
-
-REMOTE MACS ARE MACHINE-LEVEL
-\`remote.machines\` names the remote Macs this Mac may build on and host owned
+Remote Machines > Add (another machine on the tailnet that builds for this one,
+or a Mac that also hosts simulators) or Phones > Pair a Phone (the Stim phone
+app). Stim Desktop also suggests these itself, at most once a day and never
+during a build. Agents only tell the user: they never run \`stim-server setup\`,
+never edit \`remote.*\`, \`server.*\` or \`hosting.*\` for the user, and never
+approve requests.
+
+REMOTE MACHINES ARE MACHINE-LEVEL
+\`remote.machines\` names the remote machines this machine may build on and host owned
 simulator sessions on, by MagicDNS name with an optional serve port (default
 7443). Name each node and port once:
 
   stim settings set remote.machines '["janics-mac-mini"]'
   stim doctor --fix
 
-Automatic membership is separate from approval. In Desktop Settings > Remote Macs,
-use Builds enabled and Simulators enabled for this Mac or a configured remote.
-The equivalent machine settings list the excluded members; both default to []:
+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;
+both default to []:
 
   stim settings set remote.buildPoolDisabled '["local"]'
   stim settings set remote.devicePoolDisabled '["janics-mac-mini"]'
   stim settings unset remote.buildPoolDisabled
 
-Use local for this Mac and exact remote.machines entries for remotes, including
+Use local for this machine and exact remote.machines entries for remotes, including
 case and port. Names are not trimmed; unmatched entries exclude nothing. Copy the
 configured name or use Desktop's switches. Each pool
 must retain local or at least one configured remote already approved for that role.
 Offline approved members count as configured members, but placement still requires
-an available compatible host. Settings refuses removing the last member, including
-removing it from remote.machines. Disabling does not unpair a machine or stop a run.
+an available compatible host. A remote that tailscale status reports as running an
+OS other than macOS is never a device-pool member or hosting candidate, since it
+cannot host; an unknown OS counts as able to host. Settings refuses removing the
+last member, including removing it from remote.machines. Disabling does not unpair a machine or stop a run.
 
-These settings apply only to new automatic work requested by this Mac. They do not
+These settings apply only to new automatic work requested by this machine. They do not
 change which work other requesters send to a host. Named placement and --remote-build
 local bypass membership; the default device placement without --remote auto remains
 local. Existing local and hosted device sessions keep their owner. Cache hits remain
@@ -9106,16 +9886,33 @@ local alone does not trigger billed EAS fallback; an existing explicit EAS opt-i
 requires the physical device cap or queue condition. Restore membership before retrying or choose
 an explicit placement. Build and simulator memberships are independent.
 
-A remote Mac is used for a capability only after it grants that approval. Build
-and device-host approvals are separate: a Mac in the list that never granted
+A remote machine is used for a capability only after it grants that approval. Build
+and device-host approvals are separate: a machine in the list that never granted
 one is not an error, it is not used for that capability, and doctor reports
 it plainly.
 
+PAUSE INCOMING WORK
+On the worker machine, an operator can temporarily refuse new incoming builds or
+hosted sessions without revoking any clients:
+
+  stim settings set server.buildsPaused true
+  stim settings set server.devicesPaused true
+
+Both machine settings default to false. The running server reads changes without
+restarting and rechecks admission after an earlier offer. Running builds and
+existing iOS, Android and macOS hosted sessions continue; attach, cached artifact
+retrieval and stop remain available. Local CLI builds and devices are unaffected.
+These settings apply to every requesting machine, including explicit placement.
+Desktop's pool switches instead affect only that requester's automatic placement.
+Set either setting to false to resume that capability. A pause does not make the
+machine idle: wait for existing work to finish or stop the relevant sessions before
+benchmarking. Agents change these settings only when the user asks them to.
+
 DEVICE HOSTING
-Only \`doctor --fix\` asks for device-host access. A person on that Mac
-approves the printed id with \`stim-server devices grant <id> --device-host\`.
-A person can also run \`stim-server setup\` on the worker: one node, one ticket,
-one expiry, at most one request per capability, with a per-grant Y/n question (Enter approves) in a
+Only \`doctor --fix\` asks for device-host access: it makes a setup ticket and
+prints the command. A person approves by running \`stim-server setup\` on the
+worker with that ticket: one ticket, one expiry, one record per capability for
+the key that holds the ticket, with a per-grant Y/n question (Enter approves) in a
 terminal or \`--yes\` otherwise. Agents never run \`stim-server setup\` or
 approve requests. Setup never changes TCC or enables Funnel; an SSH-driven
 run is not offered. Without a terminal or --yes, setup refuses before installing
@@ -9123,10 +9920,10 @@ unless every chosen capability already has a matching approval. Desktop reuse
 requires an existing tailnet route. Ctrl-C or SIGTERM completes the journal,
 releases the setup claim and exits 1; a typed N also exits 1. Hosting grants
 include no read, control or build capability.
-On a remote Mac that hosts, Stim Desktop > Settings > Remote Macs > Running here lists the
-simulators, emulators and apps approved Macs run there, below Macs using this
-Mac. Stop asks for confirmation, ends the session and deletes or parks
-its device on that Mac. Parked sessions remain listed without Stop. The list
+On a remote Mac that hosts, Stim Desktop > Settings > Remote Machines > Running
+here lists the simulators, emulators and apps approved machines run there, below
+Macs Using This Mac. Stop asks for confirmation, ends the session and deletes
+or parks its device on that Mac. Parked sessions remain listed without Stop. The list
 refreshes every five seconds and stays hidden when the local server does not
 support it.
 $STIM_HOME/device-host-machines.json stores a private token and pinned tailnet
@@ -9136,7 +9933,7 @@ stim settings set ios.remote auto --scope machine (or android.remote; workspace,
 repo and committed scopes override the machine default),
 or per run stim ios --remote auto / stim ios --remote <machine>.
 New Desktop runs pass no --remote flag; recorded hosted sessions keep their
-machine until stim stop. Only devices outside this Mac show "on <machine>"
+machine until stim stop. Only devices outside this machine show "on <machine>"
 on tiles, workspace pages, viewer toolbars and sidebar rows, with the reason
 as hover text.
 Stim sends tokens only to the pinned node's own tailnet address,
@@ -9162,30 +9959,29 @@ shared daemon only when that agent-device can lease a single app (its
 notice, and no client is handed the Mac's desktop. STIM_AGENT_DEVICE_BIN in
 stim-server's environment names an agent-device binary to use instead of
 ~/.local/bin/agent-device. Hosted iOS uses one daemon per simulator, pinned by
-its UDID policy; both Macs need agent-device 0.21.20 or later. Hosted Android
+its UDID policy; both machines need agent-device 0.21.20 or later. Hosted Android
 uses one daemon per emulator, pinned by its serial policy, with agent-device
-0.21.22 or later on both Macs. See guide lifecycle
+0.21.22 or later on both machines. See guide lifecycle
 hosted-ios. \`doctor\` on that Mac notes an installed hosted app that runs while
 the setting is \`none\`.
 
 REMOTE BUILDS
-The same \`remote.machines\` list names the Macs that may build for this one:
+The same \`remote.machines\` list names the machines that may build for this one:
 
   {
     "remote": { "machines": ["janics-mac-mini"] }
   }
 
-\`doctor --fix\`, run in any app directory, asks each named Mac for build access and pins its tailnet
-node in $STIM_HOME/build-machines.json. A person approves the request on that
-Mac with \`stim-server devices grant <id> --build\`; doctor prints the id.
-A person can instead run \`stim-server setup\` on the worker with a node,
-ticket and expiry, under the approval rule above. A build grant is full access
+\`doctor --fix\`, run in any app directory, makes a setup ticket for each named
+machine and prints the \`stim-server setup\` command a person runs on that
+machine to approve this one, under the approval rule above. The next doctor run
+pins the worker's stim-server key in $STIM_HOME/build-machines.json. A build grant is full access
 to the account stim-server runs as: project code runs there unsandboxed, so it
 can grant itself read and control. Revoking it does not undo what that code
-already did. Grant it only to Macs you trust.
-Stim connects to a named Mac only while its name still belongs to the pinned
+already did. Grant it only to machines you trust.
+Stim connects to a named machine only while its name still belongs to the pinned
 node and never sends the token to another node. \`doctor\` reports each
-remote Mac's build pairing state and, for an approved one, asks it for one build
+remote machine's build pairing state and, for an approved one, asks it for one build
 offer and lists every reason it would not take this app's iOS build: no
 answer, another Stim build, CPU, Xcode, simulator SDK or CocoaPods, no
 Bundler for an app whose Gemfile.lock pins CocoaPods, no iPhone simulator on
@@ -9200,12 +9996,12 @@ 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 Mac for this invocation
+  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 Mac's load/slot gating
+         approved for builds; ignores remote.buildMode and this machine's load/slot gating
 
-A name never prompts for pairing, tries another remote Mac or falls back here.
-Any refusal or failure is STIM_OFFLOAD_REFUSED with the remote Mac and reason.
+A name never prompts for pairing, tries another remote machine or falls back here.
+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
 refuse on a cache miss. Invalid values, unlisted names and unpaired names refuse
@@ -9213,12 +10009,11 @@ 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 Mac before a named offload. A refusal
+Prebuild and pod install still run on this machine before a named offload. A refusal
 starts no local xcodebuild, Gradle or SwiftPM compile.
 Run stim doctor --fix to ask for build access if not paired. A person on the
-worker finds the id with stim-server devices and approves it with
-stim-server devices grant <id> --build, or runs stim-server setup there with
-the client node, ticket and expiry. Check stim settings get remote.machines,
+worker approves it by running the stim-server setup command doctor printed, with
+its ticket and expiry. Check stim settings get remote.machines,
 or rerun with --remote-build auto or --remote-build local. Ctrl-C cancels
 the remote build without a local xcodebuild, Gradle or SwiftPM compile.
 
@@ -9229,23 +10024,29 @@ Copyable agent prompt:
 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:
 
-  auto   (default) here while this Mac has capacity: a free
+  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 Mac that accepts the build and is expected to be faster:
-         while every slot here is busy, any remote Mac that accepts; while only
+         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
-         Mac's. A Mac too old to report its load counts only while every
+         machine's. A machine too old to report its load counts only while every
          slot here is busy.
-  force  on a remote Mac whenever one accepts it
+  force  on a remote machine whenever one accepts it
   off    here when local remains enabled in the automatic build pool
 
-Load per core is the 5-minute load average divided by the CPU count; a Mac's
-native builds are its Stim runs in prebuild, pods or compile on that Mac, not
+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 and install
+arguments, 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 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 Mac
-counts as saturated, both here and on a remote Mac.
+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.
 
 STIM_REMOTE_BUILD_MODE overrides it for one command. Device, Release and
 \`--remote eas|proxy\` builds, Android builds with the Apple Clang CAS compiler cache,
@@ -9254,20 +10055,39 @@ Debug builds can use a separate --remote-build, targeting the hosting Mac's
 architecture and runtime.
 macOS uses matching Xcode and macOS SDK, with a per-client SwiftPM dependency
 cache on the worker. It skips JavaScript dependencies, prebuild and pods; see
-stim guide macos. macOS artifacts are not cached.
+stim guide macos. Completed caching requires macos.artifactInputs and a locally
+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 CPU matches the target simulator, with enough disk, that does not decline,
+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,
 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
+reuse an exact completed archive from an enabled paired worker. Its full key
+includes source, Xcode, SDK, architecture and target options. A hit skips sync
+and compilation even while the worker is busy or this machine has room. Missing or
+corrupt archives follow normal placement. Off mode and an explicit local build
+do not query peer caches. Older workers continue normal placement. This peer
+lookup also covers declared native Gradle worker APKs when the worker supports
+native-gradle-peer-cache. It rechecks current private inputs against the saved
+receipt at offer and fetch for the requested source, resolved variant, ABI and
+build options. Caller fingerprints stay null; worker keys stay worker-scoped.
+React Native and Expo development builds also query enabled paired workers
+with react-native-peer-cache after local and configured-provider misses. Their
+post-mutation fingerprint, native build choices and compatible toolchain must
+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 pins CocoaPods: both Macs then run that version through
+the app's Gemfile.lock pins CocoaPods: both machines then run that version through
 bundler, so the machine needs only Bundler on its stim-server PATH and
 installs the pinned gems itself on the first build. The comparison selects
-the app's .ruby-version when installed, and otherwise the GEM_HOME, GEM_PATH and Ruby-related PATH entries of the Mac'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 JDK major
+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
 compile platform that the project's React Native version names in
 gradle/libs.versions.toml; Gradle and AGP come from the synced project. When
@@ -9277,7 +10097,7 @@ reason, such as \`janics-mac-mini: busy (load at or above 2/core; load
 \`git ls-files -co --exclude-standard\` lists (the machine keeps only files it
 lacks, so an unignored secret such as \`.env\` is sent too), builds with
 Stim's own code there, refuses unless the fingerprint there equals this one,
-and brings the \`.app\` or APK back. An Android build there uses this Mac's
+and brings the \`.app\` or APK back. An Android build there uses this machine's
 variant, target ABI, Gradle build cache, PCH and compiler cache choices, so
 the APK matches the ABI-narrowed cache key. Stim checks the archive's sha256
 and fingerprints this checkout again before it stores the app under the
@@ -9295,11 +10115,11 @@ interrupted while it reconnects, leaves it until those 5 minutes pass. With auto
 \`--json\` facts record the reason as offloadFallback. Offloading holds no
 local build slot; that fallback takes one. \`stim stats\` keeps where each
 compiling build ran and why (\`guide facts stats\`).
-An offloaded app lands only in this Mac's build cache, not in a remote cache
+An offloaded app lands only in this machine's build cache, not in a remote cache
 provider. A project whose xcodebuild changes its own fingerprinted inputs
 fails the offload fingerprint check: auto builds here; a named placement refuses.
 
-On a remote Mac that builds for others, stim-server keeps each client's checkouts, dependencies,
+On a remote machine that builds for others, stim-server keeps each client's checkouts, dependencies,
 DerivedData, compilation cache, ccache and Gradle home under
 \`server.workerRoot\` (absolute; default $STIM_HOME/build-worker), one area
 and Stim home per client and repository, and one Gradle home per client. It
@@ -9308,21 +10128,23 @@ less than 10 GB free, while its own native builds and the offloaded one fill
 its \`concurrency.maxBuilds\`, or while its load per core is at or above its
 \`server.maxLoadPerCore\`, and reports the reason in its offer. It boots and
 installs nothing. While an offloaded build runs there, it holds one of that
-Mac's \`concurrency.maxBuilds\` slots, so a local Stim build there waits for it
+machine's \`concurrency.maxBuilds\` slots, so a local Stim build there waits for it
 and counts it as busy; the slot is freed when the build ends, is cancelled or
 its process is gone. Android builds there run on the JDK in stim-server's
 JAVA_HOME (else the macOS default JDK) with the SDK in its ANDROID_HOME (else
-~/Library/Android/sdk). The client's Gradle daemon stays warm there for
+~/Library/Android/sdk, or ~/Android/Sdk on Linux). The client's Gradle daemon stays warm there for
 \`server.gradleDaemonIdleMinutes\` (default 30; 0 stops it when each build
 ends; a new value applies from the next daemon) and never holds a build
 slot. While none of the client's builds runs, stim-server stops it sooner
 when a build is cancelled, the client is revoked, or the machine has less
 than 2 GB of memory available, and deleting the client's directory under the
 worker root stops it too.
-\`stim-server service install [--serve]\` on the remote Mac keeps stim-server
-running as a login LaunchAgent; \`--path-prepend <dir>\` and \`--env KEY=VALUE\`
-pin a PATH entry or variable such as a private CocoaPods that stim-server's
-login-shell environment would otherwise replace.
+\`stim-server service install [--serve]\` on a remote machine keeps stim-server
+running as a login LaunchAgent on macOS, a systemd user service on Linux
+(\`sudo loginctl enable-linger <user>\` keeps it running after logout; install
+prints that command and never runs it), or a logon scheduled task on Windows; \`--path-prepend <dir>\` and \`--env KEY=VALUE\`
+pin a PATH entry or variable, such as a private CocoaPods, that stim-server's
+toolchain discovery does not find.
 \`stim-server service update --release <version>\` there moves the service to
 that exact stim-server release from the public npm registry once npm verifies
 its integrity and registry signatures; \`--from <dir>\` installs the packed
@@ -9330,15 +10152,15 @@ packages of a checkout instead, with the same signature check on each npm
 dependency but none for Stim's own packages. It waits for offloaded builds and hosted
 sessions to finish, restarts the job, and switches back when the new server
 exits or does not answer within 90 seconds; \`stim-server service rollback\` returns
-to the previous server. A client Mac approved for builds or device hosting
+to the previous server. A client machine approved for builds or device hosting
 there can ask for the same update over its tailnet connection: an npm release
 always, and its own packed build only while \`server.acceptClientBuilds\` is
 true on that machine (default false).
 Replacing a loaded service waits up to 45 seconds for its existing listeners to
 release the port. Uninstall does not wait for the port. If stopping the old job
-or starting the new one fails, install restores the previous plist and attempts
-to restart a previously loaded LaunchAgent; if it cannot, it prints the
-launchctl bootout/bootstrap remedy. A running LaunchAgent does not prove readiness; check \`stim-server service status\`
+or starting the new one fails, install restores the previous plist or unit and attempts
+to restart a previously running service; if it cannot, it prints the
+launchctl bootout/bootstrap or systemctl --user daemon-reload/restart remedy. A running service does not prove readiness; check \`stim-server service status\`
 and its reported log. The server listens before it touches the Stim home; a
 read-only child process reads the Stim home, server and recording directories,
 and until it returns \`/health\` answers 503 with \`startup.state\` pending.
@@ -9370,7 +10192,7 @@ stim-server records the screens of owned simulators, emulators and the
 Stim-owned Chrome page while an automation tool drives them or a paired client
 watches them, so the phone app can scrub back through them. It keeps the last
 15 minutes of footage per device under $STIM_HOME/workspaces/<id>/recordings/,
-on this Mac only, and serves it only to paired clients. \`recording.enabled\`
+on this machine only, and serves it only to paired clients. \`recording.enabled\`
 turns it off:
 
   stim settings set recording.enabled false --scope machine
@@ -9463,8 +10285,11 @@ The example shows the defaults. Full setting names and behavior:
   optimizations.remoteBuildCache
     false skips both optional remote artifact providers, including loading
     their modules and authentication. Local artifact caching stays enabled.
-    Stim ships no network provider or hosted cache. Remote artifact reuse
-    requires a provider configured through cache.provider or Expo.
+    Install @stim-cli/cache-s3 and select it through cache.provider for S3-compatible storage,
+    including Cloudflare R2, or configure another provider through Expo.
+    Stim does not run a hosted cache service; credentials use the AWS SDK chain.
+    S3 file uploads retry connection resets up to three PUT attempts, reopening
+    the completed file each time. Cancellation also stops the retry delays.
   optimizations.releaseBundleSwap
     false always builds Release from source, including the current JS;
     it never installs an old embedded bundle. Fresh artifacts can still store.
@@ -9534,7 +10359,9 @@ PCH mode matches; disable artifact caching too to force native compilation. Lega
 cannot key these compiler profiles, so Stim skips that tier for custom profiles
 and Android CAS. Providers implementing the Stim key contract remain usable.
 Android compiler/PCH profiles also get separate CMake staging directories under
-<module>/.cxx/stim-<profile>, or under the project's custom staging root. Switching
+<module>/.cxx/stim-<profile> (<module>/.cxx/<first 4 profile characters> on
+Windows, where every character counts against MAX_PATH), or under the project's
+custom staging root. Switching
 backends in Stim selects the matching directory without deleting previous builds.
 These directories accumulate across profile changes and shim upgrades. Stim
 does not prune them; remove an obsolete generated profile only with all native
@@ -9926,24 +10753,65 @@ changing focus: it sets STIM_BACKGROUND_LAUNCH=1 in the app's environment, which
 Stim Desktop honors, including for reopen events from open -g. An app that
 activates itself at launch or on reopen still takes focus.
 Hosted launches (macos --remote) do not set it.
-macOS artifacts are not cached. This prototype has no --slot or reload command.
+This prototype has no --slot or reload command.
+Completed app caching is opt-in with macos.artifactInputs:
+
+  { "macos": { "artifactInputs": { "complete": true,
+      "ignored": [], "outputs": [], "localFiles": [], "environment": [] } } }
+
+complete declares pinned, repeatable build inputs and an app that runs after its
+original checkout and scratch directory are gone. Do not enable it for mutable
+dependencies, build-time network data, undeclared environment or local inputs,
+or code that needs its original absolute source paths (including #filePath).
+Stim hashes Git-visible repository source, Package.resolved even when ignored,
+the development plist, declared resources, Swift/Xcode/SDK identity and CPU
+architecture. ignored names exact Git-ignored repository-relative input files;
+outputs names generated repository-relative directories already ignored by Git.
+localFiles names exact additional private files, relative to the package or
+absolute; environment names additional build-time variables. Values and private
+file contents are hashed locally and are not included in the shared receipt.
+Symbolic links in source inventories are currently ineligible for caching.
+Without a valid declaration Stim compiles normally and keeps SwiftPM incremental
+reuse. optimizations.buildCache and optimizations.remoteBuildCache also apply.
+The completed bundle uses the ordinary shared build cache and an optional
+cache.provider's files capability, including S3. A hit avoids compiler slots and
+placement, then gets this workspace's identifier and name on a re-signed copy.
+Corrupt or incompatible entries fall back to compilation. Inputs changed during
+compilation prevent publication. Compiler and package scratch state is not shared.
+An enabled paired worker with swiftpm-peer-cache can retain a completed archive
+after verifying its actual source, private inputs and toolchain before and after
+compilation. After local/provider misses, an exact peer hit skips source upload
+and compiler admission, even while that worker is busy. Private values stay on
+the worker; its opaque identity is not used as this Mac's local cache key.
+Ignored bundle files must be declared in ignored or localFiles for peer reuse.
+The worker rechecks private inputs before offer and fetch; deleting its checkout
+does not discard an archive whose private inputs remain valid. Toolchain versions and command selection are
+checked from the package directory. After checkout removal, only verified direct
+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
+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, staging, stopping or launching
+and declared resources without building, signing, stopping or launching
 an app, writing workspace state or claiming a build slot. It does not execute
 Package.swift, so it cannot validate the executable product or package dependencies.
 --remote-build is respected, including named-machine setup refusals; no worker
 is contacted and live worker availability is unknown. --remote is launch-only
 and refuses with --plan. The JSON plan has platform "macos", product and
-buildMachine; fingerprint, cacheKey, provider, prebuild, outcome and expectedMs
-are null, cacheHit and cacheSkipped are false, and basis is 0. SwiftPM decides
-incremental compile work when a build runs; the plan predicts no cache outcome
-or duration. Desktop checks automatically while build details are visible,
+buildMachine. An eligible cache identity supplies fingerprint and cacheKey;
+cacheHit reports a verified local completed artifact, checked in a disposable
+temporary copy. Providers and workers are not contacted. cacheSkipped is true
+when artifact caching is disabled or ineligible. provider, prebuild, outcome
+and expectedMs remain null, and basis is 0. SwiftPM decides incremental compile
+work when a build runs; the plan predicts no duration. Desktop checks automatically while build details are visible,
 reusing a completed build or check for 60 seconds and skipping running builds.
 A failed build records its error and compiler output without launching an app.
 While it runs, stim status --json reports it as environments[].build with
 platform "macos": phase prepare, compile, install, then launch, and during
 compile detail.unit "steps" with SwiftPM's [done / total] counts (fetching and
-planning are detail.step "configure"). It has no cache lookup, so outcome and
+planning are detail.step "configure"). outcome and
 plannedPhases are null; finished runs and their phase times are in
 environments[].builds.macos, where phases includes launch once the launch step finishes
 and compileSteps is SwiftPM's step total. An offloaded build reports the worker's
@@ -10144,11 +11012,11 @@ used.
 ON ANOTHER MAC
 
 stim macos --remote <machine> builds the Debug app on this Mac and runs it on an
-approved remote Mac over the tailnet, without SSH. The machine must be listed
-in remote.machines and approved: stim doctor --fix asks it, a person on that
-Mac runs stim-server devices grant <id> --device-host or stim-server setup
-with that client node, ticket and expiry (guide settings), and stim doctor then
-records the approval. Stim connects only to the machine's pinned tailnet node.
+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
 instead.
 
@@ -10207,7 +11075,7 @@ approved host that lacks them. A server started by Stim Desktop uses Desktop's
 grants.
 
 Hosted delivery carries the staged bundle with declared resources and compiled assets.
-When offload built it on the host's own tailnet node, the host copies the files
+When offload built it on the host's own stim-server, the host copies the files
 from the build it kept for this Mac instead of receiving them again, admitting
 only bytes that match the bundle's digests here. That needs both the build and
 the device-host approval for this Mac. Files the host cannot take, an older
@@ -10313,7 +11181,7 @@ outside the user's own projects.`;
 const local = `The tutorial runs on this Mac. Every time you run the tutorial app on iOS
 from a worktree of {base}, use stim ios --remote local --remote-build local,
 even when the user's settings would place the device or the build on another
-Mac. Only an explicit request to build on another Mac changes the build, with
+machine. Only an explicit request to build on another machine changes the build, with
 stim ios --remote local --remote-build "<machine>"; the device stays here.`;
 const screenshots = `Before and after screenshots, for a pull request: in each change's worktree,
 run the app on iOS before you edit anything, open it with agent-device and save
@@ -10636,7 +11504,7 @@ function renderIndex(version) {
 	return lines.join("\n");
 }
 function guideCommand(program, version, status = (running) => guideStatus({
-	projectRoot: findProjectRoot(process.cwd()),
+	projectRoot: findProjectRoot$1(process.cwd()),
 	running
 })) {
 	program.command("guide [topic] [section]").description("Print reference documentation for THIS version of Stim (topics: " + topicNames().join(", ") + "). A topic with sections prints its section index; name a section to print only it, e.g. `stim guide errors STIM_NO_METRO` or `stim guide lifecycle builds`. Generated by the binary, so it cannot drift from the installed CLI.").action(async (topic, section) => {