stim 1.2.0 → 1.3.0

package/dist/{gc-B7KkDinF.mjs → gc-GGu-8ULN.mjs}

@@ -1,20 +1,19 @@
 import { t as getExecutor } from "./exec-CyylIdq9.mjs";
-import { A as directorySize, M as isOnMountedVolume, N as listMountedVolumes, P as volumeRootFor, g as loadConfig, i as clearDevice, j as formatBytes, u as getConfigDir, v as removeProject } from "./config-CMtIaTk9.mjs";
-import { i as registeredCaches } from "./cache-manifest-Cu4_Znw9.mjs";
-import { T as workspaceDir, k as workspaceStateFile } from "./state-CZ-ER-8d.mjs";
-import { g as repoRoot, s as gitCommonDir } from "./worktree-C79xx_kM.mjs";
-import { a as findProjectRoot, i as detectIsExpo } from "./project-BBTVABUz.mjs";
-import { S as readParked, _ as teardownParkedIosSim, b as dropParked, d as resolveEasCliBin, g as teardownParkedAvd, h as teardownOwnedIosSim, m as teardownOwnedAvd, v as POOL_SETTING_REMEDY, x as parkedMaxSetting } from "./remote-cache-DDmJ1Roq.mjs";
-import { A as resolveSettings, N as settingShapeErrors, a as SETTING_SHAPE_REMEDY } from "./settings-DwU1_U_q.mjs";
+import { A as directorySize, M as isOnMountedVolume, N as listMountedVolumes, P as volumeRootFor, g as loadConfig, i as clearDevice, j as formatBytes, u as getConfigDir, v as removeProject, z as projectDeviceSlots } from "./config-CcefMY2Q.mjs";
+import { i as registeredCaches } from "./cache-manifest-CXR-Y8pH.mjs";
+import { T as workspaceDir, k as workspaceStateFile } from "./state-B3XA2wp2.mjs";
+import { g as repoRoot, s as gitCommonDir } from "./worktree-Eq6TLH8N.mjs";
+import { a as findProjectRoot, i as detectIsExpo } from "./project-fKmuIaMI.mjs";
 import { m as shortUdid, o as formatLongDuration, u as plural } from "./command-output-8wHMEde0.mjs";
-import { d as listIosDeviceTypes, g as parseRuntimeVersion, u as listAllIosSims } from "./ios-D1h1Di39.mjs";
-import { r as listBuildLocks } from "./build-lock-BsVoLDaq.mjs";
-import { d as readClaimSet, o as clearFreeClaimSet } from "./ownership-claim-7zRxxTfZ.mjs";
-import { i as listLeaseFiles, r as leaseIsExpired, u as removeExpiredLease } from "./device-lease-Dpik41RY.mjs";
-import { n as listBuildSlots } from "./build-slots-D0b6sJyo.mjs";
-import { S as listOrphanedAvdDirectories, T as ownedAvdDirectory, b as listAvds } from "./android-K63_0UfF.mjs";
-import { C as verifyStoppedSession, S as stopSessionArgs, _ as inspectSessionForTeardown, d as withEasProjectLock, f as easMachineStateRoot, g as getSessionArgs, h as findOrphanedOwnedSessions, m as removeEasSessionClaim, p as readEasSessionLedger, u as withRemoteSessionLock, v as isDefinitiveMissingSessionError, x as parseSessionListPage, y as listOwnedSessionsArgs } from "./device-remote-E81KAdXf.mjs";
-import { n as reclaimProject, t as describeDereferenced } from "./reclaim-C5Jmuahx.mjs";
+import { d as readClaimSet, o as clearFreeClaimSet } from "./ownership-claim-Bf2CAfw3.mjs";
+import { B as listBuildLocks, S as listOrphanedAvdDirectories, T as ownedAvdDirectory, b as listAvds } from "./android-BqVIJoG7.mjs";
+import { A as resolveSettings, N as settingShapeErrors, a as SETTING_SHAPE_REMEDY } from "./settings-DEJf6_kJ.mjs";
+import { a as POOL_SETTING_REMEDY, c as parkedMaxSetting, i as teardownParkedIosSim, l as readParked, n as teardownOwnedIosSim, r as teardownParkedAvd, s as dropParked, t as teardownOwnedAvd, x as resolveEasCliBin } from "./teardown-ClFp1Aax.mjs";
+import { d as listIosDeviceTypes, g as parseRuntimeVersion, u as listAllIosSims } from "./ios-Deh5js5V.mjs";
+import { i as listLeaseFiles, r as leaseIsExpired, u as removeExpiredLease } from "./device-lease-BJYybF-2.mjs";
+import { n as listBuildSlots } from "./build-slots-C3-R4XQr.mjs";
+import { C as verifyStoppedSession, S as stopSessionArgs, _ as inspectSessionForTeardown, d as withEasProjectLock, f as easMachineStateRoot, g as getSessionArgs, h as findOrphanedOwnedSessions, m as removeEasSessionClaim, p as readEasSessionLedger, u as withRemoteSessionLock, v as isDefinitiveMissingSessionError, x as parseSessionListPage, y as listOwnedSessionsArgs } from "./device-remote-AkYCKS8U.mjs";
+import { n as reclaimProject, t as describeDereferenced } from "./reclaim-iW9Cad7k.mjs";
 import { InvalidArgumentError } from "commander";
 import { existsSync, readFileSync, readdirSync, realpathSync, rmSync, statSync } from "fs";
 import { homedir, tmpdir } from "os";
