stim 1.2.0 → 1.3.1

package/dist/{guide-BS2Xc24o.mjs → guide-D95E0u3i.mjs}

@@ -1,4 +1,4 @@
-import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-DwU1_U_q.mjs";
+import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-DEJf6_kJ.mjs";
 import chalk from "chalk";
 //#endregion
 //#region src/guide/index.ts
@@ -31,6 +31,15 @@ branch that is not the default one -- only once the repository has at least
 one linked worktree, so read it from inside the worktree. A single-checkout
 session is never told that its own branch is a problem.
 
+MULTIPLE DEVICES
+
+Use ios/android --slot <name> to retain multiple devices in one workspace,
+including several of the same model. Reuse the same slot name on subsequent
+runs. Read guide lifecycle options for the complete slot workflow. Use the
+reported device ID for UI interaction. All slots share Metro; reload can reach
+multiple devices, and a shared bundle request does not prove a slot launched.
+Use stop --slot <name> for one slot, or plain stop for the whole workspace.
+
 NORMAL WORKFLOW
 
 Work in the current checkout by default. When the task needs another branch or
@@ -53,6 +62,8 @@ warm checks for existing entries before copying, not during the copy. Do not
 edit files, install dependencies, or run another warm in that worktree until
 it finishes; concurrent files can be overwritten or removed.
 If warm fails or reports incomplete, resolve the reported failure first.
+A warm that cannot record its ownership claim refuses before copying. Follow
+the printed remedy and keep concurrent runs on the same STIM_HOME.
 
 Before native worktree work, run doctor for the platform in scope. It checks
 the source checkout from a linked worktree. Fix relevant findings and inspect the
@@ -66,9 +77,17 @@ For iOS Debug architecture findings, review the project's overrides and imported
 Podfile helpers using guide lifecycle options. Doctor --fix does not change them.
 For parallel iOS work, review the recommended optional SimSlim setup in
 stim guide lifecycle simslim. If simulator process startup times out, check
-host memory pressure and free memory before retrying; do not restart other
+host memory pressure and free memory before retrying. Boot progress reports
+current and highest observed pressure; a timeout does not establish OOM.
+Avoid repeated reboots under unchanged pressure; do not restart other
 workspaces' devices or close their apps without asking. That guide covers
 the recovery steps and profile tradeoffs.
+An Android boot timeout under observed elevated memory pressure gets one
+extra wait while the emulator process this run started is alive. It never
+launches a second emulator. For a timeout, read guide errors STIM_NO_DEVICE
+and free memory by stopping only unneeded devices in workspaces you own;
+ask before closing other apps or devices. Device count alone is not evidence
+of memory pressure.
 For a linked native library carrying Git metadata, add the printed .git entries to
 .fingerprintignore only when the native build does not read Git state.
 
@@ -88,6 +107,16 @@ them. It preserves source, custom launcher settings, and the shared ccache.
   stim start
   stim ios                             # or: stim android
 
+For a project using EAS development builds, read stim guide lifecycle eas to
+select a profile from eas.json for the requested target, then run
+stim ios --eas-profile <name> or stim android --eas-profile <name>.
+Ask the user if the profile choice is ambiguous. A miss stops with
+STIM_EAS_BUILD_MISSING and an EAS build command. Run that command only when the
+session authorizes the potentially billable build, then retry Stim. The
+presence of eas.json does not select EAS or authorize building.
+Physical --device targets are supported. Follow EAS device-registration and
+rebuild remedies only when the session authorizes those account changes.
+
 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
 tool call timed out, retry the same command and follow its printed remedy if
@@ -159,8 +188,9 @@ RULES DURING THE LOOP
 - A clean logs --errors check requires exit code 0 AND no matching errors in
   captured logs. Exit code 0 alone means the query succeeded, even when errors
   were printed. Human output shows "No matching log records" on stderr for
-  zero matches; JSON mode prints zero bytes. This does not prove launch or log
-  capture succeeded. Do not read the NDJSON files directly.
+  zero matches; JSON mode prints zero bytes. A workspace with no captured
+  timeline refuses with STIM_NO_PROJECT and, in a monorepo, names the nearest
+  registered descendant app with logs. Do not read the NDJSON files directly.
 - Use stim status when resuming a workspace or recovering missing device,
   port, server, or build facts. A normal start and platform run already print
   them. Use stim doctor when a build is unexpectedly slow or the environment
