stim 1.3.0 → 1.4.0

package/dist/{guide-92CPA21s.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
@@ -62,6 +62,8 @@ warm checks for existing entries before copying, not during the copy. Do not
 edit files, install dependencies, or run another warm in that worktree until
 it finishes; concurrent files can be overwritten or removed.
 If warm fails or reports incomplete, resolve the reported failure first.
+A warm that cannot record its ownership claim refuses before copying. Follow
+the printed remedy and keep concurrent runs on the same STIM_HOME.
 
 Before native worktree work, run doctor for the platform in scope. It checks
 the source checkout from a linked worktree. Fix relevant findings and inspect the
@@ -80,6 +82,12 @@ current and highest observed pressure; a timeout does not establish OOM.
 Avoid repeated reboots under unchanged pressure; do not restart other
 workspaces' devices or close their apps without asking. That guide covers
 the recovery steps and profile tradeoffs.
+An Android boot timeout under observed elevated memory pressure gets one
+extra wait while the emulator process this run started is alive. It never
+launches a second emulator. For a timeout, read guide errors STIM_NO_DEVICE
+and free memory by stopping only unneeded devices in workspaces you own;
+ask before closing other apps or devices. Device count alone is not evidence
+of memory pressure.
 For a linked native library carrying Git metadata, add the printed .git entries to
 .fingerprintignore only when the native build does not read Git state.
 
@@ -180,8 +188,9 @@ RULES DURING THE LOOP
 - A clean logs --errors check requires exit code 0 AND no matching errors in
   captured logs. Exit code 0 alone means the query succeeded, even when errors
   were printed. Human output shows "No matching log records" on stderr for
-  zero matches; JSON mode prints zero bytes. This does not prove launch or log
-  capture succeeded. Do not read the NDJSON files directly.
+  zero matches; JSON mode prints zero bytes. A workspace with no captured
+  timeline refuses with STIM_NO_PROJECT and, in a monorepo, names the nearest
+  registered descendant app with logs. Do not read the NDJSON files directly.
 - Use stim status when resuming a workspace or recovering missing device,
   port, server, or build facts. A normal start and platform run already print
   them. Use stim doctor when a build is unexpectedly slow or the environment
@@ -196,6 +205,8 @@ the stim-<label> (<model> <runtime>) name. Never point Stim at a user-created
 emulator or simulator.
 
 worktree remove parks the workspace's simulator or emulator for later adoption.
+Before owned-device teardown, Stim best-effort closes local agent-device sessions
+on that exact device; failures warn and teardown continues (guide cleanup).
 A parked device is Stim-owned: never delete one by hand. gc --delete clears verified
 entries and keeps failures; see guide lifecycle pool. First launch on a
 physical iPhone can need the one-time taps named by the remedy.
@@ -215,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:
 
@@ -255,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 |
@@ -290,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
@@ -885,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",
@@ -898,10 +965,12 @@ discovered, not enumerated.
 
 EXIT 0 MEANS THE QUERY SUCCEEDED, whether or not records matched. A clean
 \`stim logs --errors\` check requires exit code 0 AND no matching errors in
-captured logs. An empty result does not prove launch or log capture succeeded;
-a workspace with no log directory also returns an empty result.
+captured logs. A workspace that has never produced a timeline refuses with
+STIM_NO_PROJECT instead of passing with an empty result. In a monorepo the
+refusal names the nearest registered descendant app with logs, when there is one.
 
-For zero matches: STDOUT IS EMPTY, exit code 0, and
+Once a timeline file exists, zero matches after filtering means STDOUT IS EMPTY,
+exit code 0, and
 one dim note on STDERR reading \`No matching log records in <logs dir>\`
 (human mode only -- \`--json\` prints nothing at all, on either stream).
 The only exit-1 paths are a malformed query and no project.
@@ -1388,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
@@ -1404,14 +1473,32 @@ code, never on the message.`,
   \`worktree warm\` reports it for the repository-wide warm claim under
   ~/.stim/warm-locks on both paths, including a \`--refresh\` that spawned its
   install and was killed before recording which process: nothing was refreshed
-  and nothing was copied. One case is NOT this code for a plain warm: a
-  STIM_HOME (or a warm-locks path under it) that is a file rather than a
-  directory. No claim can be stored there at all, which is a filesystem state
-  that predates claims, so plain \`warm\` degrades to the unsynchronised copy it
-  performed before them and \`--refresh\` still refuses.`
+  and nothing was copied. A STIM_HOME or warm-locks ancestor that is a file
+  also refuses. The message names that blocking path and prints a shell-quoted
+  move-aside command. Inspect it first: the file may contain unrelated data.
+  An existing backup prompts before overwriting; preserve both files.
+  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: "this process has no recordable identity, so no build lock or build slot can be taken at all",
+				summary: "a process identity or warm claim store is unavailable, so the protected operation refuses",
 				body: () => `STIM_CLAIM_UNAVAILABLE
   Every ownership claim records the holder's process identity, captured through
   the \`unique-pid\` native module. This code is that capture failing: no
@@ -1423,16 +1510,15 @@ code, never on the message.`,
   the same fingerprint while each believed it was alone. Reinstall Stim so the
   module for this platform is present, then run the command again. Nothing was
   built, installed or removed.
-  \`worktree warm --refresh\` refuses for the same reason, because it writes to
-  the source checkout. Plain \`worktree warm\` does NOT: it prints one dim
-  \`lock        unavailable (...)\` line and copies unsynchronised. A copy only
-  reads, so running it with no claim is what it did before the lock existed,
-  while refusing it would break a warm that works today -- an unwritable
-  STIM_HOME included.
-  It still reads the claim set first, which takes no claim: a live \`--refresh\`
-  claim, or a claim it cannot resolve, makes even the unsynchronised copy
-  refuse, and the line names what it found. Only a repository nothing is
-  warming is copied without a claim.`
+  Both plain \`worktree warm\` and \`worktree warm --refresh\` refuse before
+  copying for the same reason. A copy without a claim would be invisible to a
+  refresh starting after it, allowing the source dependencies to change while
+  they are read.
+  Warm also reports this code for EACCES, EPERM, EROFS and ENOENT while taking a claim.
+  The message names the claim path and original filesystem error. Restore write
+  access to the existing claim store, checking parent permissions, symlink
+  targets, mount access and sandbox rules, then retry. Do not switch STIM_HOME to evade a claim:
+  concurrent runs must coordinate through the same store.`
 			},
 			STIM_INSTALL_FAILED: {
 				summary: "simctl, adb, or devicectl refused the artifact; the one signer-conflict retry",
@@ -1717,6 +1803,20 @@ so a Debug run on one is wired to a LAN origin instead of localhost.`,
   normally live under ~/.android/avd, and a booted AVD can use several GB. A
   boot whose emulator process exited is also reported at once rather than after
   the full cold-boot timeout.
+  Before a local Android emulator boot, a memory phase line reports observed
+  warning or critical macOS host memory pressure. If the initial boot wait
+  times out under that pressure and the process this run started is still
+  alive, Stim retries the WAIT once for up to 240 seconds more on the same
+  serial; it never starts a second emulator. New-device preparation normally
+  waits 120 seconds first; the later boot check waits 240 seconds. There is
+  no extra wait for normal or unavailable pressure, a process that exited,
+  or a process whose liveness this run cannot check. adb probes are bounded;
+  final diagnostic queries share a separate budget of up to five seconds.
+  A timeout remedy reports observed pressure and the running owned-device
+  count when available. Device count alone does not establish memory pressure
+  or trigger the extra wait. Stop an unneeded device with \`stim stop\` only
+  in a workspace you own, then retry \`stim android\`; ask before closing
+  other apps or devices. Specific emulator log errors retain their remedies.
 
 "this project's sim is X, but --device-type asked for Y"
   The project already owns a simulator of a different model, and Stim will
@@ -1984,7 +2084,9 @@ captured"  (in metro.ndjson, bare RN)
   with no package.json above it, or one whose nearest package.json does not
   parse or depends on neither react-native nor expo, so the directory is not
   an app (the refusal names that package.json and says which of the two it
-  is; \`doctor\` reports the same directory as a finding), an
+  is; \`doctor\` reports the same directory as a finding), a \`logs\` query in
+  a workspace that has never produced a log timeline (the refusal names the
+  nearest registered descendant app with logs when one exists), an
   android/app/build.gradle that declares product flavors with
   no variant selected (the refusal names the debug variants), or a
   \`--device-type\`, \`--runtime\` or \`--system-image\` name that is BLANK or
@@ -2035,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",
@@ -2142,24 +2257,14 @@ not on any remote"  (worktree remove)
   which is usually the repository root, so every app of it reads the same one.`
 			},
 			warm: {
-				summary: "two warm refusals whose text is incomplete, known and not fixed",
-				body: () => `"Could not warm this worktree: EACCES: permission denied, mkdir
-'<home>/warm-locks/<name>.lock'"  (worktree warm --refresh)
-  A STIM_HOME that \`--refresh\` cannot write. The refusal itself is right -- it
-  writes to the source checkout, so it will not run without a claim -- but it
-  carries no \`failed: <CODE>\` line, because EACCES is not a Stim code, and no
-  fix line. Make STIM_HOME writable, or set STIM_HOME to somewhere writable,
-  then run it again. A plain warm degrades in this state rather than refusing.
-
-"... the claim path is a file, not a claim directory", with a \`rm -rf\` that
-changes nothing  (worktree warm --refresh)
-  When \`$STIM_HOME/warm-locks\` or STIM_HOME itself is a regular FILE, the
-  refusal names \`warm-locks/<name>.lock\` -- a path that cannot exist under a
-  file -- so running the printed removal does nothing and the next run refuses
-  identically. Remove the file that is in the way and run it again. A plain
-  warm copies unsynchronised in this state.
-
-  Both are documented rather than fixed: appandflow/stim#696.`
+				summary: "worktree warm claim storage refusals and recovery",
+				body: () => `Both plain warm and --refresh require an ownership claim.
+  Permission-denied or read-only claim storage reports STIM_CLAIM_UNAVAILABLE
+  and names the path. Restore access to the existing claim store and retry.
+  A non-directory claim ancestor reports STIM_CLAIM_REFUSED and names the
+  blocking file. Inspect it and use the printed move-aside command to preserve
+  its contents before retrying. See guide errors STIM_CLAIM_UNAVAILABLE and
+  guide errors STIM_CLAIM_REFUSED for the recovery details.`
 			},
 			carry: {
 				summary: "worktree warm copy results, lockfile mismatches, and remedies",
@@ -2340,6 +2445,7 @@ a seed belongs to this workflow.
   #    For a clean check, require exit 0 AND no matching errors.
   #    Human mode prints "No matching log records" on stderr for zero matches.
   #    Exit 0 alone means the query succeeded, even when it printed errors.
+  #    A workspace with no captured timeline refuses with STIM_NO_PROJECT.
   stim logs --errors
 
   # 5. Edit the JS. Fast Refresh applies it; no Stim command is involved.
@@ -2435,6 +2541,12 @@ ANDROID EMULATOR RESTARTS
   Rerun \`stim android\` with the same build options in that workspace to restore Metro
   forwarding, then reopen agent-device on the serial that run reports.
   Other workspaces' simulators and automation sessions remain theirs.
+  A local emulator boot reports observed warning or critical macOS memory
+  pressure before starting. A timeout under elevated pressure gets one
+  additional wait of up to 240 seconds only while the process this run
+  started is alive. Stim keeps waiting on the same emulator; it never
+  launches a duplicate. See \`stim guide errors STIM_NO_DEVICE\` for the
+  wait windows, diagnostics, and recovery steps.
 
 DESTRUCTIVE COMMANDS -- ask the user first
   gc --delete             deletes orphaned stim-* devices, tens of GB
@@ -2707,9 +2819,11 @@ result as proof instead of requiring an unrelated screenshot.`
 
   \`--refresh\` always prints a \`lock\` line, then its own facts, one per
   step, before those. A plain warm prints the \`lock\` line only when its copy
-  actually waited for another warm:
+  actually waited for another warm. A current refresh reports
+  \`lock        acquired shared (seed current)\`; a refresh needing changes
+  reports \`acquired exclusive\` with the reason from its initial check:
 
-    lock        acquired (waited 12s for stim worktree warm --refresh pid 41233) -- stim guide lifecycle options
+    lock        acquired exclusive (fast-forward 2 commits) (waited 12s for stim worktree warm --refresh pid 41233) -- stim guide lifecycle options
     checkout    janic/wip 2 commits behind origin/janic/wip -> fast-forwarded to 4b81e0c
                 not the default branch (main); worktrees seeded from this copy
                 carry janic/wip's dependencies
@@ -2794,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)
@@ -2837,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
@@ -3129,6 +3267,20 @@ WHAT MAKES THE CACHE ACTUALLY HIT: .FINGERPRINTIGNORE
   Never ignore a real native input -- a Podfile, a gradle file, the app config
   -- to force a hit: that trades a slow build for a wrong one.
 
+
+  React Native Test App can generate checkout-specific Android output under
+  node_modules/react-native-test-app/android/support/build. If fingerprint
+  differences point only there, add these project-specific entries:
+
+    node_modules/react-native-test-app/android/support/build
+    node_modules/react-native-test-app/android/support/build/**/*
+
+  Put them in the app root's .fingerprintignore and use the path as it appears
+  in the fingerprint sources; a hoisted or linked dependency may differ.
+  Keep android/support/build.gradle and native sources included. Confirm equal
+  fingerprints across built worktrees, and confirm a real native input edit
+  still changes the hash. These exclusions are not Stim defaults.
+
   \`stim doctor\` measures this directly rather than reading the file: it
   fingerprints HEAD in a temporary clean worktree, compares, and reports a
   mismatch naming the differing sources. Untracked, non-gitignored files under
@@ -3274,8 +3426,9 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   Running it in the source checkout refuses.
 
   \`--refresh\` WRITES TO THE SOURCE CHECKOUT before the copy, which is why it
-  is opt-in: it fetches, fast-forwards whatever branch is checked out there to
-  its \`@{upstream}\`, and installs what the new commits moved. It refuses a
+  is opt-in: it checks the upstream, fetches changes when needed, and fast-forwards
+  whatever branch is checked out there to its \`@{upstream}\`, and installs
+  what the new commits moved. It refuses a
   source checkout it cannot move -- uncommitted changes to tracked files or a
   rebase or merge in progress (STIM_MAIN_DIRTY), a detached HEAD
   (STIM_MAIN_DETACHED), or a branch that is both ahead and behind
@@ -3309,9 +3462,15 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   writes no failure anywhere -- is recovered the same way a failed one is.
 
   One lock per repository serialises this, whether or not you pass the flag:
-  \`--refresh\` holds it exclusively, and every copy holds it shared, so a copy
-  can never read a node_modules a refresh is rewriting. Two plain warms of the
-  same repository run together. The lock is keyed on the repository root, so
+  \`--refresh\` first checks under a shared claim. It uses \`git ls-remote\`
+  to compare the upstream's advertised commit with the local tracking ref without
+  updating Git refs or FETCH_HEAD. When the checkout, dependencies and Pods are
+  current, it keeps that shared claim through the copy, overlapping other copies.
+  A changed or unconfirmed upstream, fast-forward, dependency install or Pods
+  install requires an exclusive claim. It releases shared before waiting for
+  exclusive, then checks the checkout again before fetching or writing. Every
+  copy holds shared, so no copy reads a node_modules a refresh is rewriting.
+  The lock is keyed on the repository root, so
   two apps of one monorepo share it. It is the same ownership claim the build
   locks take: the holder's process IDENTITY decides, so a holder that dies frees
   it, a recycled pid cannot keep it, and a refresh whose install runs in a
@@ -3319,20 +3478,13 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   holder every 30s and gives up with STIM_LOCK_TIMEOUT; a claim Stim cannot
   resolve refuses with STIM_CLAIM_REFUSED and names the removal rather than
   waiting on it or removing it.
-  A plain warm that cannot record a claim at all -- an unwritable STIM_HOME, a
-  STIM_HOME on a read-only mount or under a dangling symlink, a STIM_HOME that
-  is a file, or no \`unique-pid\` build for this platform
-  (STIM_CLAIM_UNAVAILABLE) -- says so in one dim line and copies without it,
-  exactly as it did before the lock existed, because a copy only reads.
-  \`--refresh\` refuses instead, because it writes. Before that unsynchronised
-  copy starts, warm still READS the claim set, which needs no claim of its own:
-  if a refresh holds this repository, or a claim in it cannot be resolved, the
-  copy refuses rather than reading a tree that is being rewritten. That read is
-  not a lock, so a refresh that starts after it is not covered; it closes the
-  window in which one is already installing. Closing the rest needs a claim,
-  which is the one thing that state cannot record, so the residual is
-  documented rather than fixed (appandflow/stim#696), as is the
-  \`acquired (waited 0s ...)\` a contended-but-fast wait prints.
+  Both plain warm and --refresh refuse before copying when no claim can be
+  recorded. Missing process identity, denied write access and read-only storage
+  report STIM_CLAIM_UNAVAILABLE with recovery instructions. Restore access to the
+  same claim store before retrying; choosing a different STIM_HOME would hide
+  concurrent warm operations. A non-directory claim path reports
+  STIM_CLAIM_REFUSED and names the blocking file with a move-aside command that
+  preserves its contents. Sub-second waits omit the elapsed-time suffix.
 
   Wait for warm to exit successfully (exit code 0) before running start,
   ios, android, or a dependency install in that worktree. If a shell tool
@@ -3814,6 +3966,16 @@ Those are the only two commands that delete. \`stim stop\` shuts a device
 DOWN and leaves it assigned, which is what makes returning to a branch cost a
 boot rather than a create, a provision and a reinstall.
 
+Before shutting down, parking or deleting an owned device, Stim best-effort
+closes local agent-device sessions bound to its exact iOS UDID or live Android
+serial. It rechecks device ownership and uses agent-device's rejecting session
+target guard; sessions on other devices stay open. Physical devices are outside
+this cleanup. agent-device is optional: a missing binary skips this step, and a
+failed or timed-out list/close prints a device line on stderr while teardown
+continues. Cleanup allows at most 15 seconds of agent-device calls per device.
+A local daemon that cannot use socket transport or a CLI without the target guard
+skips cleanup with a warning; no remote daemon is used.
+
 Neither touches $STIM_HOME/stats.json: \`gc\` never reports or trims the run
 counters \`stats\` prints, and there is no reset flag. Delete that one file to
 start the counters over. A file this version cannot read -- unparseable, or
@@ -3831,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,