stim 1.1.0 → 1.3.0

package/dist/{guide-DrhrDBo5.mjs → guide-92CPA21s.mjs}

@@ -1,4 +1,4 @@
-import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-BSwrY4FZ.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
@@ -64,6 +73,13 @@ Doctor reports cross-volume staging and build-cache copies; read guide settings
 for placement overrides and guide lifecycle options for warm behavior.
 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. 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.
 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.
 
@@ -83,6 +99,21 @@ 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
+waiting times out.
+
   # Reproduce the affected behavior and capture the baseline errors.
   stim logs --errors
 
@@ -132,8 +163,6 @@ RULES DURING THE LOOP
   the error screen remains, follow the printed reload remedy instead of
   running ios or android again. If launch says FATAL because the app process exited,
   fix the crash and run the platform command again; Metro cannot restart it.
-- A native build can outlive a shell timeout. Retry the same command and
-  follow its printed remedy if waiting times out. See guide lifecycle concurrency.
 - ios and android install the app, launch it, and check readiness. Trust the
   exact device, app, Metro, and launch facts in the final summary. Use the full
   reported device ID. Never assume a simulator named booted belongs to this
@@ -156,7 +185,9 @@ RULES DURING THE LOOP
 - 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
-  looks incomplete.
+  looks incomplete. If status reports a changed Android serial, rerun stim
+  android with the same build options to restore forwarding, then reopen your automation
+  session on the reported serial (guide lifecycle).
 
 OWNERSHIP AND DELETION
 
@@ -215,6 +246,34 @@ requirements.
 
 LOAD ADVANCED GUIDANCE WHEN NEEDED
 
+Read the matching guide before acting in these situations:
+
+| Situation                                             | Read                             |
+| ----------------------------------------------------- | -------------------------------- |
+| Build waiting on another workspace or tool timeout    | stim guide lifecycle concurrency |
+| --variant, scheme, or several APKs from assembleDebug | stim guide lifecycle options     |
+| Refusal with a CODE                                   | stim guide errors <CODE>         |
+| Running under a sandbox                               | stim guide errors sandbox        |
+| Release configuration or ...Release variant           | stim guide lifecycle release     |
+| Remote device, custom Metro, or tunnel                | stim guide metro                 |
+| Cache miss, bypass, or fingerprint exclusions         | stim guide lifecycle builds      |
+| Capacity limits                                       | stim guide lifecycle concurrency |
+| Cache statistics from stim stats                      | stim guide facts stats           |
+| Worktree carry-over                                   | stim guide lifecycle options     |
+| gc or orphaned resources                              | stim guide cleanup gc            |
+| worktree remove refusal or --force                    | stim guide errors remove         |
+| Cleanup failure or unverified cleanup ownership       | stim guide errors teardown       |
+| Unfamiliar state or JSON field                        | stim guide facts payloads        |
+| Refusal without a code                                | stim guide errors                |
+
+Use the CODE exactly as printed; codes sharing a header resolve to the same
+section. For a refusal without a code, find its quoted message in the errors
+index. Ordinary stim stop and an authorized clean stim worktree remove do not
+need the cleanup guide. A sectioned topic called without a section prints its
+index; choose the narrowest section.
+
+FULL TOPIC LIST
+
   stim guide                      # list topics
   stim guide errors               # index of every refusal code and message
   stim guide errors <CODE>        # one refusal, e.g. stim guide errors STIM_NO_METRO
@@ -235,23 +294,17 @@ LOAD ADVANCED GUIDANCE WHEN NEEDED
   stim guide logs                 # filters, record shape, and capture limits
   stim guide cleanup              # what reclaims a device, and what deletes
   stim guide cleanup collector    # an unproven collector pid; why the app on a phone closed
-  stim guide settings             # configuration files and supported keys
-
-A refusal prints a CODE such as STIM_NO_METRO. Run stim guide errors <CODE>
-with the code exactly as printed and read only that section; every code in a
-shared header (STIM_BAD_ARG / STIM_NO_PROJECT) resolves to the same section. A
-refusal with no code is quoted by message in stim guide errors. A topic with
-sections called bare prints its section index, so read the narrowest section
-before release configurations or Android variants; remote devices; custom
-Metro processes or tunnels; cache misses, bypasses, or concurrent builds;
-capacity limits; cache statistics from stim stats; worktree carry-over;
-fingerprint exclusions; gc; --force; cleanup failures; or unfamiliar states
-and error codes. Ordinary stim stop and an authorized clean
-stim worktree remove do not need the cleanup guide.`
+  stim guide settings             # configuration files and supported keys`
 	},
 	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
