stim 1.23.0 → 1.24.0

package/dist/{guide-BC37GcDG.mjs → guide-Bggftwc5.mjs}

@@ -1,8 +1,8 @@
-import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-C7O8A6ZI.mjs";
-import { i as findProjectRoot$1 } from "./project-CTLNHCfE.mjs";
-import { h as RECENT_LAUNCH_MS } from "./eas-session-ledger-BzzsX97d.mjs";
-import { o as guideStatus, t as WATCHMAN_NESTED_WORKTREES } from "./doctor-watchman-sy_RNhFt.mjs";
-import "./status-watch-BIqqbJ6q.mjs";
+import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-RKwY33wv.mjs";
+import { i as findProjectRoot$1 } from "./project-Dz-hWkb-.mjs";
+import { h as RECENT_LAUNCH_MS } from "./eas-session-ledger-Ck6YXPAO.mjs";
+import { o as guideStatus, t as WATCHMAN_NESTED_WORKTREES } from "./doctor-watchman-B453A231.mjs";
+import "./status-watch-XC7F-AMf.mjs";
 import { SETTINGS, SETTINGS_SCHEMA_URL, TUTORIAL_VERSION } from "@stim-cli/core/state";
 import chalk from "chalk";
 //#region src/guide/agent.ts
@@ -191,13 +191,15 @@ RULES DURING THE LOOP
 - For stale Metro transforms or file-map state, use stim start --reset-cache.
   It restarts only this app's verified owned Metro, preserving devices and other
   apps' caches. See guide lifecycle for reset scope.
-- Reload is not part of the normal workflow. Use stim reload on an owned local
-  simulator or emulator when an error screen remains after the fix, and on
+- Reload is not part of the normal workflow. Use stim reload when an error
+  screen remains after the fix on an owned local simulator or emulator, a
+  physical device (an EAS Simulator session when its app connects to Metro), and on
   Android after a failed first bundle load. It reloads JavaScript and never
   restarts the app. An iOS app whose first bundle failed never connects to
   Metro, so reload cannot reach it and says to use the device's own Reload
-  control. For a physical device that reached Metro, use agent-device metro
-  reload with the reported port. The detected iOS Local Network first-load
+  control. With no owned launch recorded, reload goes through this workspace's
+  Metro to the apps connected to it, so an app that never connected is not
+  reached. The detected iOS Local Network first-load
   remedy uses UI automation instead because that app never established a Metro
   connection.
 - A successful stim reload confirms that the request was sent, not that new
@@ -482,12 +484,14 @@ 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
+After a termination request, cleanup waits for a child to close, then for its
+process group to exit: each wait is 5 seconds times the host's load per CPU,
+from 5 to 15 seconds. 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.
+A probe's time limit counts only the probe itself; PowerShell's startup and exit each have their own 30 second limit.
 
 requestMachineAccess({ ticket?, signal? }) requests build and device-host access
 from configured remote machines without granting capabilities or repairing project
@@ -642,9 +646,10 @@ 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
+the live iOS/Android app (owned, on a physical device or in an EAS Simulator
+session) or reloads the owned Chrome page. It returns the flat
+stim reload --json facts: platform, deviceId, deviceName, appId (null for an
+app Stim did not launch), 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
@@ -802,8 +807,10 @@ warns when gh is unavailable.
 
 status's remoteDevices lists each environment's recorded EAS Simulator
 session. The session is billable while it runs, and it makes the environment
-live. status reads only local records; it does not ask EAS whether the session
-is still running.
+live. EAS stops it by itself after remote.easMaxDurationMinutes (default 30).
+status reads only local records; it does not ask EAS whether the session is
+still running, so a session EAS already stopped stays listed until the next
+run replaces it or stop clears it.
 
   remoteDevices   [{ platform, backend, sessionId, state, startedAt,
                   webPreviewUrl }], empty when the workspace has none
@@ -1131,10 +1138,15 @@ leased until <time>" for each one.`,
 
   platform        "ios" | "android" | "web"
   deviceId        the exact owned simulator UDID or emulator serial targeted;
-                  for web, the owned Chrome's DevTools endpoint
-  deviceName      the owned simulator or AVD name; for web, the Chrome version
+                  for web, the owned Chrome's DevTools endpoint; metro:<port>
+                  when the apps were reached through Metro alone
+  deviceName      the owned simulator or AVD name; for web, the Chrome version;
+                  "EAS Simulator session <id>" or "devices connected to
+                  Metro" when reached through Metro alone
   appId           the live bundle id or Android package; for web, the URL the
