stim 1.3.1 → 1.4.0

package/dist/{error-diagnostics-DwhNBFDU.mjs → error-diagnostics-_VmkqRZo.mjs}

@@ -1,12 +1,13 @@
 import { t as getExecutor } from "./exec-CyylIdq9.mjs";
-import { I as deviceSlotKey, L as deviceSlotPlatforms, f as getProject, k as withDirLock } from "./config-CcefMY2Q.mjs";
-import { f as readWorkspaceLaunches, p as readWorkspaceState } from "./state-B3XA2wp2.mjs";
+import { D as withDirLock, F as deviceSlotPlatforms, P as deviceSlotKey, f as getProject } from "./config-6vdGngKa.mjs";
+import { r as readWorkspaceState } from "./workspace-state-Do1e2mOH.mjs";
+import { d as readWorkspaceLaunches } from "./state-CDbvmZdt.mjs";
 import { n as deviceConsoleLevel } from "./ios-device-D3pzTKQE.mjs";
-import { i as resolveProjectMetro } from "./metro-CORqXyTL.mjs";
+import { i as resolveProjectMetro } from "./metro-DFLmaVz8.mjs";
 import { n as parseLogcatLine, t as androidClockOffset } from "./android-BW8i_YxU.mjs";
-import { _ as launchErrorPreview } from "./command-output-8wHMEde0.mjs";
-import { n as androidHome } from "./android-hMj83VpN.mjs";
-import { a as parseLease, n as fileLeaseIo, t as deviceLeasePath } from "./device-lease-CJwK7OZr.mjs";
+import { _ as launchErrorPreview } from "./command-output-BuIb_ZOI.mjs";
+import { n as androidHome } from "./android-BkM4qTaN.mjs";
+import { a as parseLease, n as fileLeaseIo, t as deviceLeasePath } from "./device-lease-DDJr85OK.mjs";
 import { l as readLogRecords, t as attachExpoErrorContext } from "./logs-query-Cdp5aaCH.mjs";
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { createHash, randomUUID } from "node:crypto";

package/dist/{gc-BRu62v4o.mjs → gc-0AyxmECv.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-6vdGngKa.mjs";
+import { i as registeredCaches } from "./cache-manifest-D02TpYjA.mjs";
+import { h as workspaceDir, y as workspaceStateFile } from "./workspace-state-Do1e2mOH.mjs";
+import { _ as repoRoot, s as gitCommonDir } from "./worktree-DWNx4tUg.mjs";
+import { a as findProjectRoot, i as detectIsExpo } from "./project-CBFCwnN5.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-BkM4qTaN.mjs";
+import { A as resolveSettings, N as settingShapeErrors, a as SETTING_SHAPE_REMEDY } from "./settings-DwfltIXQ.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-KsPpvldq.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-DDJr85OK.mjs";
+import { n as listBuildSlots } from "./build-slots-D6sDzOe-.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-CMfHhoc8.mjs";
+import { n as reclaimProject, t as describeDereferenced } from "./reclaim-DpDVo-AP.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-CGxdmQ0K.mjs}

@@ -1,4 +1,4 @@
-import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-DEJf6_kJ.mjs";
+import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-DwfltIXQ.mjs";
 import chalk from "chalk";
 //#endregion
 //#region src/guide/index.ts
@@ -226,8 +226,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 +268,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 +304,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 +900,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 +1457,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 +1476,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 +2137,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",
@@ -2820,6 +2908,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 +2967,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 +3993,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,