@@ -315,6 +368,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
@@ -705,6 +763,30 @@ Plain \`stim start\` is local and does not create a public tunnel. Remote intent
 comes from \`start --remote\`, \`ios.remote\`, or \`android.remote\`. The
 \`metro.tunnel\` setting selects the provider after remote intent exists.
 
+BUNDLE WARMUP
+  After verifying Metro, \`stim ios\` and \`stim android\` prefetch the
+  platform's development bundle while native work continues. Expo supplies the
+  entry point and bundle options through its manifest; bare React Native uses
+  the standard index entry and development bundle options, including lazy loading.
+  Warmup is enabled by default. Set optimizations.metroWarmup=false to disable
+  it on the next ios/android command, using the machine or project settings.
+  For custom entry points or bundle options, set metro.warmupUrl.ios and/or
+  metro.warmupUrl.android to the app's complete bundle URL or /path?query.
+  Stim keeps the path and query and uses the verified local Metro port.
+  Overrides replace discovery and receive no additional query defaults.
+  doctor validates configured URLs, including their platform; it does not
+  infer or auto-fix runtime native entry points or dev-menu bundle options.
+  See \`guide settings\` for configuration examples.
+  Each request times out after 60 seconds and does not keep the command alive.
+  Warmup failures do not fail the native build.
+  Release builds and \`--no-metro-check\` skip warmup. Servers without Stim's
+  prefetch-aware response observer also skip it; restart an older supervisor
+  with the current CLI to enable warmup.
+
+  Prefetch completion is not launch proof. Development launch verification
+  waits for the app's own bundle response. With a bundler started outside Stim,
+  device logs may prove a request, but bundle completion may stay unverified.
+
 REMOTE DEVICE BACKENDS
   Metro exposure and device selection are separate:
 
@@ -824,7 +906,13 @@ 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.
@@ -1088,6 +1176,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"],
@@ -1355,6 +1461,11 @@ code, never on the message.`,
 				body: () => `STIM_LAUNCH_FAILED
   Installed, but the app would not start. On Android this usually means no
   launchable activity resolved.
+  On a local iOS simulator, a timed-out launch can mean the simulator cannot
+  spawn processes, even while it reports Booted. Check the reported memory
+  pressure and free host memory before retrying; a timeout alone is not an OOM
+  diagnosis. See \`stim guide lifecycle simslim\` for recovery and the optional
+  SimSlim recommendation.
   On a PHONE it means the app never appeared in the device's own process list
   after \`devicectl device process launch\`, and the devicectl lines that
   explain it are quoted under the message. The refusal a first launch usually
@@ -1409,7 +1520,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",
@@ -1578,9 +1692,21 @@ so a Debug run on one is wired to a LAN origin instead of localhost.`,
   reach a booted state. \`stim doctor\` checks the toolchain; \`stim status\` says what
   Stim thinks it owns. Re-running the command creates a fresh owned device
   when the recorded one is gone.
+  If Android creation says an AVD already exists on disk but is not listed,
+  run \`npx stim gc\` to inspect orphaned owned AVDs, then \`npx stim gc --delete\`
+  to reclaim those safe to delete before retrying. Keep anything GC cannot
+  verify; do not delete AVD directories by hand. A registered unrecorded owned
+  AVD is recovered, reusing its existing emulator when its identity is verified.
+  If recovery cannot verify registration or process state, inspect \`npx stim status\`
+  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
+  \`stim guide lifecycle simslim\`. Booted alone does not prove readiness.
   On Android the emulator's own stdio is captured to
   the global workspace logs/emulator.log (truncated per boot), and when it printed a
   \`FATAL |\` / \`ERROR |\` / \`PANIC:\` line THAT is the message and the remedy
@@ -2116,9 +2242,11 @@ changes nothing  (worktree warm --refresh)
   blocks network egress by default, which breaks a cache lookup and a fetch.
 
   \`stim doctor\` names this when a write to STIM_HOME actually fails, not
-  merely when a harness that can sandbox is present, and
-  \`stim doctor --fix\` writes the three keys into .claude/settings.local.json,
-  the per-user file, merging with what is there. It refuses under Codex, which
+  merely when a harness that can sandbox is present. \`stim doctor --fix\`
+  writes only when the report shows that finding, and only what the finding
+  names: the three keys, into .claude/settings.local.json, the per-user file,
+  merging with what is there. A report without the finding, with or without
+  --platform, leaves that file alone. It refuses under Codex, which
   has no per-path allowance to add, and refuses any settings file it cannot
   parse rather than replace it: comments make one unparseable here even though
   Claude Code accepts them. Claude Code reads project settings from the
@@ -2293,6 +2421,21 @@ If the app is stuck before loading its first bundle, restart its process with
 the printed force-stop and launcher commands. Foregrounding the same process
 does not restart initialization. Confirm the bundle request and expected UI.
 
+Debug Android launches on an owned emulator created in the same run get up to
+60 seconds for bundle loading; the verify phase names that budget. Existing
+emulators, remote targets, and physical devices keep the 20-second budget.
+Bundle delivery still requires the usual stability or app readiness check;
+an observed fatal error ends verification without waiting for the deadline.
+
+ANDROID EMULATOR RESTARTS
+  \`stim status\` resolves owned AVDs to their currently detected adb serial.
+  Its Android JSON adds serial and state (detected, not-detected, missing,
+  or unknown). Detection confirms device identity, not app health. Status
+  reports a serial change without changing forwarding or restarting anything.
+  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.
+
 DESTRUCTIVE COMMANDS -- ask the user first
   gc --delete             deletes orphaned stim-* devices, tens of GB
   gc --delete --cache all empties the shared build caches every project uses
@@ -2319,6 +2462,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
@@ -2474,7 +2693,7 @@ result as proof instead of requiring an unrelated screenshot.`
     build       still compiling (4m00s, usually ~3m10s)
     build       still compiling (1m00s)
     pods        still installing (1m30s of ~1m40s)
