stim 1.3.1 → 1.5.0

package/dist/{gc-BRu62v4o.mjs → gc-C20dWw_8.mjs}

@@ -1,19 +1,18 @@
 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, 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 { o as clearFreeClaimSet, u as readClaimSet } from "./ownership-claim-BtPtJVmq.mjs";
-import { B as listBuildLocks, S as listOrphanedAvdDirectories, T as ownedAvdDirectory, b as listAvds } from "./android-hMj83VpN.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--gESs9ck.mjs";
+import { A as isOnMountedVolume, C as withConfigLock, E as ownership_claim_exports, F as deviceSlotPlatforms, L as projectDeviceSlots, M as volumeRootFor, O as directorySize, f as getProject, g as loadConfig, i as clearDevice, j as listMountedVolumes, k as formatBytes, u as getConfigDir, v as removeProject } from "./config-DMP7L7H6.mjs";
+import { i as registeredCaches } from "./cache-manifest-uoOKhgUD.mjs";
+import { h as workspaceDir, y as workspaceStateFile } from "./workspace-state-WVwWw_hB.mjs";
+import { g as repoRoot, s as gitCommonDir } from "./worktree-DJnBbQZ9.mjs";
+import { a as findProjectRoot, i as detectIsExpo } from "./project-B_SDt4ip.mjs";
+import { m as shortUdid, o as formatLongDuration, u as plural } from "./command-output-BuIb_ZOI.mjs";
+import { B as listBuildLocks, S as listOrphanedAvdDirectories, T as ownedAvdDirectory, b as listAvds } from "./android-DJWiTBkz.mjs";
+import { A as resolveSettings, N as settingShapeErrors, a as SETTING_SHAPE_REMEDY } from "./settings-kO2ZqIKy.mjs";
+import { S as resolveEasCliBin, a as POOL_SETTING_REMEDY, i as teardownParkedIosSim, l as parkedMaxSetting, n as teardownOwnedIosSim, r as teardownParkedAvd, s as dropParked, t as teardownOwnedAvd, u as readParked } from "./teardown-CAVcWeRD.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-CJwK7OZr.mjs";
-import { n as listBuildSlots } from "./build-slots-C4AouyNz.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-DAA0Zm6Z.mjs";
-import { n as reclaimProject, t as describeDereferenced } from "./reclaim-CUmwucWG.mjs";
+import { i as listLeaseFiles, r as leaseIsExpired, u as removeExpiredLease } from "./device-lease-r7yEQ1R8.mjs";
+import { n as listBuildSlots } from "./build-slots-CuPszJDu.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-BTUqbl0i.mjs";
+import { n as reclaimProject, t as describeDereferenced } from "./reclaim-C_rB25f4.mjs";
 import { InvalidArgumentError } from "commander";
 import { existsSync, readFileSync, readdirSync, realpathSync, rmSync, statSync } from "fs";
 import { homedir, tmpdir } from "os";