-                  owned page was on when Stim sent the reload
+                  owned page was on when Stim sent the reload; null when no
+                  launch is recorded (a physical device or EAS Simulator
+                  session) and Stim reloaded the apps connected to Metro
   metroPort       the workspace's verified Metro port; for web, the reserved
                   Metro port or null
   strategy        how the reload was addressed.
@@ -1226,10 +1238,11 @@ leased until <time>" for each one.`,
                   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
+                  "missing". projectNode is { pin, spec, bin, version, match } 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
+                  pins Node (bin, version and match are null when no install
+                  fits the pin; match is "exact", or "major" for the newest
+                  install of the pinned major not older than the pin), else null
   remoteMachines  one { machine, state, dnsName?, deviceId?, requestedAt?,
                   expiresAt?, offloadable?, reasons?, problems?, capacity?, host? } per
                   remote.machines entry, for its build approval; state is "approved", "pending", "not-asked",
@@ -1481,7 +1494,8 @@ RULES
                   buildLock, buildSlot, deviceLease, easSession, worktree,
                   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).
+                  entry gc checked again or could not delete), trash (the
+                  same, labelled with $STIM_HOME/trash).
                   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
@@ -1706,10 +1720,23 @@ RULES
                               kind is stim (stim-claim-*, stim-host-*,
                               stim-fakehome-*, stim-hosted-macos-*,
                               stim-server-*, stim-ws-* directories), xctrace