-    build       waiting on /w/app-411 (pid 41233, 1m30s elapsed)
+    build       waiting on /w/app-411 (pid 41233, 1m30s elapsed) -- stim guide lifecycle concurrency
 
   The \`~\` value is an estimate, never a countdown; the third line is a
   project with no record to estimate from yet. \`guide facts stats\` says where
@@ -2490,7 +2709,7 @@ result as proof instead of requiring an unrelated screenshot.`
   step, before those. A plain warm prints the \`lock\` line only when its copy
   actually waited for another warm:
 
-    lock        acquired (waited 12s for stim worktree warm --refresh pid 41233)
+    lock        acquired (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
@@ -2498,7 +2717,7 @@ result as proof instead of requiring an unrelated screenshot.`
     pods        source /w/main/apps/mobile: ios/Podfile.lock changed -> pod install (1m12s)
 
   A wait reports how long this caller has waited and names the holder:
-  \`lock        waiting 40s for stim worktree warm --refresh (pid 41233)\`.
+  \`lock        waiting 40s for stim worktree warm --refresh (pid 41233) -- stim guide lifecycle options\`.
 
   \`start\` names the port, the supervisor mode and its pid on one line
   (\`metro       starting on port 8083 (expo-child, supervisor pid 13724)\`),
@@ -2744,7 +2963,7 @@ changing modes selects another profile. See \`guide settings\` for cleanup.
 
 Each reports its cache setup. \`stim doctor\` checks missing or stale setup
 when a build is blocked or slow. It reports what Stim cannot handle itself
-(a missing dev client, ccache absent from PATH or a .cxx that predates the
+(ccache absent from PATH or a .cxx that predates the
 launcher, a fingerprint no fresh worktree reproduces, a provider on a key this
 SDK ignores) and settings for builds outside Stim.
 
@@ -2926,9 +3145,9 @@ WHAT MAKES THE CACHE ACTUALLY HIT: .FINGERPRINTIGNORE
   <fingerprint, platform> (a directory under ~/.stim/build-locks). Exactly
   one workspace compiles; the others print
 
-    build       /w/app-412 is already building a3f9b1.. (pid 41233) -- tail ...
-    build       waiting on /w/app-412 (pid 41233, 4m elapsed) -- tail ...
-    build       waited 12m41s for /w/app-412's build -> installed from cache
+    build       /w/app-412 is already building a3f9b1.. (pid 41233) -- tail ... -- stim guide lifecycle concurrency
+    build       waiting on /w/app-412 (pid 41233, 4m elapsed) -- tail ... -- stim guide lifecycle concurrency
+    build       waited 12m41s for /w/app-412's build -> installed from cache -- stim guide lifecycle concurrency
 
   and install the artifact the builder stored. They report cacheHit: "local"
   plus waitedForBuild: { pid, ms }.
@@ -2997,13 +3216,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>
@@ -3011,6 +3230,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,
@@ -3096,10 +3347,27 @@ 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, .DerivedData, and android/build/generated/autolinking
-  caches are excluded, including in nested apps. Gradle regenerates autolinking
+  registered worktrees, .DS_Store, .DerivedData, .idea, and
+  android/build/generated/autolinking caches are excluded, including inside
+  newly copied directories. 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.
+
+  Other generated state stays eligible: .gradle, .cxx, *.tsbuildinfo, build
+  directories, and embedded JavaScript need project-specific decisions about
+  regeneration. Native intermediates can record the source checkout's paths;
+  warm does not relocate them. Excluding the whole .expo directory can drop
+  generated TypeScript inputs.
+
+  To choose exclusions, run this in the source checkout's repository root:
+
+    git ls-files --others --ignored --exclude-standard --directory --no-empty-directory
+
+  Patterns match those entries with the trailing / removed. They do not prune
+  children of a whole ignored directory: if Git lists android/app/src/main/assets/,
+  excluding its bundle.jsbundle child has no effect. Exclude the assets entry
+  only when the project regenerates everything inside it.
 
   Warm copies directly into the destination, without intermediate staging.
   Keep the source checkout and the linked worktree on the same volume to
@@ -3451,28 +3719,85 @@ THE POOL: WHICH DEVICE AN ID-LESS \`--device\` PICKS
   \`.ipa\` export, store signing and distribution stay out of scope.`
 			},
 			simslim: {
-				summary: "installing SimSlim and what ios.simslimProfile does to an owned simulator",
-				body: () => `OPTIONAL SIMSLIM PROFILE
+				summary: "recommended SimSlim profiles and recovery from host memory pressure",
+				body: () => `SIMSLIM FOR PARALLEL IOS WORK
+  SimSlim is recommended as an optional way to reduce simulator background
+  services and memory use, especially with several workspaces. Review which
+  services your app and tests need; a slim profile can disable those features.
+  It does not guarantee that a memory stall or crash will be fixed.
+
   Install SimSlim once on each Mac:
 
     brew install mobai-app/tap/simslim
 
-  Then commit a profile and select it in .stim.json:
+  Review the categories and create a profile in an interactive terminal:
+
+    simslim profiles
+    mkdir -p .simslim
+    simslim profile .simslim/dev.json
+
+  Selected categories in the wizard stay enabled. The wizard writes the
+  profile without applying it. Review and commit it, then select it in .stim.json:
 
     { "ios": { "simslimProfile": ".simslim/dev.json" } }
 
-  SimSlim requires an iOS 18 or newer simulator. On each local \`stim ios\`,
+  SimSlim 0.8 requires iOS 18.5 or newer. On each local \`stim ios\`,
   Stim reconciles that profile on the owned simulator before the app build.
   The first change can update services and reboot the simulator. A matching
   profile is a fast no-op on later launches. The settings persist across normal
   shutdowns and reboots. Removing the setting restores stock services when
-  Stim applied the profile. Stim never changes an unowned or remote simulator.`
+  Stim applied the profile. Stim never changes an unowned or remote simulator.
+  Each SimSlim operation has a 12-minute outer deadline, including discovery.
+  This cap also applies when SimSlim's own timeout is increased. On timeout,
+  Ctrl-C, or SIGTERM, Stim attempts to stop only its verified process group, then waits up to
+  10 seconds to confirm termination before returning or exiting.
+  An unconfirmed process group keeps its claim and blocks another reconciliation;
+  inspect the named processes before removing the exact claim in the error.
+  The simulator's managed settings record is retained, so retrying reconciles an
+  interrupted apply or restore. Stim does not assume partial changes rolled back.
+  Doctor recommends this setup but never installs SimSlim or applies a profile.
+  Profile schema and service tradeoffs: https://github.com/MobAI-App/simslim
+
+HOST MEMORY PRESSURE AND STALLED SIMULATORS
+  Booted and a working screenshot do not prove that simulator processes can
+  start. Stim checks a bounded process spawn before install and bounds local
+  simulator launch operations. Simulator discovery waits up to 30 seconds,
+  boot (including the initial boot request) up to 10 minutes, and app installation
+  up to 5 minutes. Process termination confirmation can take another 10 seconds;
+  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.
+
+  If pressure is elevated, free host memory before retrying. Use \`stim stop\`
+  only in workspaces you own and have finished using; ask before closing other
+  agents' simulators or heavy apps. Rebooting a simulator under the same pressure
+  can repeat the stall. Consider fewer concurrent builds/devices (guide lifecycle
+  concurrency) and a reviewed SimSlim profile for future runs.`
 			}
 		}
 	},
 	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