@@ -175,6 +205,8 @@ the stim-<label> (<model> <runtime>) name. Never point Stim at a user-created
 emulator or simulator.
 
 worktree remove parks the workspace's simulator or emulator for later adoption.
+Before owned-device teardown, Stim best-effort closes local agent-device sessions
+on that exact device; failures warn and teardown continues (guide cleanup).
 A parked device is Stim-owned: never delete one by hand. gc --delete clears verified
 entries and keeps failures; see guide lifecycle pool. First launch on a
 physical iPhone can need the one-time taps named by the remedy.
@@ -277,7 +309,13 @@ FULL TOPIC LIST
 	},
 	facts: {
 		summary: "The --json payloads: `start`, `ios`, `android`, `reload`, `stop`, `status`, `doctor`, `device lock`/`unlock`, and the error contract",
-		preamble: () => `FACTS CONTRACT
+		preamble: () => `SLOTS
+Named ios/android runs add slot to their JSON facts. Default-run fields remain
+compatible. status adds a slots array per environment with each named slot's
+ios/android device facts; top-level ios/android still describe default.
+Named collector, lease-holder, and launch keys use platform:slot internally.
+
+FACTS CONTRACT
 
 \`start\`, \`ios\`, \`android\`, \`reload\`, \`stop\`, \`status\`, \`stats\`, \`doctor\`,
 and \`device lock\`/\`device unlock\` each print exactly ONE line of JSON on
@@ -341,6 +379,11 @@ line by design (see \`guide logs\`), not this single-payload contract.`,
                   absent for automatic selection; not the app URL scheme
   cacheKey        the shared-build-cache key derived from it (the
                   configuration is part of it: -release-sim vs -debug-sim)
+  With --eas-profile, fingerprint is computed by EAS CLI using the selected
+  profile/environment, and cacheKey identifies the EAS project and build ID
+  separately from local native builds. cacheHit is "remote" for the EAS
+  source, including when EAS CLI reuses its own downloaded artifact cache.
+
   cacheHit        WHICH LEVEL answered, not a boolean:
                     "local"   this machine's shared cache (free, instant)
                     "remote"  the project's own Expo buildCacheProvider (a
@@ -866,15 +909,23 @@ discovered, not enumerated.
 
 EXIT 0 MEANS THE QUERY SUCCEEDED, whether or not records matched. A clean
 \`stim logs --errors\` check requires exit code 0 AND no matching errors in
-captured logs. An empty result does not prove launch or log capture succeeded;
-a workspace with no log directory also returns an empty result.
+captured logs. A workspace that has never produced a timeline refuses with
+STIM_NO_PROJECT instead of passing with an empty result. In a monorepo the
+refusal names the nearest registered descendant app with logs, when there is one.
 
-For zero matches: STDOUT IS EMPTY, exit code 0, and
+Once a timeline file exists, zero matches after filtering means STDOUT IS EMPTY,
+exit code 0, and
 one dim note on STDERR reading \`No matching log records in <logs dir>\`
 (human mode only -- \`--json\` prints nothing at all, on either stream).
 The only exit-1 paths are a malformed query and no project.
 
+Device collectors and build records carry their named slot. Use --slot phone
+for that slot's timeline; its launch marker cannot hide a sibling's errors.
+Untagged legacy records belong to default. Metro/client records are shared and
+usually untagged: use an unfiltered workspace query to inspect those errors.
+
 FLAGS
+  --slot <name>   only this slot's records (default includes untagged records)
   --source <s...>  metro, client, device, build (one or more), or all. An
                    unknown value is REJECTED rather than quietly matching
                    nothing.
@@ -1138,6 +1189,24 @@ WHAT WRITES WHAT
 Every refusal from \`ios\` / \`android\` carries a stable CODE. Branch on the
 code, never on the message.`,
 		sections: {
+			STIM_EAS_BUILD_MISSING: {
+				summary: "no completed EAS development build matches; build only with session authorization",
+				body: () => `STIM_EAS_BUILD_MISSING
+  No compatible build matches the selected EAS project, profile, platform and
+  native fingerprint. No device was acquired and no local or cloud build was
+  started. The remedy prints the exact npx eas-cli build command. Check session
+  authorization for its potential cost before running it, then retry Stim.
+  See stim guide lifecycle eas.`
+			},
+			STIM_EAS_UNAVAILABLE: {
+				summary: "EAS lookup/download failed, or another run holds the artifact claim",
+				body: () => `STIM_EAS_UNAVAILABLE
+  EAS CLI is unavailable, a profile/fingerprint/list/download operation failed,
+  the response could not be validated, or another run holds the artifact claim.
+  Follow the printed remedy: inspect the named EAS command or retry once the
+  holder finishes. This is not proof that a build is missing. No native build
+  is started. See stim guide lifecycle eas.`
+			},
 			STIM_WORKSPACE_STATE: {
 				summary: "$STIM_HOME/workspaces could not be prepared, or the digest directory belongs to another project",
 				aliases: ["STIM_WORKSPACE_COLLISION"],
@@ -1348,14 +1417,13 @@ code, never on the message.`,
   \`worktree warm\` reports it for the repository-wide warm claim under
   ~/.stim/warm-locks on both paths, including a \`--refresh\` that spawned its
   install and was killed before recording which process: nothing was refreshed
-  and nothing was copied. One case is NOT this code for a plain warm: a
-  STIM_HOME (or a warm-locks path under it) that is a file rather than a
-  directory. No claim can be stored there at all, which is a filesystem state
-  that predates claims, so plain \`warm\` degrades to the unsynchronised copy it
-  performed before them and \`--refresh\` still refuses.`
+  and nothing was copied. A STIM_HOME or warm-locks ancestor that is a file
+  also refuses. The message names that blocking path and prints a shell-quoted
+  move-aside command. Inspect it first: the file may contain unrelated data.
+  An existing backup prompts before overwriting; preserve both files.`
 			},
 			STIM_CLAIM_UNAVAILABLE: {
-				summary: "this process has no recordable identity, so no build lock or build slot can be taken at all",
+				summary: "a process identity or warm claim store is unavailable, so the protected operation refuses",
 				body: () => `STIM_CLAIM_UNAVAILABLE
   Every ownership claim records the holder's process identity, captured through
   the \`unique-pid\` native module. This code is that capture failing: no
@@ -1367,16 +1435,15 @@ code, never on the message.`,
   the same fingerprint while each believed it was alone. Reinstall Stim so the
   module for this platform is present, then run the command again. Nothing was
   built, installed or removed.
-  \`worktree warm --refresh\` refuses for the same reason, because it writes to
-  the source checkout. Plain \`worktree warm\` does NOT: it prints one dim
-  \`lock        unavailable (...)\` line and copies unsynchronised. A copy only
-  reads, so running it with no claim is what it did before the lock existed,
-  while refusing it would break a warm that works today -- an unwritable
-  STIM_HOME included.
-  It still reads the claim set first, which takes no claim: a live \`--refresh\`
-  claim, or a claim it cannot resolve, makes even the unsynchronised copy
-  refuse, and the line names what it found. Only a repository nothing is
-  warming is copied without a claim.`
+  Both plain \`worktree warm\` and \`worktree warm --refresh\` refuse before
+  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.
+  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
+  targets, mount access and sandbox rules, then retry. Do not switch STIM_HOME to evade a claim:
+  concurrent runs must coordinate through the same store.`
 			},
 			STIM_INSTALL_FAILED: {
 				summary: "simctl, adb, or devicectl refused the artifact; the one signer-conflict retry",
@@ -1464,7 +1531,10 @@ spending a build or a bundle, that the check can succeed.`,
       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.`
+      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.`
 			},
 			STIM_NO_SIGNING_IDENTITY: {
 				summary: "no single keychain identity resolves; ios.signingIdentitySha1 for two certificates",
@@ -1642,8 +1712,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 still reports Booting -- a long silent wait on a loaded machine
-  is patience, not a hang. The failure names the udid and the wait.
+  simulator reports Booting or Booted but bootstatus has not completed.
+  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
   when available. Free memory before retrying under pressure; see
@@ -1658,6 +1728,20 @@ so a Debug run on one is wired to a LAN origin instead of localhost.`,
   normally live under ~/.android/avd, and a booted AVD can use several GB. A
   boot whose emulator process exited is also reported at once rather than after
   the full cold-boot timeout.
+  Before a local Android emulator boot, a memory phase line reports observed
+  warning or critical macOS host memory pressure. If the initial boot wait
+  times out under that pressure and the process this run started is still
+  alive, Stim retries the WAIT once for up to 240 seconds more on the same
+  serial; it never starts a second emulator. New-device preparation normally
+  waits 120 seconds first; the later boot check waits 240 seconds. There is
+  no extra wait for normal or unavailable pressure, a process that exited,
+  or a process whose liveness this run cannot check. adb probes are bounded;
+  final diagnostic queries share a separate budget of up to five seconds.
+  A timeout remedy reports observed pressure and the running owned-device
+  count when available. Device count alone does not establish memory pressure
+  or trigger the extra wait. Stop an unneeded device with \`stim stop\` only
+  in a workspace you own, then retry \`stim android\`; ask before closing
+  other apps or devices. Specific emulator log errors retain their remedies.
 
 "this project's sim is X, but --device-type asked for Y"
   The project already owns a simulator of a different model, and Stim will
@@ -1925,7 +2009,9 @@ captured"  (in metro.ndjson, bare RN)
   with no package.json above it, or one whose nearest package.json does not
   parse or depends on neither react-native nor expo, so the directory is not
   an app (the refusal names that package.json and says which of the two it
-  is; \`doctor\` reports the same directory as a finding), an
+  is; \`doctor\` reports the same directory as a finding), a \`logs\` query in
+  a workspace that has never produced a log timeline (the refusal names the
+  nearest registered descendant app with logs when one exists), an
   android/app/build.gradle that declares product flavors with
   no variant selected (the refusal names the debug variants), or a
   \`--device-type\`, \`--runtime\` or \`--system-image\` name that is BLANK or
@@ -2083,24 +2169,14 @@ not on any remote"  (worktree remove)
   which is usually the repository root, so every app of it reads the same one.`
 			},
 			warm: {
-				summary: "two warm refusals whose text is incomplete, known and not fixed",
-				body: () => `"Could not warm this worktree: EACCES: permission denied, mkdir
-'<home>/warm-locks/<name>.lock'"  (worktree warm --refresh)
-  A STIM_HOME that \`--refresh\` cannot write. The refusal itself is right -- it
-  writes to the source checkout, so it will not run without a claim -- but it
-  carries no \`failed: <CODE>\` line, because EACCES is not a Stim code, and no
-  fix line. Make STIM_HOME writable, or set STIM_HOME to somewhere writable,
-  then run it again. A plain warm degrades in this state rather than refusing.
-
-"... the claim path is a file, not a claim directory", with a \`rm -rf\` that
-changes nothing  (worktree warm --refresh)
-  When \`$STIM_HOME/warm-locks\` or STIM_HOME itself is a regular FILE, the
-  refusal names \`warm-locks/<name>.lock\` -- a path that cannot exist under a
-  file -- so running the printed removal does nothing and the next run refuses
-  identically. Remove the file that is in the way and run it again. A plain
-  warm copies unsynchronised in this state.
-
-  Both are documented rather than fixed: appandflow/stim#696.`
+				summary: "worktree warm claim storage refusals and recovery",
+				body: () => `Both plain warm and --refresh require an ownership claim.
+  Permission-denied or read-only claim storage reports STIM_CLAIM_UNAVAILABLE
+  and names the path. Restore access to the existing claim store and retry.
+  A non-directory claim ancestor reports STIM_CLAIM_REFUSED and names the
+  blocking file. Inspect it and use the printed move-aside command to preserve
+  its contents before retrying. See guide errors STIM_CLAIM_UNAVAILABLE and
+  guide errors STIM_CLAIM_REFUSED for the recovery details.`
 			},
 			carry: {
 				summary: "worktree warm copy results, lockfile mismatches, and remedies",
@@ -2281,6 +2357,7 @@ a seed belongs to this workflow.
   #    For a clean check, require exit 0 AND no matching errors.
   #    Human mode prints "No matching log records" on stderr for zero matches.
   #    Exit 0 alone means the query succeeded, even when it printed errors.
+  #    A workspace with no captured timeline refuses with STIM_NO_PROJECT.
   stim logs --errors
 
   # 5. Edit the JS. Fast Refresh applies it; no Stim command is involved.
@@ -2376,6 +2453,12 @@ ANDROID EMULATOR RESTARTS
   Rerun \`stim android\` with the same build options in that workspace to restore Metro
   forwarding, then reopen agent-device on the serial that run reports.
   Other workspaces' simulators and automation sessions remain theirs.
+  A local emulator boot reports observed warning or critical macOS memory
+  pressure before starting. A timeout under elevated pressure gets one
+  additional wait of up to 240 seconds only while the process this run
+  started is alive. Stim keeps waiting on the same emulator; it never
+  launches a duplicate. See \`stim guide errors STIM_NO_DEVICE\` for the
+  wait windows, diagnostics, and recovery steps.
 
 DESTRUCTIVE COMMANDS -- ask the user first
   gc --delete             deletes orphaned stim-* devices, tens of GB
@@ -2403,6 +2486,82 @@ TWO REPORTS, TWO QUESTIONS
   the machine, with a hit rate and an estimate of the time saved (see
   \`guide facts stats\`).`,
 		sections: {
+			eas: {
+				summary: "download a matching EAS development build; explicit profile, costs, cache and miss remedies",
+				body: () => `EAS DEVELOPMENT BUILDS
+
+  stim ios --eas-profile ios-simulator
+  stim android --eas-profile development
+  stim ios --eas-profile development-device --device <udid>
+  stim android --eas-profile development --device <serial>
+
+An eas.json file does not select EAS automatically. The flag names the profile
+and selects EAS Build as the artifact source. The profile must resolve to
+"developmentClient": true and "distribution": "internal". For iOS, set
+"ios.simulator": true for a simulator, or false (or omit it) for --device.
+An explicit ios.buildConfiguration must be Debug;
+android.gradleCommand must be a single :app:assemble<Variant>Debug task producing
+an APK. Install eas-cli and authenticate with eas login
+or EXPO_TOKEN. The Expo app must already be linked to the intended EAS project.
+
+Use the profile the user names. Otherwise inspect eas.json, including extends
+and platform overrides, for the requested platform, simulator or physical
+device, and app variant or environment. Choose a profile only when those
+requirements identify one compatible development profile. If there is no
+compatible profile or the choice is ambiguous, ask the user. Profile names
+alone do not establish compatibility. Confirm the resolved settings with
+npx eas-cli config --platform <ios|android> --profile <name> --json --non-interactive.
+Pass the selected name to --eas-profile; the CLI does not infer it.
+
+Stim delegates profile inheritance, environment resolution and fingerprinting
+to EAS CLI. fingerprint:generate uploads fingerprint metadata to EAS. It does
+not start a native build. EAS access is needed even when the artifact is
+already cached, because the current profile and fingerprint must be resolved.
+
+Stim matches the EAS project, profile, native fingerprint, platform and
+simulator/internal distribution target against a completed build. It downloads
+an iOS .app or Android .apk with EAS CLI, then uses its existing installation,
+Metro connection, log capture and launch verification on the selected device.
+The flag also works with --remote; remote EAS Simulator sessions have their
+own costs, independent of this download path. Local --scheme, --configuration,
+--variant and --no-build-cache selectors
+cannot be combined with --eas-profile. Local configuration/variant defaults
+are ignored for this development-build run.
+
+Physical devices use Stim's usual selection and lease rules. An iOS app must
+have a development-client URL scheme and a valid embedded provisioning profile
+that includes the target UDID. Stim installs the signed app without re-signing
+it. If the profile does not admit the device, the remedy points to
+npx eas-cli device:create and npx eas-cli build --platform ios --profile <name>.
+Registration, signing changes and cloud builds need session authorization.
+Run the EAS build interactively when its provisioning profile needs refreshing,
+then retry the same Stim command.
+
+Start Metro with stim start as usual. Metro uses the local workspace's
+environment; arrange the appropriate local variables before starting it.
+EAS environment resolution for native fingerprinting does not configure Metro.
+
+EAS CLI caches extracted artifacts by project and build ID in its own temporary
+cache. Stim calls build:download and uses the returned artifact without making
+another cache copy. Every run queries the latest matching build, so a rebuild
+with a refreshed provisioning profile is selected even if its native fingerprint
+is unchanged. Stim coordinates concurrent downloads by project and build ID.
+cacheHit: "remote" identifies the EAS source, including when EAS CLI reuses its
+disk cache. The fingerprint fact is the EAS native fingerprint. Stim's local
+buildCache and remoteBuildCache settings do not control EAS CLI's cache.
+EAS cache files are managed by EAS CLI and are outside Stim gc.
+
+On STIM_EAS_BUILD_MISSING, Stim stops before acquiring a device and prints:
+
+  npx eas-cli build --platform ios --profile ios-simulator
+
+Run that command only when the session authorizes the potentially billable
+cloud build. Once it completes, retry the same Stim command. No build-on-miss
+flag exists, and Stim never starts a cloud build or falls back to local
+compilation in this mode. Authentication, network, invalid output or download
+failures produce STIM_EAS_UNAVAILABLE, with the failed EAS command to inspect.
+If another run holds the artifact claim, wait for it to finish and retry.`
+			},
 			readiness: {
 				summary: "implement optional pending/ready app logs, deadlines, errors, and platform isolation",
 				body: () => `OPTIONAL APP READINESS
@@ -2572,9 +2731,11 @@ result as proof instead of requiring an unrelated screenshot.`
 
   \`--refresh\` always prints a \`lock\` line, then its own facts, one per
   step, before those. A plain warm prints the \`lock\` line only when its copy
-  actually waited for another warm:
+  actually waited for another warm. A current refresh reports
+  \`lock        acquired shared (seed current)\`; a refresh needing changes
+  reports \`acquired exclusive\` with the reason from its initial check:
 
-    lock        acquired (waited 12s for stim worktree warm --refresh pid 41233) -- stim guide lifecycle options
+    lock        acquired exclusive (fast-forward 2 commits) (waited 12s for stim worktree warm --refresh pid 41233) -- stim guide lifecycle options
     checkout    janic/wip 2 commits behind origin/janic/wip -> fast-forwarded to 4b81e0c
                 not the default branch (main); worktrees seeded from this copy
                 carry janic/wip's dependencies
@@ -2994,6 +3155,20 @@ WHAT MAKES THE CACHE ACTUALLY HIT: .FINGERPRINTIGNORE
   Never ignore a real native input -- a Podfile, a gradle file, the app config
   -- to force a hit: that trades a slow build for a wrong one.
 
+
+  React Native Test App can generate checkout-specific Android output under
+  node_modules/react-native-test-app/android/support/build. If fingerprint
+  differences point only there, add these project-specific entries:
+
+    node_modules/react-native-test-app/android/support/build
+    node_modules/react-native-test-app/android/support/build/**/*
+
+  Put them in the app root's .fingerprintignore and use the path as it appears
+  in the fingerprint sources; a hoisted or linked dependency may differ.
+  Keep android/support/build.gradle and native sources included. Confirm equal
+  fingerprints across built worktrees, and confirm a real native input edit
+  still changes the hash. These exclusions are not Stim defaults.
+
   \`stim doctor\` measures this directly rather than reading the file: it
   fingerprints HEAD in a temporary clean worktree, compares, and reports a
   mismatch naming the differing sources. Untracked, non-gitignored files under
@@ -3081,13 +3256,13 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
 				summary: "every flag per command, Android variants and flavors, the per-run simulator model, runtime and system image",
 				body: () => `THE OPTION SURFACE, IN FULL
   start           --json --wait <seconds> --remote --reset-cache
-  ios             --json --no-metro-check --no-build-cache --scheme <name> --configuration <name> --device-type <name> --runtime <version> --device [udid] --wait <seconds> --no-wait --remote <proxy|eas>
-  android         --json --no-metro-check --no-build-cache --variant <name> --system-image <id> --device [serial] --wait <seconds> --no-wait --remote <proxy|eas>
+  ios             --slot <name> --json --no-metro-check --no-build-cache --scheme <name> --configuration <name> --device-type <name> --runtime <version> --device [udid] --wait <seconds> --no-wait --remote <proxy|eas>
+  android         --slot <name> --json --no-metro-check --no-build-cache --variant <name> --system-image <id> --device [serial] --wait <seconds> --no-wait --remote <proxy|eas>
   reload          [ios|android] --json
-  device          lock <ios|android> [id] --for <duration> --wait <seconds> --json;
-                  unlock [ios|android] --json
-  logs            --source --level --since --grep --tail --follow --errors --json
-  stop            --json
+  device          lock <ios|android> [id] --slot <name> --for <duration> --wait <seconds> --json;
+                  unlock [ios|android] --slot <name> --json
+  logs            --slot <name> --source --level --since --grep --tail --follow --errors --json
+  stop            --slot <name> --json
   status          --json          (already machine-wide)
   stats           --json          (this project and machine-wide)
   doctor          --json --fix --platform <ios|android>
@@ -3095,6 +3270,38 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   gc              --delete --older-than <days> --cache <name|all>
   worktree warm    --refresh; remove [path] --force
 
+  DEVICE SLOTS
+  Use --slot <name> on ios or android to keep any number of simulators,
+  emulators, or physical devices in the same workspace. Names are reusable
+  identities, not models: two slots can request identical models. A slot has
+  one target per platform. Omitting the flag selects default and preserves
+  the workspace's existing assignment.
+
+    stim ios --slot phone
+    stim ios --slot tablet --device-type "iPad Pro 13-inch (M4)"
+    stim ios --slot hardware --device <udid>
+    stim android --slot second-phone
+    stim logs --slot tablet --source device
+    stim stop --slot tablet
+
+  All slots share this workspace's Metro server and build cache. Native CLI
+  runs serialize workspace mutations; a waiting run can wait up to 30 minutes.
+  Named slots support local devices; remote sessions use the default slot.
+  Names use 1-64 letters, digits, underscores or hyphens, starting with a letter
+  or digit. Reserved object-property names are refused.
+
+  stop --slot shuts down that slot's owned devices and releases its leases,
+  retaining Metro and sibling slots. Plain stop handles the whole workspace.
+  status reports named devices under slots and counts their memory. Device
+  caps count every slot. Recycling uses the same model/runtime-matched pool
+  for every slot, with one shared cap per platform and oldest-first eviction.
+
+  Metro cannot reliably identify a particular simulator's bundle request.
+  When slots coexist, a shared bundle event is not proof that a particular
+  slot launched: Debug launch can report unverified. Check the reported device
+  directly. Release verification still checks its process. reload ios/android
+  addresses matching Metro peers across slots; it is not a single-slot reload.
+
   That is the whole surface today, and it is deliberately small. It can grow
   when a flag is genuinely the best answer -- but project-specific knowledge
   (release builds, variants, device targets) belongs in a script the repo owns,
@@ -3107,8 +3314,9 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   Running it in the source checkout refuses.
 
   \`--refresh\` WRITES TO THE SOURCE CHECKOUT before the copy, which is why it
-  is opt-in: it fetches, fast-forwards whatever branch is checked out there to
-  its \`@{upstream}\`, and installs what the new commits moved. It refuses a
+  is opt-in: it checks the upstream, fetches changes when needed, and fast-forwards
+  whatever branch is checked out there to its \`@{upstream}\`, and installs
+  what the new commits moved. It refuses a
   source checkout it cannot move -- uncommitted changes to tracked files or a
   rebase or merge in progress (STIM_MAIN_DIRTY), a detached HEAD
   (STIM_MAIN_DETACHED), or a branch that is both ahead and behind
@@ -3142,9 +3350,15 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   writes no failure anywhere -- is recovered the same way a failed one is.
 
   One lock per repository serialises this, whether or not you pass the flag:
-  \`--refresh\` holds it exclusively, and every copy holds it shared, so a copy
-  can never read a node_modules a refresh is rewriting. Two plain warms of the
-  same repository run together. The lock is keyed on the repository root, so
+  \`--refresh\` first checks under a shared claim. It uses \`git ls-remote\`
+  to compare the upstream's advertised commit with the local tracking ref without
+  updating Git refs or FETCH_HEAD. When the checkout, dependencies and Pods are
+  current, it keeps that shared claim through the copy, overlapping other copies.
+  A changed or unconfirmed upstream, fast-forward, dependency install or Pods
+  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.
+  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
   it, a recycled pid cannot keep it, and a refresh whose install runs in a
@@ -3152,20 +3366,13 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   holder every 30s and gives up with STIM_LOCK_TIMEOUT; a claim Stim cannot
   resolve refuses with STIM_CLAIM_REFUSED and names the removal rather than
   waiting on it or removing it.
-  A plain warm that cannot record a claim at all -- an unwritable STIM_HOME, a
-  STIM_HOME on a read-only mount or under a dangling symlink, a STIM_HOME that
-  is a file, or no \`unique-pid\` build for this platform
-  (STIM_CLAIM_UNAVAILABLE) -- says so in one dim line and copies without it,
-  exactly as it did before the lock existed, because a copy only reads.
-  \`--refresh\` refuses instead, because it writes. Before that unsynchronised
-  copy starts, warm still READS the claim set, which needs no claim of its own:
-  if a refresh holds this repository, or a claim in it cannot be resolved, the
-  copy refuses rather than reading a tree that is being rewritten. That read is
-  not a lock, so a refresh that starts after it is not covered; it closes the
-  window in which one is already installing. Closing the rest needs a claim,
-  which is the one thing that state cannot record, so the residual is
-  documented rather than fixed (appandflow/stim#696), as is the
-  \`acquired (waited 0s ...)\` a contended-but-fast wait prints.
+  Both plain warm and --refresh refuse before copying when no claim can be
+  recorded. Missing process identity, denied write access and read-only storage
+  report STIM_CLAIM_UNAVAILABLE with recovery instructions. Restore access to the
+  same claim store before retrying; choosing a different STIM_HOME would hide
+  concurrent warm operations. A non-directory claim path reports
+  STIM_CLAIM_REFUSED and names the blocking file with a move-aside command that
+  preserves its contents. Sub-second waits omit the elapsed-time suffix.
 
   Wait for warm to exit successfully (exit code 0) before running start,
   ios, android, or a dependency install in that worktree. If a shell tool
@@ -3600,6 +3807,13 @@ HOST MEMORY PRESSURE AND STALLED SIMULATORS
   a final boot-state query can take 30 seconds. Opening the Simulator app after
   boot is best-effort and takes at most 5 seconds. A timeout is not proof of an
   app crash or OOM.
+  During boot, Stim reports elapsed time, the simulator name, last boot output,
+  current pressure and the highest observed pressure roughly every 15 seconds.
+  Failure diagnostics retain the highest pressure and unavailable sample count;
+  they do not infer the cause of a timeout. Monitoring stops when boot ends.
+  Monitoring and timeout handling are best-effort: synchronous CLI work can
+  delay them. Diagnostics report observation gaps over 30 seconds; pressure
+  during a gap is unobserved, even when the surrounding readings are normal.
   Doctor and failure diagnostics report macOS memory pressure when available;
   a failed query remains unknown. Existing swap or low free RAM alone is not
   enough to diagnose pressure.
@@ -3614,7 +3828,16 @@ HOST MEMORY PRESSURE AND STALLED SIMULATORS
 	},
 	cleanup: {
 		summary: "Where simulators come from, and how they get reclaimed",
-		preamble: () => `CLEANUP AND DISK
+		preamble: () => `DEVICE SLOTS
+
+Cleanup enumerates every slot. stop --slot <name> keeps the shared server and
+other slots; plain stop and worktree remove handle the whole workspace.
+An upgrade retains existing device assignments as the default slot. Do not
+wipe state to upgrade: it records ownership needed for safe teardown. Use the
+same slot-aware CLI for all commands while named assignments exist; older
+versions cannot reliably manage their assignments.
+
+CLEANUP AND DISK
 
 WHAT RECLAIMS AN OWNED DEVICE
   stim worktree remove    parks eligible owned simulators and emulators
@@ -3631,6 +3854,16 @@ Those are the only two commands that delete. \`stim stop\` shuts a device
 DOWN and leaves it assigned, which is what makes returning to a branch cost a
 boot rather than a create, a provision and a reinstall.
 
+Before shutting down, parking or deleting an owned device, Stim best-effort
+closes local agent-device sessions bound to its exact iOS UDID or live Android
+serial. It rechecks device ownership and uses agent-device's rejecting session
+target guard; sessions on other devices stay open. Physical devices are outside
+this cleanup. agent-device is optional: a missing binary skips this step, and a
+failed or timed-out list/close prints a device line on stderr while teardown
+continues. Cleanup allows at most 15 seconds of agent-device calls per device.
+A local daemon that cannot use socket transport or a CLI without the target guard
+skips cleanup with a warning; no remote daemon is used.
+
 Neither touches $STIM_HOME/stats.json: \`gc\` never reports or trims the run
 counters \`stats\` prints, and there is no reset flag. Delete that one file to
 start the counters over. A file this version cannot read -- unparseable, or