@@ -690,13 +689,20 @@ function collectDeviceLeases(now) {
 }
 function deleteProjectDevices(orphanedDevices, staleDevices, staleDeviceRecords) {
 	let deleteFailures = 0;
-	function reap(d) {
+	function reap(d, onlyIfMissing = false) {
 		const r = d.kind === "ios" ? teardownOwnedIosSim(d.id, {
 			del: true,
 			label: d.name
 		}) : teardownOwnedAvd(d.name, {
 			del: true,
-			..."project" in d ? { owner: { projectPath: d.project } } : {},
+			onlyIfMissing,
+			..."project" in d ? { owner: {
+				projectPath: d.project,
+				slot: d.slot
+			} } : {},
+			..."project" in d ? { onRemoved: () => {
+				if (clearDevice(d.project, d.kind, d.slot, d.id)) console.log(chalk.dim(`  cleared the ${d.kind} record for ${d.project}`));
+			} } : {},
 			..."orphanedDirectory" in d ? { orphanedDirectory: d.orphanedDirectory } : {}
 		});
 		const what = d.kind === "ios" ? `ios sim ${d.name} (${d.id})` : `android avd ${d.name}`;
@@ -712,15 +718,20 @@ function deleteProjectDevices(orphanedDevices, staleDevices, staleDeviceRecords)
 	for (const d of orphanedDevices) reap(d);
 	for (const d of staleDevices) {
 		const status = reap(d);
-		if (status === "torn-down" || status === "missing") {
-			clearDevice(d.project, d.kind, d.slot);
+		if (d.kind === "ios" && (status === "torn-down" || status === "missing")) {
+			clearDevice(d.project, d.kind, d.slot, d.id);
 			console.log(chalk.dim(`  cleared the ${d.kind} record for ${d.project}`));
 		}
 	}
-	for (const r of staleDeviceRecords) {
-		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)`));
-	}
+	for (const r of staleDeviceRecords) if (r.kind === "android" && r.owned) reap({
+		...r,
+		name: r.id,
+		idleDays: 0
+	}, true);
+	else if (withConfigLock(() => {
+		if (r.kind === "android" && deviceSlotPlatforms(getProject(r.project), r.slot)?.android?.owned) return false;
+		return clearDevice(r.project, r.kind, r.slot, r.id);
+	})) console.log(chalk.green(`Cleared the ${r.kind} record for ${r.project} (${r.id} is not on this machine)`));
 	return deleteFailures;
 }
 //#endregion
@@ -932,7 +943,7 @@ function malformedRemoteSessionLockNotice(roots) {
 	for (const root of roots) {
 		const lockPath = join(workspaceDir(root), "remote-session.lock");
 		if (!existsSync(lockPath)) continue;
-		if (readClaimSet(lockPath).unresolved.length === 0) continue;
+		if ((0, ownership_claim_exports.readClaimSet)(lockPath).unresolved.length === 0) continue;
 		return `EAS session sweep skipped: the remote-session lock at ${lockPath} has a malformed owner record.`;
 	}
 	return null;
@@ -1154,7 +1165,7 @@ function unresolvedLockLines(locks, slots) {
 		"              remove one yourself once you know nothing is building with it"
 	];
 }
-function formatGcReport({ skipped = [], deadProjects = [], invalidProjects = [], parkedSims = [], parkedAvds = [], orphanedDevices = [], staleDevices = [], staleDeviceRecords = [], buildLocks = {
+function formatGcReport({ skipped = [], deadProjects = [], orphanedPorts, invalidProjects = [], parkedSims = [], parkedAvds = [], orphanedDevices = [], staleDevices = [], staleDeviceRecords = [], buildLocks = {
 	stale: [],
 	live: [],
 	unresolved: []
@@ -1187,6 +1198,7 @@ function formatGcReport({ skipped = [], deadProjects = [], invalidProjects = [],
 	}
 	lines.push(...projectEntryLines(`Dead project entries (${deadProjects.length}):`, deadProjects));
 	lines.push(...projectEntryLines(`Invalid project entries (${invalidProjects.length}) - the key is not an absolute path:`, invalidProjects));
+	lines.push(...namedPortLines(orphanedPorts));
 	lines.push(...formatParkedSimReport(parkedSims, now));
 	lines.push(...formatParkedAvdReport(parkedAvds, now));
 	if (orphanedDevices.length) {
@@ -1292,6 +1304,14 @@ function leaseGarbageLines({ expired, kept }) {
 function deviceSizeSuffix(device) {
 	return device.kind === "android" && device.bytes !== void 0 ? ` - ${formatBytes(device.bytes)} on disk` : "";
 }
+function namedPortLines(ports = []) {
+	if (!ports.length) return [];
+	return [
+		`Orphaned named ports (${ports.length}):`,
+		...ports.map(({ project, label, port }) => `  ${project}: ${label} (${port})`),
+		"              --delete stops TCP listeners and releases these allocations."
+	];
+}
 //#endregion
 //#region src/commands/gc.ts
 function removeInvalidProjectEntries(invalidProjects) {
@@ -1464,6 +1484,11 @@ async function collectGcReport({ olderThan = null, cache = null, now = Date.now(
 	return {
 		skipped,
 		deadProjects,
+		orphanedPorts: deadProjects.flatMap((project) => Object.entries(cfg?.projects[project]?.ports ?? {}).map(([label, port]) => ({
+			project,
+			label,
+			port
+		}))),
 		invalidProjects,
 		parkedSims,
 		parkedAvds,
@@ -1591,7 +1616,16 @@ async function runGcCore(opts, deps) {
 	let deleteFailures = deleteParkedSims(report.parkedSims, deps) + deleteParkedAvds(report.parkedAvds);
 	removeInvalidProjectEntries(invalidProjects);
 	for (const path of deadProjects) {
-		const result = await reclaimProject(path);
+		if (existsSync(path) || !isOnMountedVolume(path)) {
+			console.log(chalk.yellow(`Kept ${path}: its absence can no longer be confirmed.`));
+			continue;
+		}
+		const result = await reclaimProject(path).catch((error) => {
+			deleteFailures++;
+			console.log(chalk.red(`Could not prune ${path}; its registry entry was kept: ${error.message}`));
+			return null;
+		});
+		if (!result) continue;
 		if (result.keptEntry) console.log(chalk.yellow(`Could not fully prune ${path}; its registry entry was kept.`));
 		else console.log(chalk.green(`Pruned ${path}`));
 		for (const dir of result.removedWorkspaceDirs) console.log(chalk.dim(`  removed workspace output ${dir}`));
@@ -1606,7 +1640,7 @@ async function runGcCore(opts, deps) {
 	}
 	deleteFailures += deleteProjectDevices(orphanedDevices, staleDevices, staleDeviceRecords);
 	for (const lock of buildLocks.stale) {
-		const cleared = clearFreeClaimSet({
+		const cleared = (0, ownership_claim_exports.clearFreeClaimSet)({
 			root: lock.path,
 			label: `${lock.platform} build`
 		});
@@ -1623,7 +1657,7 @@ async function runGcCore(opts, deps) {
 		console.log(chalk.green(`Cleared the ${lock.platform} build lock left by pid ${lock.pid ?? "?"} (${lock.projectRoot || "unrecorded workspace"})`));
 	}
 	for (const slot of buildSlots.stale) {
-		const cleared = clearFreeClaimSet({
+		const cleared = (0, ownership_claim_exports.clearFreeClaimSet)({
 			root: slot.path,
 			label: "build slot"
 		});

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

@@ -1,4 +1,6 @@
-import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-DEJf6_kJ.mjs";
+import { a as findProjectRoot } from "./project-B_SDt4ip.mjs";
+import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-kO2ZqIKy.mjs";
+import { t as guideStatus } from "./guide-status-BF6RsJJp.mjs";
 import chalk from "chalk";
 //#endregion
 //#region src/guide/index.ts
@@ -65,8 +67,12 @@ 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
+Before native worktree work, run doctor for the platform in scope. The STATUS
+block at the top of this topic says when it is due here: never run in this
+checkout, older than seven days, or run under another Stim version. No block
+means doctor is current and Stim is up to date; the same block names a newer
+Stim release when one exists. Doctor checks the source
+checkout from a linked worktree. Fix relevant findings and inspect the
 upstream gap; in the single-checkout workflow those seed findings do not
 appear. It also prints the running CLI version and the stim installation
 resolved from PATH. If that resolved installation is older than another one,
@@ -153,7 +159,7 @@ RULES DURING THE LOOP
   change does not need one.
 - For stale Metro transforms or file-map state, use stim start --reset-cache.
   It restarts only this app's verified owned Metro, preserving devices and other
-  apps' caches. See guide lifecycle for reset scope and Expo requirements.
+  apps' caches. See guide lifecycle for reset scope.
 - Reload is not part of the normal workflow. Use stim reload on an owned local
   simulator or emulator when an error screen remains after the fix, and on
   Android after a failed first bundle load. It reloads JavaScript and never
@@ -226,8 +232,10 @@ shut down the phone or uninstall the app.
 
 Treat a refusal as an ownership or state mismatch: read its code and remedy.
 Never reach for --force first.
-Stim leaves externally started servers alone. Stop them with their original
-tool; neither a matching port nor --force grants process ownership.
+Stim leaves externally started Metro servers alone. Stop them with their original
+tool; neither a matching Metro port nor --force grants process ownership.
+Named ports are separate: ports stop kills TCP listeners on the workspace's
+reserved named ports, even outside the workspace. Read guide ports before use.
 
 Ask the user before these actions:
 
@@ -266,6 +274,7 @@ Read the matching guide before acting in these situations:
 | 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     |
+| Web or API server ports                              | stim guide ports                 |
 | 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 |
@@ -301,6 +310,7 @@ FULL TOPIC LIST
   stim guide lifecycle release    # Release configurations and ...Release variants
   stim guide facts                # the --json payloads
   stim guide facts devmenu        # the Expo dev menu or Tools button over the app
+  stim guide ports                # named ports for web and API servers
   stim guide metro                # supervisor, custom Metro, tunnels, and remote devices
   stim guide logs                 # filters, record shape, and capture limits
   stim guide cleanup              # what reclaims a device, and what deletes
@@ -896,6 +906,58 @@ STARTING YOUR OWN BUNDLER STILL WORKS
 
   \`stop\` leaves an externally started server running. Stop it with the tool
   that started it.`
+	},
+	ports: {
+		summary: "Workspace ports for web and API servers that Stim does not manage",
+		body: () => `NAMED SERVER PORTS
+
+If Stim is not installed globally, replace stim with npx stim.
+
+  stim ports get web
+  pnpm exec vite --port "$(stim ports get web)" --strictPort
+  stim ports
+  stim ports stop web --dry-run
+  stim ports stop web
+  stim ports release api
+
+get <label> allocates on first use and prints only the number to stdout.
+Repeated calls reuse it, even while a server is listening. Labels start with
+a letter and contain up to 64 letters, digits, underscores, or hyphens.
+metro is reserved; use stim start and stim stop for managed Metro.
+
+New allocations scan TCP ports 8900-8999. They skip registry reservations
+and existing listeners, announcing occupied ports and upward retries on
+stderr. Allocation requires lsof. All 100 ports occupied or reserved is a
+refusal; stop or release unused allocations in their owning workspaces.
+
+The machine registry, under STIM_HOME, serializes allocation and cleanup.
+The workspace is the nearest package.json directory, resolved through
+symlinks. Use the same package directory for every command in a monorepo.
+The allocation reserves a number, not a listening socket. Another process
+can bind it before your server does. Use strict-port behavior when supported
+and verify the server bound the number supplied. Stim does not start,
+supervise, or capture logs for these servers.
+
+ports lists named labels and ports, plus Metro marked managed.
+ports stop [label] kills TCP listeners on those named ports and releases
+the allocations. It sends SIGTERM, waits two seconds, then SIGKILL if needed.
+It prints the PID and command for each stopped process. The listener's cwd
+can be anywhere: the named reservation is permission to stop that listener.
+Reserve only services this workspace may stop. --dry-run prints what would
+be stopped and released, without doing either. A failed inspection or stop
+keeps that allocation for retry; other labels are still processed.
+ports release [label] releases without signalling a process.
+Omitting the label selects every named port, never Metro. stim stop leaves
+named ports alone.
+
+worktree remove stops named listeners and releases their allocations.
+gc reports allocations whose workspace no longer exists; gc --delete stops
+and releases them. Unmounted or unresolved workspace paths are retained.
+Failed stops keep the registry entry. Use the same current Stim version for
+cleanup: versions without ports do not know about named allocations.
+
+A shared API does not get a shared reservation. Pass its port by environment
+instead of allocating a separate label in every worktree.`
 	},
 	logs: {
 		summary: "Querying the merged NDJSON timeline, and what --errors means",
@@ -1401,7 +1463,7 @@ code, never on the message.`,
   run the command again.`
 			},
 			STIM_CLAIM_REFUSED: {
-				summary: "a build lock exists whose holder cannot be identified; Stim neither removes it nor waits on it",
+				summary: "an ownership claim blocks the operation; inspect its holder before removing an unresolved claim",
 				body: () => `STIM_CLAIM_REFUSED
   A build lock records the holder's process IDENTITY, not just its pid, so a
   recycled pid reads as a gone builder rather than a live one, and a builder
@@ -1420,7 +1482,26 @@ code, never on the message.`,
   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.`
+  An existing backup prompts before overwriting; preserve both files.
+  Android creation, recovery and teardown use per-AVD claims under
+  ~/.stim/avd-locks. Creation records the avdmanager process group, so a claim
+  left by a killed creator becomes recoverable after that group exits. Retry
+  after a live creator or cleanup finishes. An interruption before the child
+  is recorded, or during synchronous teardown, can leave no verifiable
+  identity: inspect the named claim and confirm that neither Stim nor its
+  avdmanager or adb child is still using the AVD before removing only that
+  claim. Keep the AVD and its incomplete workspace record. Once the claim is
+  safe to clear, retry \`stim android\` to reconcile incomplete setup through
+  owned-device teardown. GC and project removal refuse while the claim is
+  live or unresolved.
+  Parked-device adoption and deletion use claims under $STIM_HOME/pool-locks.
+  If a holder dies during a synchronous native callback, its child cannot be
+  identified and the device stays protected, including from older CLIs through
+  an opaque inline marker. Verify that the old Stim process
+  and its native children have finished before removing the named claim.
+  Legacy inline \`deletionClaim\` fields in config.json have no process
+  identity and require separate manual inspection; \`stim guide lifecycle pool\`
+  describes their field-only recovery.`
 			},
 			STIM_CLAIM_UNAVAILABLE: {
 				summary: "a process identity or warm claim store is unavailable, so the protected operation refuses",
@@ -2062,8 +2143,21 @@ captured"  (in metro.ndjson, bare RN)
 "Timed out waiting for the lock at <path>."
   Short directory locks serialize writes to config, workspace state, device
   leases, ownership records, metadata, and cache manifests. The path identifies
-  the lock. A lock older than 10s is taken over automatically. Wait for the
-  command holding it; if none is running, remove the named directory.`
+  the lock. These locks wait up to 12s and never expire based on age. Wait for
+  the command holding it; if none is running, remove the named directory.
+  Short locks use the same process-identity claims as long operations, stored
+  beside the visible directory at <path>.claims. An opaque marker in the visible
+  directory also excludes older Stim versions. Only the exclusive claim holder
+  can recover a recognized marker. A
+  complete claim left by a proven-dead owner is recovered automatically on
+  the next attempt. An unreadable or undecodable record instead reports
+  STIM_CLAIM_REFUSED and names the claim to inspect; an unavailable native
+  identity reports STIM_CLAIM_UNAVAILABLE without running the protected work.
+  Older lock directories have no process identity. A visible directory left
+  empty before marker publication or during final removal also cannot prove it is free.
+  These paths still time out; verify that no holder is running before removing
+  only the named directory. Standalone Metro and Expo cache packages use the
+  same core protocol and do not require the Stim CLI.`
 			},
 			teardown: {
 				summary: "an unmanaged port, an unverified supervisor, and a failed device teardown",
@@ -2337,12 +2431,11 @@ a seed belongs to this workflow.
 
   # If stale Metro transforms or file-map state require recovery:
   stim start --reset-cache
-  # Restarts only this app's verified owned Metro, retaining its port/devices.
-  # Uses a fresh persistent cache namespace, not deletion of shared cache files.
-  # Other apps and worktrees keep their caches. Subsequent starts reuse the new
-  # namespace; another reset changes it again. Native build caches are unchanged.
-  # Expo requires SDK 54+ and Stim's config adapter. Custom file-map cache
-  # managers must honor Metro's fileMapCacheDirectory for file-map invalidation.
+  # Restarts only this app's verified owned Metro, retaining its port/devices,
+  # with Metro's own reset (resetCache on a bare server, expo start --clear).
+  # That clears every store in the app's Metro config, including this app's
+  # shared transform store, so other worktrees of the SAME app rebuild their
+  # transforms too. Other apps and native build caches are unchanged.
 
   # 3. Owned device booted, native inputs fingerprinted, cached build
   #    installed (or built), app launched wired to port 8082, device-log
@@ -2820,6 +2913,22 @@ result as proof instead of requiring an unrelated screenshot.`
   retry it. The reported pool can temporarily exceed the bound rather than
   orphaning a simulator.
 
+  Adoption and deletion share a process-identity claim for each parked iOS
+  simulator or Android emulator under $STIM_HOME/pool-locks. A live owner
+  excludes both operations. A proven dead or different owner is recovered on
+  the next attempt, unless it may have left native work running. Deletion also
+  puts an opaque marker on the pool record so older Stim versions keep it
+  protected. New versions resolve that marker through the same identity claim.
+  A crash during a synchronous device-tool call leaves that work unverifiable; inspect
+  the old process and its native children before following the claim's removal
+  remedy. See \`stim guide errors STIM_CLAIM_REFUSED\`.
+
+  Older inline \`deletionClaim\` markers contain only a pid and stay protected,
+  even when that pid is absent. After verifying that neither the old Stim
+  process nor its native child is using the device, remove only that parked
+  record's \`deletionClaim\` field from config.json, then retry. Keep the pool
+  record and device; do not remove the whole config.
+
   and an adopting run says so where a plain boot would say \`booted\`:
 
     device      stim-app-412 (iPhone 17 26.5) (9C1F..) adopted (11s)
@@ -2863,6 +2972,14 @@ result as proof instead of requiring an unrelated screenshot.`
   When a fresh AVD's preferred name belongs to another workspace or a parked
   entry, Stim adds a short suffix instead of taking over that device. Always
   use the actual device name and serial reported by the platform command.
+  Creation reserves the owned AVD before running native tools, so other
+  workspaces can update config while GC and teardown retain that reservation.
+  Interrupted creation keeps an incomplete record and protects its recorded
+  native process group until it exits. Retry \`stim android\` for owned-device
+  cleanup and recreation; a live or unresolved per-AVD claim
+  refuses cleanup. Follow \`stim guide errors STIM_CLAIM_REFUSED\` before
+  manually clearing a claim, and keep the AVD data while its process state
+  cannot be verified.
 
   Android cleanup happens AFTER boot, before install or launch: \`adb shell
   pm clear\` clears the adopting app's data while retaining its APK, and
@@ -3881,6 +3998,13 @@ to stats.json.corrupt-<unix ms> and starts a new one.`,
   branches stay. A branch with an existing Stim ownership record is deleted
   only when it has no unique commits.
 
+NAMED SERVER PORTS
+  worktree remove stops TCP listeners on each named allocation and releases
+  the ports. gc reports named allocations for missing workspaces; gc --delete
+  stops their listeners and releases them. Unmounted or unresolved paths stay
+  registered. Failed stops retain their allocations for a later retry.
+  stim stop does not touch named ports. See guide ports.
+
 ON THE SOURCE CHECKOUT
   git cannot remove a repository's main working tree, and deleting the source
   checkout is not what anyone meant -- so there, and only there,
@@ -4700,10 +4824,17 @@ function renderIndex(version) {
 	lines.push("", "Read one with:  stim guide <topic>   (sectioned topics: stim guide <topic> <section>)");
 	return lines.join("\n");
 }
-function guideCommand(program, version) {
-	program.command("guide [topic] [section]").description("Print reference documentation for THIS version of Stim (topics: " + topicNames().join(", ") + "). A topic with sections prints its section index; name a section to print only it, e.g. `stim guide errors STIM_NO_METRO` or `stim guide lifecycle builds`. Generated by the binary, so it cannot drift from the installed CLI.").action((topic, section) => {
+function guideCommand(program, version, status = (running) => guideStatus({
+	projectRoot: findProjectRoot(process.cwd()),
+	running
+})) {
+	program.command("guide [topic] [section]").description("Print reference documentation for THIS version of Stim (topics: " + topicNames().join(", ") + "). A topic with sections prints its section index; name a section to print only it, e.g. `stim guide errors STIM_NO_METRO` or `stim guide lifecycle builds`. Generated by the binary, so it cannot drift from the installed CLI.").action(async (topic, section) => {
+		const withStatus = async (body) => {
+			const block = await status(version);
+			return block ? `${block}\n\n${body}` : body;
+		};
 		if (!topic) {
-			console.log(renderIndex(version));
+			console.log(await withStatus(renderIndex(version)));
 			return;
 		}
 		const body = renderTopic(topic);
@@ -4715,7 +4846,7 @@ function guideCommand(program, version) {
 			process.exit(1);
 		}
 		if (!section) {
-			console.log(body);
+			console.log(topic === "agent" ? await withStatus(body) : body);
 			return;
 		}
 		const index = renderSectionIndex(topic);