@@ -3527,6 +3852,18 @@ If a delete fails, the device's config record is KEPT and the command reports
 it. A record is what makes the device findable again, so it outlives a failed
 teardown rather than turning it into an orphan.
 
+ANDROID DATA WITHOUT A REGISTRATION
+  \`gc\` also reports stim-*.avd directories whose .ini registration is
+  gone. \`gc --delete\` rechecks the directory, emulator process locks, and
+  current workspace and pool references before removing that data. A registration
+  under any name that points at the directory protects it. User AVDs, symlinks
+  and unverifiable storage stay. The no-config and scoped-STIM_HOME
+  sweep guards apply to these directories too.
+  A partial avdmanager deletion is a failure even if the tool exits successfully.
+  The owning workspace or pool record stays for a retry. If removing orphan
+  data fails, its remaining directory is reported as stim-gc-<id>.avd on the
+  next sweep.
+
 BUILD LOCKS
   \`gc\` also reports the single-flight build locks (above): the ones whose
   builder is no longer running are debris a reboot or a kill left behind, and
@@ -3777,7 +4114,9 @@ KEYS STIM READS
                         at most 64 KiB. Install the
                         external tool once with
                         \`brew install mobai-app/tap/simslim\`. SimSlim requires
-                        an iOS 18 or newer simulator. Each local \`stim ios\`
+                        iOS 18.5 or newer in SimSlim 0.8. Recommended for parallel
+                        iOS work after reviewing service tradeoffs; see
+                        \`stim guide lifecycle simslim\`. Each local \`stim ios\`
                         reconciles the profile on its Stim-owned simulator.
                         The first change can reboot it; a matching profile is a
                         fast no-op. Removing the setting restores stock services
@@ -3814,7 +4153,10 @@ KEYS STIM READS
                         -- the sdkmanager package id the owned AVD is created
                         from. The \`--system-image\` flag overrides this per
                         invocation, and an id this SDK has not installed is
-                        STIM_BAD_ARG with the installed ids printed
+                        STIM_BAD_ARG with the installed ids printed.
+                        New AVDs use the Pixel 6 hardware profile (1080x2400,
+                        420 dpi). Existing AVDs keep their display settings;
+                        parked AVDs from the old generic profile are not adopted.
   android.dataPartitionSizeGb
                         whole GiB for a newly created owned AVD's data
                         partition. Defaults to 8; accepts 6 through 16384.
@@ -3894,6 +4236,25 @@ ${ANDROID_AVD_CONFIG_HELP.map((line) => `                          ${line}`).joi
                         did not create it, so a Metro request through it is
                         still gated the same way a managed tunnel's is. Set it
                         before Expo start so the manifest advertises it.
+  metro.warmupUrl       optional object with per-platform bundle URLs:
+  metro.warmupUrl.ios
+  metro.warmupUrl.android
+                        an HTTP(S) URL or a /path ending in .bundle, with the
+                        full query the app uses, including a matching platform.
+                        Unset uses Expo's manifest or bare React Native defaults.
+                        Stim preserves the path and query but always requests
+                        this workspace's verified local Metro port; a supplied
+                        host and port are ignored. No defaults are added to an
+                        override. This only configures prefetch, not the app.
+                        For example, in .stim.json:
+                        { "metro": { "warmupUrl": {
+                          "ios": "/src/main.bundle?platform=ios&dev=true&lazy=true"
+                        } } }
+                        Use the app's complete request for custom options.
+                        URLs must encode spaces and omit fragments. doctor
+                        validates the shape and platform but cannot discover
+                        runtime entry-point or dev-menu overrides or auto-fix
+                        them. See \`guide metro\` for warmup behavior.
   worktree.exclude      ignored-path skip list for worktree warm. Settings
                         come from the source checkout's repository-root
                         .stim.json. A nonempty .worktreeexclude in the source
@@ -4044,6 +4405,7 @@ key inherits the next layer. Changes apply on the next build or Metro restart.
       "remoteBuildCache": true,
       "releaseBundleSwap": true,
       "metroSharedCache": true,
+      "metroWarmup": true,
       "ios": {
         "compilationCache": true,
         "swiftCompilationCache": false,
@@ -4075,6 +4437,11 @@ The example shows the defaults. Full setting names and behavior:
     false stops Stim appending its shared Metro store on both dev servers.
     Project-configured stores remain the project's choice. Replace the removed
     machine setting caches.injectMetroStore=false with this setting set false.
+  optimizations.metroWarmup
+    true by default. false skips background development bundle requests during
+    ios/android, including any metro.warmupUrl override. Metro verification and
+    native builds still run. Applies on the next ios/android command; no Metro
+    restart is needed.
   optimizations.ios.compilationCache
     controls Xcode compilation caching (Xcode 26+).
   optimizations.ios.swiftCompilationCache