-                              (instruments*.ktrace) or jest (Jest's
+                              (instruments*.ktrace), swiftpm
+                              (TemporaryDirectory.* directories) 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
+    trash                   { root, entries: [{ path, worktree, removedAt,
+                              bytes, willDelete, kept }] } | null  ignored
+                              directories worktree remove moved out of a
+                              worktree into $STIM_HOME/trash before git
+                              removed it. bytes is null while a removal is
+                              deleting the entry. kept names the live or
+                              unresolved ownership claim, the missing or
+                              invalid trash.json, or the worktree that
+                              still exists, that keeps a directory;
+                              --delete deletes the rest, only remove-*
+                              entries with a valid trash.json. null when the
+                              trash is empty or under any --cache scope
     caches                  { name, dir, source, bytes, note, willEmpty,
                               emptySkipped, scopedEmpty }  alive, not
                               garbage; willEmpty marks the ones --delete
@@ -2291,7 +2318,9 @@ RULES
                  existed count their device time in prepare and install
 
   Only runs that record a last build are listed: a run that stops before
-  looking up a build, such as a bad flag, is not. Estimates (expectedMs) come from run statistics, not builds.
+  looking up a build, such as a bad flag, is not. A run that builds or reuses
+  an app and then fails at the device, install or launch step is listed as
+  failed with its error code. Estimates (expectedMs) come from run statistics, not builds.
 
   done and total are counts, not a completion fraction: a target or task
   can take a second or ten minutes, and cached work finishes instantly.
@@ -2682,7 +2711,11 @@ HOSTED IOS METRO
   ios --remote <machine> keeps Metro local and needs no start --remote.
   The supervisor watches private gateway requests in workspace state, binds
   only this machine's Tailscale address and accepts only the pinned hosting peer
-  with a per-session secret. The host's bridge is loopback-only. Port and secret
+  with a per-session secret. The host's bridge is loopback-only. For an Expo
+  dev client it listens on this machine's Metro port, which the dev server
+  writes into the manifest. ios --remote starts Metro on a port free on both
+  Macs; a running Metro or a pin on a port the host uses refuses the run before
+  the build. Port and secret
   stay in 0600 workspace state and never appear in status, JSON or logs.
   metro.tunnel and metro.publicUrl are ignored. Supervisor restart recreates
   the recorded gateway; stop or a stopped hosted session closes it. A recorded
@@ -2770,7 +2803,9 @@ REMOTE DEVICE BACKENDS
   are Apple silicon. The cache key ends in that architecture.
 
   The EAS backend needs eas-cli 21.6.0 or later and an account with EAS
-  Simulator access. An EAS session is billable. Stim prepares the app before
+  Simulator access. An EAS session is billable; Stim has EAS stop each session
+  it creates after remote.easMaxDurationMinutes (default 30), and a later run
+  replaces a session that expired. Stim prepares the app before
   it creates or reconnects the session, so a failed build starts no session
   and the install follows the connection directly. EAS does not inherit the
   proxy credentials. Always tear the session down: \`stop\`,
@@ -2823,9 +2858,13 @@ WHAT THE SUPERVISOR IS
 
   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.
+  on PATH when an nvm, fnm, Volta, asdf, mise or linked Homebrew
+  node/node@NN install satisfies the pin and the node already on PATH does
+  not; the metro log then records a project_node event naming it. When no
+  install has the version the pin names, the newest install of the pinned
+  major that is not older than the pin stands in, and a node on PATH of
+  that major and not older than the pin is kept. 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
@@ -3215,6 +3254,10 @@ serve bounded log queries.
   the safe direction: a client redbox that Fast Refresh already fixed keeps
   being reported until the next launch.
 
+  RUN FAILURES. A run that builds or reuses an app and then fails before the app
+  is running adds one build record with event run_failed, its code and the
+  phase it failed in, so \`status\` and \`logs --errors\` agree.
+
   OUTPUT. Every logs command, including --errors and --follow, shows full captured
   error, component and native stacks, with no frame or message-length limit.
   --errors shows the first 20 matching error records, plus stack context.
@@ -3552,6 +3595,10 @@ Branch on the code, never on the message.`,
   --system-image / --device-profile for Android when the offer names
   an unavailable choice. A session that exists stays recorded even if delivery
   fails: retry stim ios|android --remote <machine>, or run stim stop to reconcile it.
+  An Expo dev client whose running or pinned Metro port is in use on the host
+  refuses before the build: run stim stop, then stim ios --remote <machine>
+  without stim start, so Stim starts Metro on a port free on both Macs, or pin
+  one free on both Macs with metro.port or STIM_METRO_PORT.
   An unreachable stop keeps the placement; rerun stim stop when the host answers.
   To see why a host was slow or refused: stim logs --source placement (hosts checked and
   reason codes), stim logs --source build (remote_connect_failed, remote_request_failed),
@@ -3643,8 +3690,9 @@ Branch on the code, never on the message.`,
   \`pod install\` (iOS) or the gradle dependency sync (Android) failed. On iOS
   this runs only when Podfile.lock and Pods/Manifest.lock disagree, or Pods is
   absent -- which is exactly what a carried worktree produces.
-  WHICH POD COMMAND: when the project root has a Gemfile and a Gemfile.lock
-  that resolves cocoapods, pods go through bundler -- \`bundle check --dry-run\`,
+  WHICH POD COMMAND: Stim takes the nearest Gemfile from the directory pod
+  install runs in (ios/) up to the project root, as Bundler finds it. When its
+  Gemfile.lock resolves cocoapods, pods go through bundler -- \`bundle check --dry-run\`,
   then \`bundle install\` only when that reports missing gems, then \`bundle exec
   pod install\` -- so the CocoaPods the lockfile pins is the one that writes
   Podfile.lock. Everything else gets plain \`pod install\`: no Gemfile, a Gemfile
@@ -3743,8 +3791,13 @@ Branch on the code, never on the message.`,
   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
+  projects fit 51 and 48. \`stim android\` on
+  an emulator, local or --remote <backend>, refuses before it starts Metro
+  or prepares the emulator, even when a cached build would have installed.
+  That early refusal is skipped for a physical or hosted device, an EAS
+  profile and when build machines are paired; a build that still runs here
+  is refused before Gradle runs, so a cache hit there still installs.
+  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
@@ -3911,6 +3964,13 @@ 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.
 
+A fingerprint-mismatch reason means the worker fingerprints the synced
+checkout differently. It names the sources that differ and the files pod
+install or prebuild rewrote there. Stim already sends the gitignored files the
+fingerprint reads, such as .env.local. Make the named input agree on both Macs,
+for example by committing the lockfile pod install rewrote there; pairing does
+not change it.
+
 Run stim doctor --fix to ask for build access if not paired. Check
 stim settings get remote.machines. A person on the worker approves this machine
 by running the stim-server setup command doctor --fix printed, with its ticket
@@ -3954,6 +4014,11 @@ Rerun with --remote-build auto for normal placement and local fallback, or
   copying for the same reason. A copy without a claim would be invisible to a
   refresh starting after it, allowing the source dependencies to change while
   they are read.
+  A report command such as \`gc\` reports it when it cannot confirm that a child
+  it started has stopped, typically on a machine under heavy load. The child is
+  left untouched. The remedy tells you what to check and which command to run
+  again, and when the run held ownership claims it lists the exact \`rm\`
+  command for each retained claim.
   Warm also reports this code for EACCES, EPERM, EROFS and ENOENT while taking a claim.
   The message names the claim path and original filesystem error. Restore write
   access to the existing claim store, checking parent permissions, symlink
@@ -4279,7 +4344,8 @@ so a Debug run on one is wired to a LAN origin instead of localhost.`,
   and \`adb devices\`, then retry after any other run finishes. Keep the AVD and
   its process locks while its state is unverified.
   On iOS a slow first boot is waited out for up to ten minutes while the
-  simulator reports Booting or Booted but bootstatus has not completed.
+  simulator reports Booting or Booted but bootstatus has not completed, and
+  then until SpringBoard has finished starting, which \`simctl launch\` needs.
   Booted alone does not end that wait. The failure names the udid and the wait.
   After boot, a process-spawn probe must finish within 30 seconds before
   installation. If it fails, the refusal includes observed host memory pressure
@@ -4452,14 +4518,19 @@ so a Debug run on one is wired to a LAN origin instead of localhost.`,
   proxy is selected. They never select the backend.`
 		},
 		STIM_REMOTE_EAS_UNAVAILABLE: {
-			summary: "--remote eas needs eas-cli 21.6.0 or later",
+			summary: "--remote eas needs eas-cli 21.6.0 or later and an Expo app linked to an EAS project",
 			body: () => `STIM_REMOTE_EAS_UNAVAILABLE
   \`--remote eas\` requires eas-cli 21.6.0 or later, the first release with
   the \`eas simulator:*\` commands Stim runs. Stim reads \`eas --version\` and
   refuses before any build or session work when eas-cli is missing, older, or
   reports no version. Upgrade it (\`npm install --global eas-cli@latest\`, or
   the project's eas-cli dependency). Proxy environment variables do not change
-  this selection and are not passed to EAS.`
+  this selection and are not passed to EAS.
+  It is also the code when EAS reports that the Expo app has no EAS project
+  (no extra.eas.projectId), so no session was created. Link the app with
+  \`eas init --id <project-id> --non-interactive\` or create a project with
+  \`eas init --account <account-name> --non-interactive\`, then rerun. Rerunning
+  \`stim ios\` or \`stim android\` without the link fails the same way.`
 		},
 		STIM_REMOTE_PLATFORM_MISMATCH: {
 			summary: "the recorded remote session belongs to the other platform; stop, then rerun",
@@ -4543,12 +4614,17 @@ so a Debug run on one is wired to a LAN origin instead of localhost.`,
 			aliases: ["STIM_RELOAD_UNOWNED", "STIM_RELOAD_PROBE_FAILED"],
 			body: () => `STIM_RELOAD_STOPPED / STIM_RELOAD_UNOWNED / STIM_RELOAD_PROBE_FAILED
   The recorded app is gone, its exact device is not live and owned by this
-  workspace, or simctl/adb could not prove the process exists. For web,
+  workspace, or Metro has no peer for the app and simctl/adb could not prove the
+  process exists (a probe that times out alone does not stop the reload). For web,
   STOPPED means no owned Chrome is running (run stim web) and PROBE_FAILED
   that its identity could not be verified. A bare reload picks the Chrome page
-  only when no native launch is recorded. No launch or
-  device lifecycle action is taken; follow the printed platform-command or
-  process-probe remedy.`
+  only when no native launch is recorded. Stim records launches only on owned
+  local simulators and emulators. With none recorded, reload asks this
+  workspace's Metro for its connected apps, which reaches an app on a physical
+  device (--device) or an EAS Simulator session; STOPPED then means no app is
+  connected to that Metro, so launch it or, for an Android phone, restore its
+  adb reverse. No launch or device lifecycle action is taken; follow the
+  printed platform-command or process-probe remedy.`
 		},
 		STIM_RELOAD_FAILED: {
 			summary: "the reload failed; the remedy differs by shape -- read it before acting",
@@ -4699,6 +4775,13 @@ captured"  (in metro.ndjson, bare RN)
   config -- lands THERE, not in supervisor.log). \`stim logs --errors\` has
   the full records. Fix that and run \`start\` again.
 
+  A bind error on the reserved port ("listen EADDRINUSE ... :<port>") means
+  another process, usually another Stim home, took the port after Stim chose
+  it. \`start\` releases that reservation, reserves another free port and
+  starts again, up to 3 attempts, and says so. A pinned metro.port and
+  \`--remote\` starts are not retried. When all attempts fail, run \`start\`
+  again.
+
   "Cannot reuse or replace the recorded supervisor: ..."
   A live record has no verifiable OS process identity, or the workspace and
   registry records disagree. Nothing new was started; the old process is
@@ -5327,14 +5410,15 @@ hosting Mac keeps Metro local through a private bridge; see hosted-ios. Step 2 r
 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.
+simulators to volume zero through Xcode's devicectl once SpringBoard has
+finished starting, because SpringBoard resets the volume while it starts, 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
@@ -5342,16 +5426,25 @@ not part of the normal workflow. It is the explicit recovery path when Fast
 Refresh cannot clear the current screen, and on Android after a failed first
 bundle load. It reloads JavaScript and never restarts the app. Use \`stim
 reload ios\` or \`stim reload android\` to select a platform when both owned
-apps are live. For a physical device that reached Metro, use \`agent-device
-metro reload --metro-port <reported-port>\`. The detected iOS Local Network
+apps are live. With no owned launch recorded, it reloads the apps connected to
+this workspace's Metro, such as one on a physical device (--device); an
+Android phone needs its adb reverse. An app in an EAS Simulator session may not
+connect to Metro through the tunnel; then reload finds no app and the way to
+restart it is stim ios|android --remote eas.
+The detected iOS Local Network
 first-load remedy uses agent-device UI automation because no Metro peer exists
-yet. It never builds, installs, boots, or cold-launches. It acts only on a live
-app on this workspace's owned local simulator or emulator, and refuses release
-builds, stopped or unowned devices, a missing or foreign Metro, and an
-ambiguous no-platform request. Every reload goes over this workspace's Metro
+yet. It never builds, installs, boots, or cold-launches. It acts on a live app
+on this workspace's owned local simulator or emulator, or on the apps connected
+to this workspace's Metro, and refuses release builds, stopped or unowned
+devices, a missing or foreign Metro, and an ambiguous no-platform request. Every reload goes over this workspace's Metro
 websocket, on both platforms. It never reopens a development-client URL,
 because that restarts the app rather than reloading its JavaScript.
 
+Before sending, Stim checks that the app process exists. The iOS probe
+(\`simctl spawn launchctl list\`) waits 5 seconds, scaled up with host load to at
+most 30. When the device tool still does not answer, Stim sends the reload anyway;
+\`STIM_RELOAD_PROBE_FAILED\` is then reported only if Metro finds no peer for the app after the reload fails.
+
 An Android reload first lists \`adb reverse\` on each live owned emulator
 launched against this Metro and re-applies the Metro port's reverse where it is
 missing. adb ties a reverse to its transport, and a transport that drops and
@@ -5378,7 +5471,7 @@ dev menu.
 When Metro reports no peer for the app, Stim broadcasts a reload anyway before
 giving up, because matching is best-effort and an unmatched peer may still be
 this app. So verify the UI first: it may already have recovered. If it did not,
-retry: a client reconnects every 2 seconds, which is also this probe's timeout,
+retry: a client reconnects every 2 seconds, which is also the Metro probe's timeout,
 so a single miss can be a reconnect window rather than an app that never
 connected. If it stays unreachable on iOS, an error in the first bundle leaves
 the app without a packager connection at all, and no retry will make it a peer.
@@ -5902,7 +5995,7 @@ is on PATH, the slot is default, no --runtime, --system-image or
 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 machine has room, auto runs here and the
-session bills until stim stop. If any check fails, or the
+session bills until stim stop or remote.easMaxDurationMinutes. If any check fails, or the
 setting is off, auto runs here and may wait in the existing FIFO device
 slot queue; --no-wait and --wait 0 refuse with STIM_AT_CAPACITY. The placement
 line explains the decision, the skipped hosts and why EAS was not used
@@ -5952,6 +6045,12 @@ Stim builds or fetches before reserving, records the session immediately, then
 uploads the app on every run. React Native and Expo Debug keep Metro here; the supervisor owns a
 private gateway bound to this machine's Tailscale address, pinned to the host peer
 and protected by a per-session secret. The host exposes only a loopback bridge.
+For an Expo dev client the bridge listens on this machine's Metro port, because
+the dev server writes that port into the manifest's bundle URL. When this run
+starts Metro, it asks the host and picks a port free on both Macs, moving the
+recorded port if the host uses it. A running Metro or a metro.port pin on a port
+the host uses refuses before the build: run stim stop, then stim ios --remote
+<machine> without stim start, or pin a port free on both Macs.
 No start --remote is needed; metro.tunnel and metro.publicUrl are ignored.
 Debug requires a running supervisor with private gateway support before reserving
 a simulator. --no-metro-check refuses with STIM_BAD_ARG for hosted Debug runs.
@@ -7037,8 +7136,11 @@ WHAT MAKES THE CACHE ACTUALLY HIT: .FINGERPRINTIGNORE
   BUILD is what breaks that, and it fails silently -- a cache that never hits
   looks exactly like a cache that is not there.
 
-  Stim ignores two paths a fresh checkout never has and no native build reads:
-  android/local.properties and android/.idea. A project does not repeat those.
+  Stim ignores paths a fresh checkout never has and no native Debug build
+  reads: android/local.properties, android/.idea, *.xcodeproj/xcuserdata, and,
+  while a .gitignore pattern matches them (even when committed), the
+  \`react-native bundle\` output ios/main.jsbundle and ios/assets. A project
+  does not repeat those.
   Everything else is the project's call, including a lockfile whose checksums
   embed machine paths -- ignoring a path any project might read turns a slow
   build into a wrong one.
@@ -7516,7 +7618,10 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
 
   Warm copies directly into the destination, without intermediate staging.
   Keep the source checkout and the linked worktree on the same volume to
-  retain copy-on-write cloning where supported. Cross-volume copies require
+  retain copy-on-write cloning where supported. On macOS with the Command Line
+  Tools, an ignored directory on the same APFS volume, such as node_modules or
+  ios/Pods, is cloned in one step, so a large one takes seconds; elsewhere
+  warm clones or copies file by file. Cross-volume copies require
   full file data; doctor reports that cost. STIM_TMPDIR and machine tempDir do
   not affect warming.
 
@@ -8057,6 +8162,8 @@ HOST MEMORY PRESSURE AND STALLED SIMULATORS
     Watchman                       stim gc --delete --cache watchman
     Gradle or Kotlin daemon        stim gc --delete --cache gradle-daemons
   Any other process is named with its size only; ask before quitting it.
+  Boot does not wait for this read: the pressure message prints at once and the
+  named processes follow on a second memory line when top finishes.
   Doctor skips this check when STIM_HOME is set: processes are machine-global.
 
   If pressure is elevated, free host memory before retrying. Use \`stim stop\`
@@ -8167,8 +8274,8 @@ DISK PRESSURE LEVELS
        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)
+    5. Stim temp directories, xctrace recordings and SwiftPM temp directories
+       in TMPDIR unmodified for 24 hours, with gc --delete's checks (see stim guide cleanup gc)
   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
@@ -8481,6 +8588,24 @@ LINKED WORKTREES
   has locked (unlock it first; --force does not override) and, without
   --force, uncommitted or unpushed work and initialized submodules. It then
   reclaims any owned resources it finds and removes the linked checkout.
+  Before git removes it, the command renames the worktree's ignored
+  directories (node_modules, ios/Pods, build outputs) into
+  $STIM_HOME/trash/<entry>, so git removes a light tree, and a detached,
+  low-priority rm deletes the entry after the command returns. Disk is freed
+  when that rm finishes. Through the programmatic API (createStim), the entry
+  is deleted before the call resolves. A directory that does not rename stays
+  for git to delete as before; on Windows, or when $STIM_HOME is on another
+  volume, nothing is renamed. When git refuses the removal, the directories
+  are moved back. Each entry holds an ownership claim while the command or its
+  rm uses it; gc reports every directory under trash with its size ("deleting"
+  while a removal holds it) and, for an entry Stim wrote, its source worktree.
+  gc --delete deletes only a remove-* entry with a valid trash.json whose
+  claim is free and whose worktree path is gone, which finishes a removal that
+  was interrupted, and keeps any other directory. An entry whose worktree path
+  still exists, as after a removal killed between the rename and git, stays
+  with the reason; if that worktree is the one the entry came from, run
+  \`stim worktree remove\` on it to finish the removal.
+  gc never moves the directories back.
   When git still refuses the removal, the kept ownership record no longer
   names the devices that were parked or deleted. A workspace that is in use
   (see IN USE below) keeps its directory, devices and registry entry, and the
@@ -8687,13 +8812,19 @@ TMPDIR LEFTOVERS
   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
+  (instruments*.ktrace), SwiftPM temp directories (TemporaryDirectory.* with a
+  six-character suffix, left by swift and xcodebuild) and Jest's
+  jest_<uid in base 36> cache. \`gc --delete\` checks them again and deletes a
+  Stim temp directory, recording or SwiftPM temp directory 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
+  keeps a recording or SwiftPM temp directory that cannot be read, every
+  recording while an xctrace or Instruments process runs, and every SwiftPM
+  temp directory while a swift or xcodebuild process runs, or when the process
+  list cannot be read. Stim's own SwiftPM macOS builds run swift with the
+  ambient TMPDIR, because SwiftPM keeps the locks for its shared caches there,
+  so their temp directories land here too. 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
@@ -8794,6 +8925,9 @@ DEVICE LEASES
   its holder and expiry, including holders no config knows. \`stop\` and
   \`worktree remove\` release the leases of the workspace they act on, and
   nothing else deletes a lease file: never remove another workspace's.
+  They also remove the \`adb reverse\` that an \`android --device\` run added
+  for this workspace's Metro port on that phone, using the serial and port the
+  run recorded in its workspace state; any other reverse on the phone stays.
 
 A device leaks when a project is abandoned WITHOUT either delete path -- the
 sim survives with nothing pointing at it. \`stim gc\` (no flag, writes
@@ -9503,6 +9637,17 @@ ${ANDROID_AVD_CONFIG_HELP.map((line) => `                          ${line}`).joi
                         project scope; a committed value opts in everyone who
                         runs the app. Only the user enables it. See lifecycle
                         hosted-ios.
+  remote.easMaxDurationMinutes
+                        Minutes after which EAS stops each EAS Simulator session
+                        Stim creates (--remote eas or the easFallback), so a
+                        session nobody ended stops billing. A positive integer;
+                        default 30. Machine scope only. stop and gc --delete
+                        still end a session sooner; a run after the cap expires
+                        replaces the stopped session. Stim passes it to eas sim
+                        as --max-duration-minutes. EAS rejects a value above the
+                        account plan's session limit, so raise it only as far
+                        as the plan allows. A run reuses a live session without
+                        checking its remaining time.
   metro.tunnel          selects how a remote device reaches this workspace's
                         Metro after remote intent exists. Plain \`start\` stays
                         local. For Expo and bare React Native, "auto" (default)
@@ -10044,6 +10189,11 @@ and records buildMachine with builtOn absent. Build failures retain the selected
 value; builtOn is here or the configured machine entry when compilation ran.
 Prebuild and pod install still run on this machine before a named offload. A refusal
 starts no local xcodebuild, Gradle or SwiftPM compile.
+A React Native offload sends the tracked and untracked files, and the gitignored
+files the native fingerprint hashes or the Expo config reads, such as .env.local
+and other Expo .env files, secrets included. Nothing under node_modules and no
+build output the fingerprint ignores is sent. A fingerprint-mismatch refusal
+names the sources that differ and the files pod install or prebuild rewrote there.
 Run stim doctor --fix to ask for build access if not paired. A person on the
 worker approves it by running the stim-server setup command doctor printed, with
 its ticket and expiry. Check stim settings get remote.machines,
@@ -10069,11 +10219,31 @@ emulator debug build or a stim macos SwiftPM Debug build compiles:
   off    here when local remains enabled in the automatic build pool
 
 For React Native and Expo, among machines that can take a new build, a matching dependency installation
-ranks before load. The worker checks the requested project, lockfile and install
-arguments, and verifies that its modules and install marker remain present.
+ranks before load. The worker checks the requested project, lockfile, install
+arguments and the major of the Node the app pins, and verifies that its modules
+and install marker remain present.
 Older workers' dependency hints and mere checkout or build-folder presence do
 not influence this ranking. Exact completed-artifact hits still come first.
 
+The worker installs dependencies with the lockfile nearest the app: the first
+pnpm-lock.yaml, yarn.lock or package-lock.json in its directory or above it in
+the checkout, in the directory that holds it. An app with its own lockfile
+inside a larger repository installs its own dependencies there. In a pnpm
+workspace the worker installs every workspace package, as \`pnpm install\` does
+locally, because a native build can run a script of a package the app does not
+depend on.
+
+The worker runs the dependency install, prebuild, pods and xcodebuild with the
+Node the app pins, in its directory or the nearest one above it in the
+checkout, first on PATH, chosen as for Metro (see \`stim guide metro\`). On
+every offloaded iOS build, pinned or not, it writes the first node on its PATH
+(the pinned Node when it put one first) as NODE_BINARY in the iOS project's
+.xcode.env.local, replacing any export NODE_BINARY= line already there. A warm
+Gradle daemon keeps running React Native's node steps on the Node it started
+with. When no installed Node fits the pin, the steps run on the worker's node
+and a deps-failed or prebuild-failed reason names the pin and that Node's
+version. A change of the pinned Node's major reinstalls the dependencies.
+
 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.
@@ -10086,7 +10256,8 @@ STIM_REMOTE_BUILD_MODE overrides it for one command. Device, Release and
 and iOS/Android runs with the build cache off, always build here. Hosted iOS
 Debug builds can use a separate --remote-build, targeting the hosting Mac's
 architecture and runtime.
-macOS uses matching Xcode and macOS SDK, with a per-client SwiftPM dependency
+macOS uses matching Xcode and macOS SDK (not when --remote-build and --remote name the
+same Mac; see stim guide macos), with a per-client SwiftPM dependency
 cache on the worker. It skips JavaScript dependencies, prebuild and pods; see
 stim guide macos. Completed caching requires macos.artifactInputs and a locally
 verified compile; remote output is not published under an unverified client key.
@@ -10115,9 +10286,10 @@ 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 machines then run that version through
+the app's Gemfile.lock, in ios/ or the project root, pins CocoaPods: both machines then run that version through
 bundler, so the machine needs only Bundler on its stim-server PATH and
-installs the pinned gems itself on the first build. The comparison selects
+installs the pinned gems itself on the first build. This Mac's side of the
+comparison runs \`pod --version\` in the directory pod install runs in. The comparison selects
 the app's .ruby-version when installed, otherwise rvm's or rbenv's default Ruby, and only when neither exists the GEM_HOME, GEM_PATH and Ruby-related PATH entries of the machine's login shell (read once with $SHELL -lic), unless the caller already sets GEM_HOME, with pod install's UTF-8 locale defaults. pod install, including the Bundler run, uses the same environment.
 For Android its CPU may differ, since the APK's ABIs come from the NDK, so an
 x86_64 Linux or Windows machine running stim-server can build for an Apple silicon Mac. Its JDK major
@@ -10870,7 +11042,8 @@ build pool. remote.buildPoolDisabled excludes members from automatic placement,
 including its local fallback. Explicit local or named placement bypasses membership.
 Configure remote.machines
 and approve build access as described in stim guide settings. The worker needs
-matching Stim, CPU architecture, Xcode and macOS SDK, plus network access to
+matching Stim, CPU architecture, Xcode and macOS SDK (except for an app built and run on
+the same Mac, below), plus network access to
 fetch package dependencies the first time. It keeps SwiftPM dependencies in a
 per-client cache and incremental outputs per repository. It runs fixed swift
 build commands without JavaScript installs, prebuild or pods. It receives only
@@ -10878,6 +11051,12 @@ the files git lists (tracked and untracked, not ignored). Resource and catalog
 sources must be among those files. The client sends resolved sources relative
 to the repository root; the worker resolves them inside its checkout.
 
+With --remote <machine> and --remote-build naming the same machine (the same
+paired node), the app is built and run there, so this Mac's Xcode, macOS SDK and
+CPU architecture do not have to match: the worker needs the same Stim build and
+its own Xcode and macOS SDK. This Mac's cache is skipped and the worker's cache
+identity comes from the worker's toolchain. Any other combination keeps the match.
+
 The client validates the development plist and resource entries before asking a machine. It verifies
 the returned archive's sha256, bundle identifier, executable, declared resources
 and ad hoc signature