@@ -413,16 +412,18 @@ function findOrphanedDevices({ sims = [], avds = [], config, isMounted, deadProj
 	for (const [path, proj] of Object.entries(config?.projects || {})) {
 		if (dead.has(path)) continue;
 		const mounted = isMounted ? isMounted(path) : true;
-		const ios = proj?.platforms?.ios;
-		if (ios?.deviceUdid) referenced.set(ios.deviceUdid, {
-			path,
-			mounted
-		});
-		const android = proj?.platforms?.android;
-		if (android?.avdName) referenced.set(android.avdName, {
-			path,
-			mounted
-		});
+		for (const { platforms } of projectDeviceSlots(proj)) {
+			const ios = platforms.ios;
+			if (ios?.deviceUdid) referenced.set(ios.deviceUdid, {
+				path,
+				mounted
+			});
+			const android = platforms.android;
+			if (android?.avdName) referenced.set(android.avdName, {
+				path,
+				mounted
+			});
+		}
 	}
 	for (const sim of readParked("ios", { config })) referenced.set(sim.udid, {
 		path: "the simulator pool",
@@ -481,22 +482,26 @@ function findStaleProjectDevices({ config, sims = [], avds = [], olderThanDays,
 		const touched = lastTouched(path);
 		if (!Number.isFinite(touched) || touched >= cutoff) continue;
 		const idleDays = Math.floor((now - touched) / DAY_MS);
-		const ios = proj?.platforms?.ios;
-		if (ios?.owned && ios.deviceUdid && liveSims.has(ios.deviceUdid)) stale.push({
-			kind: "ios",
-			id: ios.deviceUdid,
-			name: liveSims.get(ios.deviceUdid),
-			project: path,
-			idleDays
-		});
-		const android = proj?.platforms?.android;
-		if (android?.owned && android.avdName && liveAvds.has(android.avdName)) stale.push({
-			kind: "android",
-			id: android.avdName,
-			name: android.avdName,
-			project: path,
-			idleDays
-		});
+		for (const { slot, platforms } of projectDeviceSlots(proj)) {
+			const ios = platforms.ios;
+			if (ios?.owned && ios.deviceUdid && liveSims.has(ios.deviceUdid)) stale.push({
+				kind: "ios",
+				id: ios.deviceUdid,
+				name: liveSims.get(ios.deviceUdid),
+				project: path,
+				...slot === "default" ? {} : { slot },
+				idleDays
+			});
+			const android = platforms.android;
+			if (android?.owned && android.avdName && liveAvds.has(android.avdName)) stale.push({
+				kind: "android",
+				id: android.avdName,
+				name: android.avdName,
+				project: path,
+				idleDays,
+				...slot === "default" ? {} : { slot }
+			});
+		}
 	}
 	return stale;
 }
@@ -507,20 +512,24 @@ function findStaleDeviceRecords({ config, sims = [], avds = [], deadProjects = [
 	const stale = [];
 	for (const [path, proj] of Object.entries(config?.projects || {})) {
 		if (dead.has(path)) continue;
-		const ios = proj?.platforms?.ios;
-		if (simsChecked && ios?.deviceUdid && !liveSims.has(ios.deviceUdid)) stale.push({
-			kind: "ios",
-			id: ios.deviceUdid,
-			project: path,
-			owned: Boolean(ios.owned)
-		});
-		const android = proj?.platforms?.android;
-		if (avdsChecked && android?.avdName && !liveAvds.has(android.avdName)) stale.push({
-			kind: "android",
-			id: android.avdName,
-			project: path,
-			owned: Boolean(android.owned)
-		});
+		for (const { slot, platforms } of projectDeviceSlots(proj)) {
+			const ios = platforms.ios;
+			if (simsChecked && ios?.deviceUdid && !liveSims.has(ios.deviceUdid)) stale.push({
+				kind: "ios",
+				id: ios.deviceUdid,
+				project: path,
+				...slot === "default" ? {} : { slot },
+				owned: Boolean(ios.owned)
+			});
+			const android = platforms.android;
+			if (avdsChecked && android?.avdName && !liveAvds.has(android.avdName)) stale.push({
+				kind: "android",
+				id: android.avdName,
+				project: path,
+				...slot === "default" ? {} : { slot },
+				owned: Boolean(android.owned)
+			});
+		}
 	}
 	return stale;
 }
@@ -704,12 +713,12 @@ function deleteProjectDevices(orphanedDevices, staleDevices, staleDeviceRecords)
 	for (const d of staleDevices) {
 		const status = reap(d);
 		if (status === "torn-down" || status === "missing") {
-			clearDevice(d.project, d.kind);
+			clearDevice(d.project, d.kind, d.slot);
 			console.log(chalk.dim(`  cleared the ${d.kind} record for ${d.project}`));
 		}
 	}
 	for (const r of staleDeviceRecords) {
-		clearDevice(r.project, r.kind);
+		clearDevice(r.project, r.kind, r.slot);
 		console.log(chalk.green(`Cleared the ${r.kind} record for ${r.project} (${r.id} is not on this machine)`));
 	}
 	return deleteFailures;

package/dist/{guide-BS2Xc24o.mjs → guide-92CPA21s.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
@@ -66,7 +75,9 @@ 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.
 For a linked native library carrying Git metadata, add the printed .git entries to
@@ -88,6 +99,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
@@ -277,7 +298,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 +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
@@ -874,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.
@@ -1138,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"],
@@ -1464,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",
@@ -1642,8 +1701,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
@@ -2403,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
@@ -3081,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>
@@ -3095,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,
@@ -3600,6 +3767,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 +3788,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