stim 1.11.0 → 1.13.0

package/dist/{guide-NDvTmMi-.mjs → guide-BfZ0OmiP.mjs}

@@ -1,6 +1,7 @@
-import { o as findProjectRoot } from "./project-BXZzOABt.mjs";
-import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-B5oFZEri.mjs";
-import { t as guideStatus } from "./guide-status-CWvti2Lg.mjs";
+import { a as findProjectRoot } from "./project-DGeclhvO.mjs";
+import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-xB0Frkg6.mjs";
+import { t as RECENT_LAUNCH_MS } from "./status-sszP4XKU.mjs";
+import { t as guideStatus } from "./guide-status-BaMYu55M.mjs";
 import { SETTINGS_SCHEMA_URL } from "@stim-cli/core/state";
 import chalk from "chalk";
 //#endregion
@@ -80,7 +81,14 @@ other apps or other workspaces' devices.
   stim worktree warm
 
   stim start
-  stim ios                             # or: stim android
+  stim ios                             # or: stim android, or: stim web
+
+For the web target, stim web opens the page in a Stim-owned headless Chrome
+and captures its console and errors in stim logs. It never starts a web
+server: start the dev server first, then run stim web. For Expo web the dev
+server is stim start, and the app needs the react-dom, react-native-web and
+@expo/metro-runtime dependencies. Any other server runs on stim ports get web
+and needs web.url. Read stim guide web first.
 
 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
@@ -177,7 +185,8 @@ RULES DURING THE LOOP
   them. Use stim doctor when a build is unexpectedly slow or the environment
   looks incomplete. If status reports a changed Android serial, rerun stim
   android with the same build options to restore forwarding, then reopen your automation
-  session on the reported serial (guide lifecycle).
+  session on the reported serial (guide lifecycle). Each status issue names a
+  remedy to run from its workspace (guide facts status).
 
 OWNERSHIP AND DELETION
 
@@ -221,7 +230,8 @@ Ask the user before these actions:
 - worktree remove --force, because it also discards uncommitted and untracked
   files.
 - gc --delete, because it deletes orphaned resources, removes clean linked
-  worktrees whose branch is merged, and clears the build outputs of every
+  worktrees whose branch or pull request is merged (or whose pull request
+  was closed), and clears the build outputs of every
   workspace not in use. Run stim gc --json first and show
   the user the entries its sections list (guide facts gc). gc --delete
   --cache all empties the shared build caches and those outputs instead, and
@@ -242,7 +252,11 @@ Run stim stop when you pause or finish a task, and stim worktree remove once
 it is merged or abandoned. Never create a simulator or emulator by hand;
 every device comes from Stim. Before starting a new workspace, check stim
 status for an idle workspace to reuse and confirm capacity headroom instead of
-adding another.
+adding another. Never quit Device Hub or Simulator.app: on Xcode 27
+(confirmed on 27A266a), quitting Device Hub by default shuts down every booted
+simulator on the machine, including ones it never opened a window for and
+ones other workspaces or agents are using. Use stim stop on workspaces you
+own instead.
 
 SANDBOXES
 
@@ -266,7 +280,8 @@ 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                 |
+| Web app in an owned Chrome (stim web)                 | stim guide web                   |
+| 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 |
@@ -310,6 +325,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 web                  # stim web: owned Chrome, page logs, launched, teardown
   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
@@ -318,7 +334,7 @@ FULL TOPIC LIST
   stim guide settings             # configuration files and supported keys`
 	},
 	facts: {
-		summary: "The --json payloads: `start`, `ios`, `android`, `ios|android --plan`, `reload`, `stop`, `status`, `doctor`, `device lock`/`unlock`, `gc`, and the error contract",
+		summary: "The --json payloads: `start`, `ios`, `android`, `web`, `ios|android --plan`, `reload`, `stop`, `status`, `doctor`, `device lock`/`unlock`, `gc`, and the error 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
@@ -327,7 +343,7 @@ Named collector, lease-holder, and launch keys use platform:slot internally.
 
 FACTS CONTRACT
 
-\`start\`, \`ios\`, \`android\`, \`reload\`, \`stop\`, \`status\`, \`stats\`, \`doctor\`,
+\`start\`, \`ios\`, \`android\`, \`web\`, \`reload\`, \`stop\`, \`status\`, \`stats\`, \`doctor\`,
 \`gc\`, and \`device lock\`/\`device unlock\` each print exactly ONE line of JSON on
 stdout for \`--json\`. Every other line goes to stderr, so it is always safe
 to pipe. \`logs --json\` is the one exception: it is NDJSON, one record per
@@ -366,8 +382,11 @@ status runs \`git status --porcelain=v2 --branch\` in every worktree in
 parallel, and caches the merge verdict by HEAD and default-branch commit
 under $STIM_HOME/git-merge. One call starts no new merge check 250 ms after
 its first; later calls judge the rest, and until then a verdict for the same
-HEAD at an older default-branch commit stands in. \`status --watch\` reuses a worktree's git read
-for 5 s. Plain status prints "git: 2 changed, 1 untracked, ahead 3" under
+HEAD at an older default-branch commit stands in; a check that timed out
+is retried after 5 minutes. \`status --watch\` reuses a worktree's git read
+until its index, HEAD, reflog or the branch, upstream or default-branch refs
+change, and for at most 60 s, so a file edit, creation or deletion that is
+not staged can take up to a minute to show. Plain status prints "git: 2 changed, 1 untracked, ahead 3" under
 each environment, and the same after each worktree with no environment.
 
 status's remoteDevices lists each environment's recorded EAS Simulator
@@ -390,7 +409,7 @@ Plain status prints one "remote <platform>: EAS session <id> billable" line
 per session, with the preview URL.`,
 		sections: {
 			payloads: {
-				summary: "every field of the start, ios, android and reload payloads, the error contract, the device rules",
+				summary: "every field of the start, ios, android, web and reload payloads, the error contract, the device rules",
 				body: () => `  stim start --json
 
   port            the Metro port RESERVED for this workspace
@@ -431,13 +450,18 @@ per session, with the preview URL.`,
                   hit 6564e2.. (post-prebuild key)\`), so a cold tree -- a
                   fresh worktree or clone of a CNG app -- installs an entry
                   another workspace already built instead of compiling
-                  beside it. Android also fingerprints after Gradle because
-                  Gradle plugins can rewrite native inputs while they build;
-                  its artifact is stored only under that post-build hash. A
-                  stable second fingerprint prints no shift line. If the iOS
-                  fingerprint after prebuild or pod install, or the Android
-                  fingerprint after Gradle, cannot be computed, the build is
-                  installed but not cached, and fingerprint and cacheKey are null
+                  beside it. Both platforms fingerprint again after the
+                  compile because Gradle plugins can rewrite native inputs
+                  while they build; a change under node_modules/ or the
+                  native directory stores the artifact only under that
+                  post-build hash. A stable fingerprint prints no shift line.
+                  If any other input changed while the build ran (the app
+                  config or a config plugin since the first lookup, other
+                  than the bundle id or package prebuild adds, or any
+                  other source during the compile), or a fingerprint after
+                  prebuild, pod install or the compile cannot be computed,
+                  the build is installed but not cached, and fingerprint and
+                  cacheKey are null
   configuration   the Xcode configuration that was built ("Release" from
                   --configuration or the ios.configuration setting); null for
                   the default Debug
@@ -518,6 +542,12 @@ per session, with the preview URL.`,
                                  finishing
                     "unverified" nothing was observed at all: usually a
                                  dev-client server picker awaiting a tap
+                  Neither "bundling" nor "unverified" is reported for an app
+                  whose process is gone when the bundle timeout closes: the
+                  run fails as FATAL, "the app process exited", with the
+                  device log's errors. An iOS crash report can land a minute
+                  after the crash, so \`logs --errors\` may show the native
+                  stack only later
                   See \`guide facts devmenu\` for the dev menu and its button.
   metroPort       the port the app was wired to; NULL on a non-Debug
                   configuration, whose JS is embedded and which is launched
@@ -615,18 +645,20 @@ per session, with the preview URL.`,
                   reason is "not running" or "stopped (idle)" when the
                   supervisor had stopped it after metro.idleStopMinutes
 
-  stim reload [ios|android] --json
+  stim reload [ios|android|web] --json
 
   Exit 0 and this payload confirm that the reload request was sent. They do
   not prove that new JavaScript loaded or that the screen recovered. The
   command does not observe completion. Verify the expected UI on deviceId
   and inspect stim logs --errors before claiming recovery.
 
-  platform        "ios" | "android"
-  deviceId        the exact owned simulator UDID or emulator serial targeted
-  deviceName      the owned simulator or AVD name
-  appId           the live bundle id or Android package
-  metroPort       the workspace's verified Metro port
+  platform        "ios" | "android" | "web"
+  deviceId        the exact owned simulator UDID or emulator serial targeted;
+                  for web, the owned Chrome's DevTools endpoint
+  deviceName      the owned simulator or AVD name; for web, the Chrome version
+  appId           the live bundle id or Android package; for web, the page URL
+  metroPort       the workspace's verified Metro port; for web, the reserved
+                  Metro port or null
   strategy        how the reload was addressed.
                   "metro-websocket" -- Metro named its clients and Stim
                   addressed every peer matching this platform. A workspace
@@ -636,11 +668,35 @@ per session, with the preview URL.`,
                   the reload went to all of them and Stim cannot confirm appId
                   was among them. Verify the UI on deviceId; if it did not
                   change, reload from the app's own error screen or dev menu
+                  "cdp" -- web: Page.reload on the owned Chrome page, sent
+                  over a DevTools connection verified to reach that Chrome
   targets         how many peers the reload was addressed to, or null when
                   broadcast. Greater than 1 means several devices are running
                   this app on that Metro and the request addressed all of
                   them, not only deviceId. Completion is not observed
 
+  stim web --json
+
+  platform        "web"
+  browser         "chrome"
+  version         the Chrome product, such as "Chrome/153.0.8010.49", or null
+  running         true: the owned Chrome answered and holds the page
+  pid             the owned Chrome's browser process; null when not running
+  supervisorPid   the Stim process holding its DevTools session, or null
+  url             the page opened, web.url with its ports filled in
+  headless        false only with --headed
+  viewport        "desktop" | "phone" (web.viewport)
+  profile         the Stim-owned Chrome user data directory
+  cdpEndpoint     http://127.0.0.1:<port>, the reserved DevTools endpoint, or
+                  null when not running
+  reused          true when the running Chrome navigated again instead of
+                  starting: same --headed, viewport and certificate options
+  launched        true | "bundling" | "unverified" (see \`guide web\`)
+  metroPort       the Metro port the page loads from, or null for a web.url
+                  that does not use {port:metro}
+  logs            { dir }: web.ndjson holds the page records
+  durationMs      wall time of the run
+
   stim doctor --json
 
   project         the resolved app root
@@ -664,7 +720,7 @@ per session, with the preview URL.`,
                   costs-time finding with a PATH or installation remedy
 
 ON FAILURE
-  \`start\`, \`ios\` and \`android\` all print the error contract instead,
+  \`start\`, \`ios\`, \`android\` and \`web\` all print the error contract instead,
   still one line on stdout, and exit 1:
 
     { "code": "STIM_METRO_TIMEOUT", "message": "...", "remedy": "..." }
@@ -689,6 +745,12 @@ ON FAILURE
 
     { "root": "...", "ok": false, "code": "STIM_STOP_BLOCKED", "message": "...", "remedy": "..." }
 
+  device.web is present when the workspace had an owned Chrome:
+  { status, label: "Chrome", kind?, reason?, remedy? }; kind is null when no
+  kind applies. status is "shut-down"
+  when Chrome closed (its profile is kept), else "skipped" (its identity could
+  not be verified) or "failed", and ok is then false.
+
   Branch on \`code\`, never on the message text. \`guide errors\` enumerates
   every code.
 
@@ -805,13 +867,13 @@ RULES
   full commands.`
 			},
 			gc: {
-				summary: "the gc report payload: mode, sections, reasons, failures, and the gc refusals",
+				summary: "the gc report payload: mode, sections, reasons, failures, results, inventory, and the gc refusals",
 				body: () => `  stim gc [--delete] [--older-than <days>] [--cache <name|all|workspaces>]
           [--worktrees] [--idle <duration>] --json
 
   The report the text prints, as one payload. Show the user its sections
   before you run \`gc --delete\`. Under --delete it is the report that run
-  acted on: each entry's outcome is a stderr line, \`failures\` counts the
+  acted on: \`results\` lists each entry's outcome, \`failures\` counts the
   entries it could not delete, and a nonzero count exits 1. Run
   \`stim gc --json\` again to see what is left.
 
@@ -828,6 +890,46 @@ RULES
   actionable      true when --delete with the same flags reclaims something
   failures        null on a dry run without --idle; otherwise the entries it
                   could not delete or shut down
+  results         what --delete or --idle did, one { kind, status, label,
+                  id, bytes, detail } per entry it acted on; empty on a dry
+                  run. status is "done", "kept" (left alone, detail says
+                  why) or "failed" (detail says why and what to retry).
+                  kind: device, parkedDevice, idleDevice, deviceRecord,
+                  workspaceOutputs, workspaceDirectory, project, buildLock,
+                  buildSlot, deviceLease, easSession, worktree, cache.
+                  label is a device, path or cache name; id is the UDID,
+                  AVD name or path behind it, or null
+  inventory       null except on a dry run without --cache or --idle. Report
+                  only: gc never acts on it, even under --delete.
+                  { devices, runtimes, systemImages, notices }
+    devices       { kind, id, name, model, runtime, state, lastUsedAt, bytes,
+                    directory, owner, project, slot }  every available iOS
+                    simulator and registered AVD. runtime is the simctl
+                    runtime identifier or the AVD's system image package.
+                    lastUsedAt is simctl's last use, or when the emulator
+                    last wrote the AVD's hardware-qemu.ini. bytes is the
+                    simulator's data size from simctl; null for AVDs.
+                    owner is workspace (project and slot say which),
+                    parked, orphaned (this Stim home created it and no
+                    workspace holds it), otherStimHome (a stim-* device this
+                    home has no record of creating, even when a workspace
+                    names it) or user. Off macOS no simulator is listed
+    runtimes      { identifier, runtimeIdentifier, version, build, bytes,
+                    lastUsedAt, deviceCount, command }  iOS simulator
+                    runtimes from \`xcrun simctl runtime list -j\`, then
+                    any other \`simctl list runtimes\` shows, with bytes
+                    and command null. deviceCount is the simulators on
+                    it; command is the \`xcrun simctl runtime delete\`
+                    line for a deletable runtime, else null. Stim never
+                    runs it
+    systemImages  { package, directory, avdCount, command }  installed
+                    Android system images; avdCount is the AVDs whose
+                    image.sysdir.1 names it; command is the
+                    \`sdkmanager --uninstall\` line. Stim never runs it
+    notices       why a listing is missing or partial, such as simctl
+                    timing out or an AVD or system image folder Stim
+                    cannot read. A macOS privacy denial (EPERM) names the
+                    Privacy & Security setting to grant
   sections        one array per report section, in the text order. Every key
                   is present, empty when there is nothing to report:
     deadProjects            { path }
@@ -835,26 +937,42 @@ RULES
     orphanedPorts           { project, label, port }
     orphanedWorkspaces      { dir, projectRoot, bytes }  --delete removes the
                               whole workspace directory
-    linkedWorktrees         { path, idleDays, mergedInto, willRemove,
-                              reason, detail }  mergedInto is the default
-                              branch HEAD is merged into ("origin/main"),
-                              or null; detail says why it is removed
-                              ("merged into origin/main", "idle 9d") or kept.
-                              Without --worktrees, the source checkout and
-                              roots outside git are left out
+    linkedWorktrees         { path, idleDays, mergedInto, pullRequest,
+                              pullRequestUnknown, willRemove, reason,
+                              detail, eligibleAt }  mergedInto is the
+                              default branch HEAD is merged into
+                              ("origin/main"), or null. pullRequest is the
+                              branch's pull request { number, state:
+                              "open" | "merged" | "closed", url,
+                              containsHead }, or null; pullRequestUnknown
+                              says why gh could not answer, else null.
+                              detail says why it is removed ("merged into
+                              origin/main", "PR #12 closed", "idle 9d") or
+                              kept. eligibleAt is the ISO time a
+                              recent-activity worktree becomes removable,
+                              else null. Without --worktrees, the source
+                              checkout and roots outside git are left out
     parkedSimulators        { udid, name, model, runtime, parkedAt, bytes,
                               listed }  with --older-than, only those parked
                               at least that long
     parkedEmulators         { name, systemImage, deviceProfile, parkedAt, bytes, listed }
                               likewise
     orphanedDevices         { kind, id, name, bytes, directory }
-    unverifiedDevices       { kind, id, name, command }  stim-* devices Stim
-                              has no record of creating; never deleted, run
-                              command yourself
+    unverifiedDevices       { kind, id, name, command }  stim-* devices this
+                              Stim home has no record of creating; never
+                              deleted, run command yourself (rm -rf <dir>
+                              for AVD data with no registration)
     staleDevices            { kind, id, name, project, slot, idleDays,
                               bytes }  only with --older-than
     staleDeviceRecords      { kind, id, project, slot }  --delete clears
                               the record only
+    staleLedgerEntries      { kind: "ios" | "android" | "web", id }
+                              simulators this Stim home created that a
+                              complete simctl listing no longer shows, AVD
+                              names with no registration or data in any AVD
+                              root, and browser profile paths whose
+                              directory is gone; --delete forgets the
+                              ledger entry only
     idleDevices             { kind, id, name, project, slot, lastActivityAt,
                               idleForMs, buildInProgress }  booted owned
                               devices whose status activity is "idle";
@@ -872,6 +990,12 @@ RULES
     deviceSweepNotices      { message }
     easSessionSweepNotices  { message }
     skipped                 { path, detail }  not classified as dead
+    workspaceLogs           { dir, projectRoot, bytes, trimBytes, willTrim,
+                              reason, detail }  logs/ of each workspace;
+                              trimBytes is what --delete would drop from
+                              Metro, client and device logs over twice the
+                              8 MiB cap; willTrim marks the ones it would
+                              trim
     workspaceBuildOutputs   { dir, projectRoot, bytes, idleDays, willClear,
                               reason, detail }  derived-data, gradle-build,
                               android-cas and cache-provider of each
@@ -890,12 +1014,14 @@ RULES
   A linked worktree's detail is never null.
     workspaceBuildOutputs   unresolved | in-use | last-use-unknown |
                             recently-used
+    workspaceLogs           unresolved | in-use | collector
     linkedWorktrees         not-a-worktree | bare-repository |
                             source-checkout-unknown | source-checkout |
                             locked | in-use | status-unreadable | dirty |
                             unpushed-unchecked | unpushed | submodules |
                             not-merged | merge-unknown | last-use-unknown |
-                            recently-used
+                            recently-used | activity-unknown |
+                            recent-activity
 
   These print the error contract instead and exit 1:
 
@@ -906,9 +1032,66 @@ RULES
   - --cache together with --worktrees or --idle`
 			},
 			status: {
-				summary: "the status payload's build and device activity fields: a running build, its estimate, each platform's last build, and who drives each device",
+				summary: "the status payload's issues and their codes, build and device activity fields: a running build, its estimate, each platform's last build, who drives each device, whether the app runs on it, and what uses CPU and memory now",
 				body: () => `  stim status --json
 
+  Each environment carries issues, the things in that workspace that need
+  the user, and warnings, the same issues as text ("<slot>: " when not the
+  default slot, then "<message>; run \`<remedy>\`"):
+
+  issues   [{ code, severity, message, remedy, workspace, slot? }]
+
+  code       port-not-ours          something other than this workspace's
+                                    Metro answers its reserved port
+             sim-missing            the recorded simulator no longer exists
+             sim-without-metro      the simulator is booted and no Metro
+                                    serves the workspace
+             avd-serial-changed     the owned emulator came back on another
+                                    serial, so Metro forwarding is lost
+             avd-missing            the recorded AVD no longer exists
+             avd-not-detected       adb does not see the owned emulator while
+                                    the workspace expects it: it holds an
+                                    unexpired lease on its serial, or it
+                                    launched onto it and has not stopped
+                                    that slot since, and its dev server runs
+                                    or the launch was in the last
+                                    ${RECENT_LAUNCH_MS / 6e4} minutes. An idle workspace's
+                                    shut-down emulator is android.state
+                                    "not-detected" with no issue.
+             avd-unchecked          the emulator listing could not be read
+             supervisor-unverified  a supervisor record whose process status
+                                    cannot prove gone or ours; stop refuses to
+                                    signal it
+             browser-unverified     the owned Chrome's supervisor or Chrome
+                                    process cannot be proven gone or ours;
+                                    stop and stim web refuse to signal it
+             browser-orphaned       the owned Chrome runs but its supervisor
+                                    exited, so page logs are not captured;
+                                    stim stop closes it
+  severity   "error" when stop or start refuses until it is resolved, else
+             "warning"
+  remedy     a command to run from workspace, such as "stim android --slot
+             fold"
+  slot       absent for the default slot
+
+  A supervisor record whose pid is gone or reused is not an issue: status
+  reports supervisor null, and the next stop or start clears the record.
+  \`stop --slot <name>\` forgets that slot's launch, so a device stopped on
+  purpose is not reported while the shared dev server keeps running.
+
+  An environment where \`stim web\` ran carries web, its Stim-owned Chrome:
+
+  web  { browser, version, running, pid, supervisorPid, url, headless,
+         viewport, profile, cdpEndpoint }
+
+  running        the browser supervisor and Chrome are both verified live;
+                 pid, supervisorPid and cdpEndpoint are null when false
+  cdpEndpoint    http://127.0.0.1:<port>, the reserved loopback DevTools
+                 endpoint of that Chrome. Attach Playwright MCP
+                 (--cdp-endpoint) or agent-browser (--cdp <port>) to it; it
+                 reaches only the Stim profile, never your own browser
+  profile        the Stim-owned user data directory under STIM_HOME
+
   Each booted simulator and detected emulator in environments (and in
   slots) carries activity; a shut-down or physical device has none:
 
@@ -925,7 +1108,8 @@ RULES
                    the claim does not record them
   lastActivityAt   the newest of this device's app log records, this
                    platform's Metro bundle requests and the workspace's last
-                   Stim run; absent when none is recorded
+                   Stim run, rounded down to the minute; absent when none is
+                   recorded
   basis            the evidence behind state, strongest first:
                    agent-device-claim, agent-device-lease  agent-device state,
                      read only; live only when every recorded process is alive
@@ -941,6 +1125,29 @@ RULES
   \`gc --idle <duration>\` shuts down owned devices idle that long
   (\`guide cleanup gc\`).
 
+  An owned booted simulator or detected emulator also carries app, whether
+  the workspace's app process is alive on it now:
+
+  app  { id, state }
+
+  id     the bundle identifier or package checked: the one launched on this
+         device, else the project's
+  state  "running"  a process of that app runs on the device
+         "stopped"  no such process: it crashed, was killed or never launched
+         "unknown"  the process listing or the app's Info.plist could not be
+                    read; never "stopped"
+
+  app is absent when the device is not owned or no app id is known: the
+  process was not checked.
+
+  This is current process state, read from one host ps (simulator apps are
+  host processes) and the same adb shell ps as activity, so a status --watch
+  refresh notices an exit within its 30-second fallback. It is not launch
+  evidence: launched in an ios or android result keeps its own meaning. For
+  "stopped", run \`stim ios\` or \`stim android\` to launch it again. Plain
+  status appends "<id> running", "<id> not running" or "<id> process
+  unknown" to the device line.
+
   An environment's metro carries idleStop { reason: "idle", at, idleMinutes }
   when its supervisor stopped the dev server for idleness and nothing serves
   the port since; plain \`status\` prints "stopped (idle)" (\`guide metro\`).
@@ -980,7 +1187,7 @@ RULES
 
   lastBuilds   { ios?, android? }, each { platform, status, cacheHit,
                cacheSkipped, durationMs, fingerprint, startedAt, finishedAt,
-               errorCode?, missReason? }
+               errorCode?, missReason?, diagnostics? }
 
   status       "ok" or "failed"
   cacheHit     "local" or "remote" for an app from that cache tier; false
@@ -998,19 +1205,87 @@ RULES
                baseline is { fingerprint, from: "workspace" | "project" }, the
                cached build compared with; rekeyedBy lists "prebuild" or
                "pod install" when those steps moved the key.
+  diagnostics  only on a failed run whose compiler reported errors: up to
+               5 { file, line, column, message }, null where the compiler
+               gave no position.
 
   Plain status prints "last build: ios local cache in 12s, android compiled
   in 7m02s". To predict the next run instead, see \`guide facts plan\`.
 
+  An environment with a recorded run also carries builds, each platform's
+  last 10 runs, newest first. Its newest entry that is not "interrupted" is
+  the run lastBuilds reports, once a run has recorded builds.
+
+  builds         { ios?, android? }, each a list of lastBuilds entries
+                 with { result, slot, configuration, cacheKey, phases }
+  result         "succeeded", "failed", "cancelled" (Stim stopped the run
+                 after an interrupt or \`stim stop\`) or "interrupted": its
+                 process ended without recording a result, such as a kill or a
+                 second interrupt, so the next run recorded it with
+                 null durationMs and finishedAt, no cache facts, and 0 for the
+                 phase it stopped in
+  slot           the device slot, "default" without --slot
+  configuration  the iOS configuration or Android variant the run built,
+                 "Debug" or "debug" by default; null when the run ended
+                 before resolving it
+  cacheKey       the cache key the run looked up or stored under
+  phases         milliseconds spent in each phase the run entered, among
+                 prepare, cache-lookup, wait, prebuild, pods, compile,
+                 install and launch
+
+  Only runs that record a last build are listed: a run that stops before
+  looking up a build, such as a bad flag, is not. Estimates (expectedMs) come from run statistics, not builds.
+
   There is no completion fraction: a compile's log volume depends on what
-  is already built, so it does not measure progress.`
+  is already built, so it does not measure progress.
+
+  An environment's memoryMb is an estimate, not a measurement: a fixed amount
+  per booted simulator, detected emulator, running Metro and running Chrome.
+  capacity.committedMb sums it, and the memory budget uses the same estimate.
+  What is using CPU and memory now is the top-level machine section:
+
+  machine   null, or { owners: [{ kind, name, workspace, slot?, id, owned,
+            cpuPercent, residentMb, processes }] }
+
+  kind         simulator  a booted simulator's launchd_sim tree
+               emulator   an emulator's launcher and qemu tree, by its -avd
+               metro      a workspace's supervisor and Metro trees
+               build      a running ios or android run's process tree,
+                          xcodebuild, Gradle and compilers included
+               browser    the Chrome of \`stim web\` and its supervisor
+               server     stim-server
+               shared     machine-wide processes no workspace owns:
+                          CoreSimulator services, adb server, Gradle and
+                          Kotlin daemons, Watchman, the emulator's netsimd
+  workspace    the workspace that records the device or runs the process;
+               null for a device no workspace records and for server and
+               shared
+  id           the simulator's UDID, the AVD name, Metro's port or the
+               build's platform; null otherwise
+  owned        true for what Stim started and stops: a workspace's owned
+               device (\`stim stop --slot <slot>\`), its Metro (\`stim
+               stop\`), build or Chrome. Never act on an owner with false.
+  cpuPercent   ps %CPU summed over the owner's processes; 100 is one core
+  residentMb   summed resident set size. Pages shared between processes
+               count once per process, so a simulator reports well above
+               its physical footprint.
+
+  Each process counts in exactly one owner, the one whose root process is
+  its nearest ancestor, so the supervisor a build started counts as Metro,
+  not as the build, and a Gradle or Kotlin daemon counts in the build that
+  started it until that build exits, then as shared. Processes with no owner
+  are left out. machine comes from one host ps, the one status reads for
+  device activity, and is null when no simulator is booted, no workspace is
+  live and no build runs: status then reads no process table. \`status --watch --json\` rereads it every 15 seconds while
+  machine is not null, with no other subprocess.`
 			},
 			plan: {
-				summary: "the ios and android --plan payload: fingerprint, cacheHit, prebuild, expectedMs and basis",
+				summary: "the ios and android --plan payload: fingerprint, cacheHit, prebuild, missReason, expectedMs and basis",
 				body: () => `  stim ios --plan --json            # or: stim android --plan --json
 
   { platform, slot?, fingerprint, cacheKey, cacheHit, provider,
-    cacheSkipped, prebuild, outcome, expectedMs, basis, refusal? }
+    cacheSkipped, prebuild, outcome, expectedMs, basis, missReason?,
+    refusal? }
 
   fingerprint   the fingerprint the run would look up first; with
                 --eas-profile, the one EAS CLI computes
@@ -1025,6 +1300,15 @@ RULES
   expectedMs    the median wall time of this project's last successful runs
                 with that outcome on that platform, or null with none
   basis         how many runs expectedMs comes from (at most 10)
+  missReason    on a predicted cold build with cache reads on, why the
+                cache has no app, in the shape of lastBuilds.<platform>
+                .missReason (\`guide facts status\`), compared with the same
+                baseline the run would use. kind is "changed",
+                "no-baseline", "same-sources" or "prebuild-pending": a
+                baseline exists and the run would prebuild first, which the
+                plan does not, so changes compare the fingerprint before that
+                prebuild; changeCount 0 then means those inputs match the
+                baseline. rekeyedBy is empty.
   refusal       { code, message, remedy } when the run would refuse:
                 STIM_PREBUILD_FAILED for a tracked native dir the fingerprint
                 leaves out, STIM_EAS_BUILD_MISSING for an EAS miss
@@ -1298,7 +1582,16 @@ 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.
+symlinks. In a monorepo, a package that depends on neither react-native nor
+expo, such as a Vite web app, uses the one Stim app registered in the same
+git worktree instead, and says so on stderr. ports, web, settings, logs,
+reload, stop and status follow this rule (status stars the app instead of
+printing the note); other commands use the nearest package.json. Register the app first: run stim ports get <label>, stim start,
+stim ios or stim android from the app directory. Every ports command then
+acts on the app's ports, so ports stop without a label there also stops the
+app's other labels. A package that already holds ports keeps them; release
+them to move to the app. With no registered app, or more than one, the
+nearest package.json stays the workspace; run ports from the app directory.
 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,
@@ -1340,7 +1633,10 @@ discovered, not enumerated.
 metro.ndjson, client.ndjson and device.ndjson are size-capped. At about 8 MiB a file
 becomes <name>.1, replacing the previous .1, and a new file starts. Queries read
 both generations, so the oldest records drop off first. History and --since
-reach back only as far as those records.
+reach back only as far as those records. A file written before the cap
+existed can be larger; \`gc\` reports each workspace's log size and \`gc
+--delete\` trims a file over 16 MiB to its newest 8 MiB in a workspace not in use
+(\`guide cleanup disk\`).
 
 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
@@ -1370,18 +1666,23 @@ FLAGS
   --tail <n>       only the last n MATCHING records (applied after filtering,
                    so --level error --tail 5 is the last five ERRORS)
   --errors         errors and fatals since the last marker, from metro, client
-                   and build, plus confirmed native app-crash reports.
+                   and build, plus confirmed native app-crash reports and the
+                   owned Chrome's device errors (platform web: failed
+                   requests, browser errors).
                    Capped at 20 printed records.
   --follow         keep streaming until interrupted (Ctrl+C is exit 0)
   --json           the raw records, one per line, so stdout is valid NDJSON.
                    ZERO matches is ZERO bytes on stdout (an empty NDJSON
                    stream), exit 0 -- parse stdout line by line, never as one
                    JSON document. The "No matching log records" note is human
-                   mode only, on stderr.
+                   mode only, on stderr. With --errors, an Expo error record
+                   also carries context (see THE RECORD).
 
 --ERRORS, PRECISELY
   Level error or fatal, from metro, client and build, plus device records with
-  event native_crash (app/device/time-correlated OS reports or fatal app console output), timestamped after the
+  event native_crash (app/device/time-correlated OS reports or fatal app console output)
+  and device records with platform web (the owned page's failed requests and
+  browser errors, from stim web), timestamped after the
   marker that closes their window. Three rules, and a field test
   caught all three wrong at once -- it returned 3,004 iOS syslog lines on a
   healthy app while hiding a real startup crash.
@@ -1390,7 +1691,10 @@ FLAGS
   \`simctl log stream\` is predicated on the app's PROCESS, and inside that
   process Apple's frameworks log thousands of Error-typed lines (nw_socket,
   SecTrust, WebKit, CoreUI) that have nothing to do with your app. The proven
-  ones are demoted to info by the collector; the scope rule covers the rest.
+  ones are demoted to info by the collector, and iOS main-thread
+  "Synchronous URL loading" performance diagnostics (Expo icons served by
+  Metro raise them) to warn, so a launch does not count them as app errors;
+  the scope rule covers the rest.
   The metro stream carries exactly one demotion of its own, and it is Stim's
   doing: the dev-client deep link \`ios\`/\`android\` open to wire the app to
   your port arrives inside the app as a link, and React Navigation logs at
@@ -1416,8 +1720,15 @@ FLAGS
       errors are reported -- and nothing else. A failed attempt's own summary
       and details land at or after its marker, so they stay reported.
     a LAUNCH marker (src build, written before \`ios\` / \`android\` attempts
-      launch) resets EVERYTHING. It precedes the tool call so an immediate
-      native crash is not hidden by a marker written after the process died.
+      launch) resets EVERYTHING except the web page's records. It precedes the
+      tool call so an immediate native crash is not hidden by a marker written
+      after the process died.
+    a PAGE-LOAD marker (the web_navigation record \`stim web\` writes for each
+      load of the page's top-level document) resets only the page's records,
+      those with platform web. It is written when the load starts, so a
+      failure logged in the same millisecond belongs to that load, and so does
+      anything the old page logs before it is replaced. Until the first page
+      load is logged, the page's records follow the launch windows.
   A finished bundle is not evidence that the app which loaded it is fine.
   In the field case the app threw at 16:03:54 and Metro wrote its marker at
   16:03:55, one second later, because the bundler finishes accounting for a
@@ -1438,11 +1749,18 @@ FLAGS
   not stack depth. For untouched captured records use:
     stim logs --source all --json
   Neither form can restore text the runtime truncated before capture.
-  In non-follow human output, an Expo error includes its immediately
-  following code frame and Call Stack lines. Bare React Native symbolication is
-  shown as separate context because Metro does not provide an error correlation
-  identifier. Context does not change the error count or the raw error records
-  returned by --json. --json is never capped, and neither is an explicit --tail.
+  With --errors, an Expo error includes the code frame and stack lines Expo
+  printed after it, in human and --json output, with or without --follow.
+  Stim's own Metro records that land between those lines, such as bundle
+  responses, do not cut the stack short. Human output joins the lines to the
+  message. --json leaves msg as captured and adds them to the error record as
+  a context array of strings; each record is still one line. --follow holds an
+  Expo error until a poll, about every 500 ms, adds no more of its lines, so
+  it can print up to about a second after Expo does. Non-follow human output
+  also shows bare React Native symbolication as separate context, because
+  Metro does not provide an error correlation identifier. Context never
+  changes the error count or adds records to --json. --json is never capped,
+  and neither is an explicit --tail.
 
   In --follow mode the marker window is dropped -- every error arriving from
   then on is by definition after the last marker seen.
@@ -1464,6 +1782,10 @@ THE RECORD
              A collector_clock warning then says timestamps retain device time.
     raw      true when the level was inferred from a line of text rather than
              reported by the producer (every expo-child record)
+    context  --errors --json only: the code frame and stack lines Expo
+             printed after this error, as an array of strings. Absent when
+             there are none. Stim adds it at query time; it is not in the
+             log files.
 
 WHAT WRITES WHAT
   metro.ndjson         the bundler, in both supervisor modes
@@ -1479,7 +1801,8 @@ WHAT WRITES WHAT
                        is where a native crash that never reached JS shows up
                        -- and, on iOS, where every Apple framework running in
                        the app's process also logs. The proven noise sources
-                       are recorded at info rather than error; the rest is why
+                       are recorded at info rather than error (Synchronous
+                       URL loading diagnostics at warn); the rest is why
                        --errors leaves this source out unless asked. A VERIFIED
                        LAUNCH counts these records and prints one line:
 
@@ -1741,11 +2064,17 @@ Branch on the code, never on the message.`,
   the source checkout, then warm again.`
 			},
 			STIM_BUILD_FAILED: {
-				summary: "xcodebuild or gradle failed; the two Android APK refusals; a damaged compilation-cache object",
+				summary: "xcodebuild or gradle failed; the Android missing-SDK and APK refusals; a damaged compilation-cache object",
 				body: () => `STIM_BUILD_FAILED
   xcodebuild or gradle failed. The EXTRACTED diagnostics are printed (capped),
   not the transcript. Read the log path on the next line for the rest.
-  Two Android refusals share this code without gradle itself failing:
+  Three Android refusals share this code without gradle itself failing:
+  - NO ANDROID SDK, before gradle starts: nothing exists at the SDK path
+    Stim resolves (ANDROID_HOME, else ANDROID_SDK_ROOT, else the default
+    location), and there is no android/local.properties. Set ANDROID_HOME to the SDK or write sdk.dir
+    into android/local.properties; \`stim doctor --platform android\` reports
+    the same condition. When the SDK is found and neither variable is set,
+    Stim passes its path to gradle as ANDROID_HOME.
   - MORE THAN ONE debug APK under android/app/build/outputs/apk and nothing
     configured to pick one (a project with product flavors, several flavors
     already built). Stim will not guess which flavor to install: the
@@ -2248,6 +2577,12 @@ so a Debug run on one is wired to a LAN origin instead of localhost.`,
   \`gc --delete\`) and run \`stim ios\` again to create the requested model.
   That loses the old sim's app state.
 
+"this project's sim runs iOS X, but --runtime asked for Y"
+  The same refusal for an explicit \`--runtime\` that names another installed
+  iOS version than the project's sim runs. Reap the sim the same way, or pass
+  \`--slot <name>\` to create one on the requested runtime beside it. The
+  ios.runtime setting alone never refuses; it applies at creation.
+
 "this project's emulator uses device profile X, but Y was requested"
   The Android counterpart, from \`--device-profile\` or android.deviceProfile.
   Reap the AVD the same way, or pass \`--slot <name>\` to create the requested
@@ -2428,10 +2763,11 @@ so a Debug run on one is wired to a LAN origin instead of localhost.`,
   metro.publicUrl for an existing endpoint.`
 			},
 			STIM_RELOAD_AMBIGUOUS: {
-				summary: "both owned apps are live; name the platform",
-				separator: "--- RELOAD CODES (`stim reload [ios|android]`) ---",
+				summary: "more than one owned app or the owned Chrome is live; name the platform",
+				separator: "--- RELOAD CODES (`stim reload [ios|android|web]`) ---",
 				body: () => `STIM_RELOAD_AMBIGUOUS
-  Both owned apps are live. Name ios or android; Stim never guesses.`
+  More than one of the owned iOS app, Android app and Chrome page is live.
+  Name ios, android or web; Stim never guesses.`
 			},
 			STIM_RELOAD_RELEASE: {
 				summary: "the live app has embedded JS; run a Debug build first",
@@ -2444,7 +2780,10 @@ so a Debug run on one is wired to a LAN origin instead of localhost.`,
 				aliases: ["STIM_RELOAD_UNOWNED", "STIM_RELOAD_PROBE_FAILED"],
 				body: () => `STIM_RELOAD_STOPPED / STIM_RELOAD_UNOWNED / STIM_RELOAD_PROBE_FAILED
   The recorded app is gone, its exact device is not live and owned by this
-  workspace, or simctl/adb could not prove the process exists. No launch or
+  workspace, or simctl/adb could not prove the process exists. For web,
+  STOPPED means no owned Chrome is running (run stim web) and PROBE_FAILED
+  that its identity could not be verified. A bare reload picks the Chrome page
+  only when no native launch is recorded. No launch or
   device lifecycle action is taken; follow the printed platform-command or
   process-probe remedy.`
 			},
@@ -2476,6 +2815,51 @@ so a Debug run on one is wired to a LAN origin instead of localhost.`,
   MORE THAN ONE MATCHING PEER IS NOT A FAILURE. A workspace Metro serves one
   app, so several matching peers are that app on several devices. Stim reloads
   every one of them and reports the count in the facts as targets.`
+			},
+			STIM_WEB_NO_CHROME: {
+				summary: "stim web found no installed Chrome or Chromium",
+				separator: "--- WEB CODES (`stim web`) ---",
+				body: () => `STIM_WEB_NO_CHROME
+  stim web drives the installed Google Chrome (or Chromium) with a profile
+  Stim creates. It looks in /Applications and ~/Applications on macOS, in
+  Program Files on Windows, and for google-chrome or chromium on PATH. Stim
+  never installs a browser. Install Chrome, then run stim doctor.`
+			},
+			STIM_WEB_NO_URL: {
+				summary: "not an Expo app and web.url is unset, so Stim does not know which page to open",
+				body: () => `STIM_WEB_NO_URL
+  Only Expo serves web from Metro, so for any other app Stim needs web.url.
+  stim web never starts a web server, for any framework. Start yours on a
+  named port and point web.url at it:
+    pnpm exec vite --port "$(stim ports get web)" --strictPort
+    stim settings set web.url 'http://localhost:{port:web}/' --scope workspace
+  See stim guide web.`
+			},
+			STIM_WEB_DEPS_MISSING: {
+				summary: "an Expo app without react-native-web cannot render on the web",
+				body: () => `STIM_WEB_DEPS_MISSING
+  The Expo app does not resolve react-native-web, so Metro cannot build a web
+  bundle. Install the web dependencies, start Metro, then run stim web again:
+    npx expo install react-dom react-native-web @expo/metro-runtime
+    stim start`
+			},
+			STIM_WEB_BROWSER_HELD: {
+				summary: "the previous owned Chrome could not be stopped or verified; it was left running",
+				body: () => `STIM_WEB_BROWSER_HELD
+  stim web replaces the workspace's owned Chrome when its options change, and
+  the previous one could not be stopped: its supervisor or Chrome did not
+  exit, or their process identities could not be verified. Stim never signals
+  a process it cannot verify. Check stim status for browser-unverified, then
+  follow stim guide errors teardown.`
+			},
+			STIM_WEB_LAUNCH_FAILED: {
+				summary: "the owned Chrome did not start or did not open DevTools on its reserved port",
+				body: () => `STIM_WEB_LAUNCH_FAILED
+  The browser supervisor exited before Chrome answered on its reserved
+  DevTools port. The remedy names the supervisor log; web.ndjson carries the
+  failure as web_browser_failed, and browser.log holds Chrome's own output.
+  A port another process bound first also lands here: run stim web again to
+  reserve a fresh one.`
 			},
 			STIM_WORKTREE_REMOVAL_IN_PROGRESS: {
 				summary: "a managed remote start found worktree remove holding the lock; wait, then rerun",
@@ -2574,7 +2958,11 @@ captured"  (in metro.ndjson, bare RN)
   ios.deviceType, ios.runtime, android.systemImage or android.deviceProfile
   setting is checked the same way, and the check applies
   even when this workspace ALREADY owns a device, so a name that could never
-  create anything is caught rather than left to a later run.
+  create anything is caught rather than left to a later run. The
+  \`pixel_fold\` and \`resizable\` profiles on a system image without
+  foldable support (SupportPixelFold in its advancedFeatures.ini) refuse the
+  same way, since the emulator quits on boot; the remedy names an installed
+  image that has it, or an sdkmanager install when none does.
   \`gc --json --cache <name>\` refuses with STIM_BAD_ARG when no shared cache
   carries the name; the remedy names the caches on this machine. \`gc\`
   refuses --cache together with --worktrees the same way.
@@ -2643,9 +3031,17 @@ captured"  (in metro.ndjson, bare RN)
 				summary: "a lock held past the wait; workspace-process and short directory locks",
 				body: () => `STIM_LOCK_TIMEOUT
   The same locks, held by an ordinary command that is still running, for
-  longer than the wait -- 60s by default, 4 minutes for the remote-session and
-  EAS project locks, and ~90 minutes for the \`worktree warm\` lock, which one
-  \`--refresh\` can hold for a whole dependency install. That wait prints its
+  longer than the wait -- 60s by default, 4 minutes for the remote-session lock
+  and for \`gc\` deleting EAS sessions under the EAS project lock (its sweep
+  skips at once while that lock is held), and ~90 minutes for the \`worktree warm\` lock, which one
+  \`--refresh\` can hold for a whole dependency install. The machine-wide EAS
+  project lock admits one EAS session start at a time. A \`--remote eas\` run
+  waits on it after its build with no overall limit, printing \`lock  waiting
+  for EAS remote start (pid 41233, in <workspace>, running for 1m12s) to
+  release the EAS project lock\` at once and \`still waiting for ...\` every 30
+  seconds. It refuses only when one holder has held the lock for longer than
+  the slowest EAS session start (39 minutes), naming that pid.
+  The \`worktree warm\` wait prints its
   elapsed waiting time and holder every 30 seconds (\`lock        waiting 40s
   for stim worktree warm --refresh (pid 41233)\`) and the refusal names the same holder
   and the lock directory under ~/.stim/warm-locks.
@@ -2658,8 +3054,10 @@ 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. 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.
+  the lock. These locks wait up to 12s and never expire based on age. When
+  another Stim command holds the lock, the message says so: wait for it and
+  retry. A failed marker write, such as ENOSPC on a full disk, removes the
+  directory it just created before Stim reports the write error.
   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
@@ -2669,9 +3067,12 @@ captured"  (in metro.ndjson, bare RN)
   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
+  empty before marker publication (a process killed between creating it and
+  writing its marker) or during final removal also cannot prove it is free.
+  These paths still time out, and the message says no current Stim holds the
+  lock and ends with \`rm -rf '<path>'\`. An older Stim version may still be
+  using it: if none is running, remove the named directory with that command.
+  Standalone Metro and Expo cache packages use the
   same core protocol and do not require the Stim CLI.`
 			},
 			teardown: {
@@ -2708,7 +3109,23 @@ the supervisor could not be verified"  (stop)
 "teardown failed: <reason>"
   Stim could not release the owned device and keeps its record for a retry.
   \`worktree remove\` exits 1 without removing the worktree while the device is
-  still tracked. Fix the reported cause and re-run.`
+  still tracked. Fix the reported cause and re-run.
+
+"teardown failed: Owned AVD <name> did not finish shutting down after <n>s:
+emulator process <pid> is still running"
+  An owned emulator counts as stopped only when no process launched for its
+  AVD (\`qemu-system-*\` or \`emulator\` with \`-avd <name>\`) is left in the
+  process table. Stim asks it to quit with \`adb emu kill\` and waits 60s.
+  Then it sends SIGTERM and, 5s later, SIGKILL. When adb cannot reach the
+  emulator, Stim sends SIGTERM at once and waits 60s before SIGKILL. It signals
+  only a pid whose command line names the AVD and whose process identity,
+  recorded before shutdown, still matches. "(Stim could not verify the
+  identity of <pid>, so it sent no signal)" means that identity could not be
+  read or no longer matches. Check \`ps -p <pid> -o command=\`, stop the
+  process yourself, then re-run the command or \`gc --delete\`. Windows has
+  no process-table check and Stim signals nothing there: it waits for the pid
+  in the AVD's process lock after \`adb emu kill\`, and refuses at once when
+  adb cannot reach the emulator.`
 			},
 			remove: {
 				summary: "worktree remove refused a dirty tree: what it restores itself and what --force discards",
@@ -3111,13 +3528,13 @@ ANDROID EMULATOR RESTARTS
   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.
-  On macOS, top-level androidEmulatorApp "stim-desktop" in the machine config
-  boots owned emulators without a window and shows them in Stim Desktop; see
-  guide settings. An emulator that is already running keeps its current
+  On macOS, androidEmulatorApp "stim-desktop", the default while Stim Desktop
+  is installed, boots owned emulators without a window and shows them in Stim
+  Desktop; see guide settings. An emulator that is already running keeps its current
   display until it next boots.
 
 DESTRUCTIVE COMMANDS -- ask the user first
-  gc --delete             deletes orphaned devices Stim created, tens of GB
+  gc --delete             deletes orphaned devices this Stim home created, tens of GB
   gc --delete --cache all empties the shared build caches every project uses
   gc --delete --cache <name>
                           empties only the caches that carry <name>
@@ -3170,8 +3587,10 @@ WAITING FOR A CHANGE
   status payload per line: one at once, then one each time the payload
   changes, never two identical ones in a row. It reacts to Stim state files,
   the EAS session ledger, adb device arrivals and departures, and simulator
-  state, and recomputes every 30 seconds as a fallback. Ctrl+C, SIGTERM or
-  closing its stdout ends it with exit 0. Without --json it reprints the human view on change.`,
+  state, and recomputes every 30 seconds as a fallback. A log append updates
+  only the log error count and device activity, no sooner than 15 seconds
+  after the previous refresh. Ctrl+C, SIGTERM or closing its stdout ends it
+  with exit 0. Without --json it reprints the human view on change.`,
 		sections: {
 			eas: {
 				summary: "download a matching EAS development build; explicit profile, costs, cache and miss remedies",
@@ -3657,7 +4076,11 @@ PREDICTING THE NEXT BUILD (--plan)
   the cache.provider tier into a temporary directory the plan removes, the
   app config's provider wherever it keeps its downloads, as during a run.
   On a miss it adds the prebuild decision the run would make (generate,
-  regenerate, none, or refuse with STIM_PREBUILD_FAILED). With --eas-profile it asks EAS for a matching
+  regenerate, none, or refuse with STIM_PREBUILD_FAILED) and, with cache
+  reads on, the miss reason the run would print, such as "native dependency
+  added: expo-clipboard". A plan never prebuilds, so when the run would and a
+  baseline exists, the reason's kind is prebuild-pending and it compares the
+  fingerprint before that prebuild. With --eas-profile it asks EAS for a matching
   build (config, fingerprint:generate, build:list) and downloads nothing.
   expectedMs is the median of this project's recorded runs with that outcome;
   the payload is in \`guide facts plan\`.
@@ -3895,7 +4318,10 @@ THE BUILD CACHE HAS THREE LEVELS
   records the reason as lastBuilds.<platform>.missReason in status --json
   (see \`guide facts status\`), and writes the changed sources (capped at 20
   names) to the build log as a fingerprint_diff record. With no baseline the
-  line says there was nothing to compare with.
+  line says there was nothing to compare with. status --json also lists each
+  platform's last 10 runs in builds.<platform>, with their result, cache
+  outcome, miss reason, phase timings and diagnostics, so a hit that turned
+  into a miss shows which run changed what.
 
   THE KEY CAN MOVE MID-RUN, and the run says so in two facts rather than two
   explanations. \`expo prebuild\` and \`pod install\` rewrite fingerprinted
@@ -3932,11 +4358,28 @@ THE BUILD CACHE HAS THREE LEVELS
   \`expo prebuild --clean\` yourself or delete the directory so the next build
   regenerates it.
 
-  If the iOS fingerprint after prebuild or pod install is unavailable, Stim
-  installs the build but skips local storage and remote uploads. fingerprint
-  and cacheKey are null in the result and lastBuild; the old key is not reused.
-  Android does the same if its post-Gradle fingerprint cannot be computed.
-  These null fields mean unavailable cache information, not an install failure.
+  Both platforms fingerprint once more after the compile. A change the build
+  itself makes to a fingerprinted file under node_modules/ or the native
+  directory moves the key the same way, printed as \`(after Gradle)\` or
+  \`(after xcodebuild)\`. Any other input that changed while the build ran
+  -- the app config or a config plugin at any point after the first lookup,
+  or any other source during the compile -- means the artifact may not match
+  the key, so Stim installs what it built and stores nothing. The one config
+  change exempted is the ios.bundleIdentifier or android.package that
+  \`expo prebuild\` adds to a static app.json that lacks one:
+
+    fingerprint expoConfig changed while the build ran, so the artifact may not match its key; the build will be installed but not cached
+
+  The prebuild record never takes a hash that includes the edit, so the next
+  run regenerates a CNG directory from the edited config and compiles it
+  instead of reusing the stale one. An edit under node_modules/ or the native
+  directory during the compile cannot be told apart from the build's own
+  writes and moves the key. Stim also skips storing when the fingerprint
+  after prebuild, pod install or the compile cannot be computed. In every
+  skipped case nothing goes to the local cache, the cache provider or a
+  remote upload, fingerprint and cacheKey are null in the result and
+  lastBuild, and the old key is not reused. These null fields mean
+  unavailable cache information, not an install failure.
 
 WHAT MAKES THE CACHE ACTUALLY HIT: .FINGERPRINTIGNORE
   Every entry is keyed on what the tree hashes, so two workspaces share an
@@ -4357,13 +4800,22 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   (\`iOS 26.5\`), exactly; no prefix or suffix matches.
 
   These flags describe a device that does not exist yet. When this workspace
-  ALREADY owns a simulator and \`--device-type\` names a different model,
-  Stim refuses rather than silently booting the wrong one: reap the current
-  sim with \`stim worktree remove\` (or \`stim gc --delete\`), then run
-  \`stim ios\` again to create the requested one. \`--device-profile\` does
-  the same for an AVD of another profile. To keep both devices, give the new
-  one its own \`--slot\`. \`--runtime\` and \`--system-image\` apply at
-  creation only, so an existing device keeps the version it was made with.
+  ALREADY owns a simulator and \`--device-type\` names a different model, or
+  \`--runtime\` a different iOS version, Stim refuses rather than silently
+  booting the wrong one: reap the current sim with \`stim worktree remove\`
+  (or \`stim gc --delete\`), then run \`stim ios\` again to create the
+  requested one. \`--device-profile\` does the same for an AVD of another
+  profile. To keep both devices, give the new one its own \`--slot\`. The
+  ios.runtime and android.systemImage settings apply at creation only, so an
+  existing device keeps the version it was made with. An explicit \`--system-image\` that
+  names another image than this workspace's AVD refuses the same way, unless
+  that AVD never finished a boot (for example one made from an image its
+  profile cannot boot): Stim then deletes it through owned-device teardown and
+  creates the requested one. \`--device-profile pixel_fold\` or
+  \`resizable\` on a system image without foldable support (SupportPixelFold
+  in its advancedFeatures.ini) refuses with STIM_BAD_ARG before anything is
+  created, since the emulator quits on boot; the remedy names an installed
+  image that has it.
   The --json payload reports what was actually used: \`deviceType\` and
   \`runtime\` on iOS, \`systemImage\` and \`deviceProfile\` on Android, read
   from the device itself, so a settings-driven run reports them too.`
@@ -4723,9 +5175,10 @@ HOST MEMORY PRESSURE AND STALLED SIMULATORS
   boot (including the initial boot request) up to 10 minutes, and app installation
   up to 5 minutes. Process termination confirmation can take another 10 seconds;
   a final boot-state query can take 30 seconds. After boot, Stim opens the owned
-  simulator in the selected Xcode's Device Hub on Xcode 27, or Simulator on
-  older Xcode. Top-level iosSimulatorApp in the machine config can select
-  Siniulator or Stim Desktop instead; see guide settings. Override it for one
+  simulator in Stim Desktop while it is installed, otherwise in the selected
+  Xcode's Device Hub on Xcode 27, or Simulator on older Xcode. Top-level
+  iosSimulatorApp in the machine config can select another viewer; see guide
+  settings. Override it for one
   local run with \`stim ios --simulator-app siniulator\`,
   \`--simulator-app stim-desktop\`, or \`--simulator-app xcode\`. This also
   opens an already running owned simulator without rebooting it or saving the
@@ -4734,6 +5187,8 @@ HOST MEMORY PRESSURE AND STALLED SIMULATORS
   and takes at most 10 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.
+  Warning or critical pressure adds recovery advice to the first report at
+  that level; later reports repeat it only after the level changes.
   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
@@ -4745,7 +5200,11 @@ HOST MEMORY PRESSURE AND STALLED SIMULATORS
 
   If pressure is elevated, free host memory before retrying. Use \`stim stop\`
   only in workspaces you own and have finished using; ask before closing other
-  agents' simulators or heavy apps. Rebooting a simulator under the same pressure
+  agents' simulators or heavy apps. Never quit Device Hub or Simulator.app to
+  free memory: on Xcode 27 (confirmed on 27A266a), quitting Device Hub by
+  default shuts down every booted simulator on the machine, including ones it
+  never opened a window for and ones other workspaces or agents are using.
+  Rebooting a simulator under the same pressure
   can repeat the stall. Consider fewer concurrent builds/devices (guide lifecycle
   concurrency) and a reviewed SimSlim profile for future runs.`
 			}
@@ -4768,11 +5227,14 @@ WHAT RECLAIMS AN OWNED DEVICE
   stim worktree remove    parks eligible owned simulators and emulators
                             (\`guide lifecycle pool\`); deletes them when
                             parking is disabled or their setup cannot be verified
-  stim gc --delete        sweeps devices Stim created that no project
+  stim gc --delete        sweeps devices this Stim home created that no project
                             references (\`guide cleanup gc\`), clears
                             verified parked simulators and emulators, and
                             runs \`stim worktree remove\` on every clean,
-                            Stim-managed linked worktree whose branch is merged
+                            Stim-managed linked worktree whose branch is merged,
+                            or whose pull request was merged or closed, and
+                            that shows no activity within
+                            gc.worktreeGraceMinutes
   stim gc --delete --older-than <days>
                             also reaps the device of a workspace no Stim
                             command has used in that long, even though the
@@ -4788,15 +5250,20 @@ WHAT RECLAIMS AN OWNED DEVICE
 
 \`worktree remove\` and \`gc --delete\` are the only two commands that delete;
 \`gc --delete\` deletes worktrees only through \`worktree remove\`. \`gc
---delete\` also clears workspace build outputs (\`guide cleanup disk\`) and
-orphaned workspace directories, never a checkout. \`stim stop\` shuts a device
+--delete\` also clears workspace build outputs, trims oversized workspace logs
+(\`guide cleanup disk\`) and removes orphaned workspace directories, never a
+checkout. \`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
+serial. An Android session must also name the owned AVD, because the next
+emulator on a console port reuses its serial. \`stop\` closes a session only
+when agent-device's claim on the device names it and was taken inside this
+workspace; sessions from another workspace or claim stay open. Stim 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.
@@ -4843,7 +5310,8 @@ SWEEPING FINISHED WORKTREES
   Every \`gc\` without --cache looks at every registered project root and
   every workspace.json root, grouped by git worktree, and reports each linked
   worktree with the reason it is removed or kept. A worktree is finished when
-  its branch is merged into the default branch. \`--worktrees\` also removes
+  its branch is merged into the default branch, or its pull request was
+  merged or closed (PULL REQUESTS below). \`--worktrees\` also removes
   one that is idle: no recorded use for --older-than days, 7 without it; a
   worktree whose last use is unknown is kept. Both need the same clean state;
   a worktree is kept when it is the source checkout, bare, locked, in use,
@@ -4852,6 +5320,27 @@ SWEEPING FINISHED WORKTREES
   initialized submodules. Without --worktrees, the report leaves out the
   source checkout and roots outside git.
 
+  IN USE means its dev server supervisor runs, a stim ios, android or stop
+  run holds its native-run lock, a live build lock or slot names it, a
+  managed tunnel or remote lock is held, an owned simulator or emulator of
+  the workspace is booted (an agent-device session needs one), or it holds
+  an unexpired device lease. When the simulator or emulator list cannot be
+  read, the worktree counts as in use. A device left booted keeps the
+  worktree until \`stim stop\` in it, or \`gc --idle <duration>\`, shuts
+  the device down.
+
+  RECENT ACTIVITY keeps a worktree gc would otherwise remove until
+  gc.worktreeGraceMinutes (120 by default, \`guide settings\`) have passed
+  since the latest of: a write to its git index, HEAD or HEAD reflog, a write
+  to its Stim workspace state or log files, and, for a merged branch, the
+  committer date of the commit that brought it into the default branch, or
+  the time its pull request was merged or closed. That
+  window is when an agent that just merged runs \`stim stop\` and \`stim
+  worktree remove\` itself. The reason is recent-activity, and the report
+  and the JSON eligibleAt field say when it becomes removable. When that
+  activity cannot be read, the worktree is kept (reason activity-unknown).
+  0 turns the grace period off.
+
   MERGED means, with the default branch taken from origin/HEAD, after a
   \`git fetch origin <default>\` per repository (30s timeout, no credential
   prompt; skipped when that checkout fetched in the last 10 minutes):
@@ -4864,24 +5353,42 @@ SWEEPING FINISHED WORKTREES
     commit on the default branch (a rebase merge), or its whole diff since the
     merge base has the same verbatim patch id as a commit there, compared on
     the files the branch changes (a squash merge).
-  Merge state comes from git alone, not from a hosting service. A squash
-  merge whose content changed during the merge (a conflict resolution, a
-  suggested edit, even whitespace) does not match and is kept, and so is a
-  fast-forwarded branch. When origin/HEAD is not set, the fetch fails, or git
+  From git alone, a squash merge whose content changed during the merge (a
+  conflict resolution, a suggested edit, even whitespace) does not match, and
+  neither does a fast-forwarded branch or a stacked pull request merged after
+  the one below it; the pull request check covers those. When origin/HEAD is not set, the fetch fails, or git
   cannot answer, the state is unknown and never counts as merged (reason
   merge-unknown, with the remedy); with --worktrees an idle worktree is still
   removed. A squash- or rebase-merged branch whose upstream is gone (deleted
   after the merge and pruned locally) has commits only it reaches; they do
   not block removal, because their change is on the default branch, and the
   branch is kept.
+
+  PULL REQUESTS: gc runs one \`gh api graphql\` query per repository that
+  asks for the 20 newest pull requests of each linked worktree's branch, as
+  \`gh pr list --head <branch> --state all\` would, and for each worktree
+  takes the pull request whose head is HEAD, else one whose head contains
+  HEAD. A pull request whose head HEAD is past ("PR #12 merged, and HEAD has
+  commits it does not"), one unrelated to HEAD (an older use of the branch
+  name), and one from a fork do not count. A merged or closed one makes the worktree finished
+  under the same clean state. Merged, its commits are kept on GitHub, so local
+  commits whose remote branch was deleted do not block removal. Closed, they
+  do: a closed pull request whose remote branch is gone keeps the worktree as
+  unpushed. An open pull request never makes a worktree finished. When gh is
+  not installed, not signed in, or fails, the JSON pullRequestUnknown field
+  and the report say why, and gc judges from git alone. A detached HEAD is
+  not looked up. \`stim worktree remove\` makes the same check when
+  local-only commits alone would refuse the removal, and accepts a merged
+  pull request whose head is or contains HEAD.
     stim gc                                        # report merged worktrees
     stim gc --delete                               # remove them
     stim gc --delete --worktrees --older-than 3    # also the clean idle ones
   --cache with --worktrees is refused with STIM_BAD_ARG; run them separately.
   With --delete it runs the \`stim worktree remove\` pipeline, never --force,
   on each removable worktree. That pipeline re-inspects the worktree and
-  re-checks use under the removal locks, and idleness for an idle worktree
-  or an unchanged HEAD for a merged one, then parks devices and handles the
+  re-checks use and recent activity under the removal locks, and idleness
+  for an idle worktree or an unchanged HEAD for a merged one, then parks
+  devices through the same teardown and handles the
   branch exactly as a manual \`stim worktree remove\`, which keeps the
   checkout when its HEAD moves while devices are reclaimed. A worktree that
   changed since the report is kept with the reason. A worktree that fails is
@@ -4941,15 +5448,16 @@ it. A record is what makes the device findable again, so it outlives a failed
 teardown rather than turning it into an orphan.
 
 WHICH stim-* DEVICES gc DELETES
-  A \`stim-\` prefix alone is not proof that Stim made a device. gc deletes an
-  unreferenced device only when Stim created it: the device is listed in
+  A \`stim-\` name is not proof that this Stim home made a device: every
+  STIM_HOME names its devices the same way. gc deletes an unreferenced device
+  only when this home created it: the device is listed in
   $STIM_HOME/created-devices.json, where Stim records every simulator and AVD
-  it creates, or it predates that ledger and matches Stim's own format
-  exactly -- an iOS name \`stim-<label> (<model> <runtime>)\`, or an AVD
-  named \`stim-<label>\` whose config.ini holds the byte-valued
-  disk.dataPartition.size Stim writes. gc lists any other stim-* device under
+  it creates, or it predates that ledger and this home's config records it in
+  the device pool or in a project as owned. gc lists any other stim-* device,
+  including those another STIM_HOME created, under
   "Unrecognized stim-* devices" with the command that deletes it
-  (\`xcrun simctl delete <udid>\` or \`avdmanager delete avd -n <name>\`), and
+  (\`xcrun simctl delete <udid>\`, \`avdmanager delete avd -n <name>\`, or
+  \`rm -rf <dir>\` for AVD data with no registration), and
   never runs it. Boot, shutdown and teardown re-check ownership by the same
   rule, so a device that stops matching is left alone.
 
@@ -5018,6 +5526,26 @@ THE MIRROR IMAGE: A STALE DEVICE RECORD
   at simctl or avdmanager, and the project keeps its entry, its label and its
   Metro port. The next \`ios\` / \`android\` creates a fresh owned device.
 
+  The ledger of devices Stim created (created-devices.json) keeps a
+  simulator's UDID after the simulator is deleted outside Stim. \`gc\`
+  reports such UDIDs under "Stale device ledger entries" when a complete
+  simctl listing, unavailable simulators included, does not show them, and
+  \`gc --delete\` forgets them under the ledger lock. If the listing fails,
+  nothing is reported or forgotten, and like the device sweep it is skipped
+  without a config or under a scoped STIM_HOME. UDIDs are never reused, so a
+  forgotten entry cannot belong to a later simulator.
+
+  Android ledger entries are AVD names, and names are reused: another
+  STIM_HOME can later create an AVD with the same name. \`gc\` reports an
+  AVD name as stale only when \`emulator -list-avds\` answered, the first AVD
+  root exists (a missing one may be an unmounted volume), no AVD root holds
+  <name>.ini or <name>.avd, and no unfinished setup reserves the name.
+  \`gc --delete\` takes that AVD's claim, then re-checks and forgets the name
+  under the config and ledger locks, so a setup in progress or an AVD
+  recreated since the report keeps its entry. A name reused before \`gc\`
+  runs still counts as this home's; run \`gc\` after deleting a Stim AVD by
+  hand.
+
 THE ONE CASE GC WILL NOT REAP
   If the config is gone entirely (deleted ~/.stim, or a throwaway
   STIM_HOME), gc cannot tell your stale devices from another config's LIVE
@@ -5084,7 +5612,7 @@ THE ONE CASE GC WILL NOT REAP
   Wall-clock timestamps and command names are not ownership proof.`
 			},
 			disk: {
-				summary: "disk usage, workspace build outputs, AVD and build-log sizes, the data partition, trimming the shared caches",
+				summary: "disk usage, workspace build outputs and logs, AVD and build-log sizes, the data partition, trimming the shared caches",
 				body: () => `DISK
   Logs, state, pidfiles and Xcode DerivedData are under the global workspace
   directory, and \`worktree remove\` reclaims them. \`gc --delete\` clears the
@@ -5100,12 +5628,16 @@ THE ONE CASE GC WILL NOT REAP
   disabled. The first boot and a boot after the emulator, system image, or AVD
   settings change are cold, while later supported boots load the one automatic
   snapshot saved on exit. \`stop\` waits for the emulator process and, when
-  enabled, the snapshot save to finish.
+  enabled, the snapshot save to finish. An emulator that ignores \`adb emu
+  kill\` or is unreachable over adb is signalled once its identity is verified;
+  one that still runs fails the teardown and keeps its record (see \`stim guide
+  errors teardown\`).
   New owned AVDs default to an 8 GiB data partition, though project settings can
   change it. When enabled, Quick Boot keeps one automatic snapshot until the AVD is
   parked or deleted.
   \`gc\` prints the on-disk size beside an orphaned or stale owned Android AVD
-  when its content directory can be read.
+  when its content directory can be read, and beside an orphaned or stale
+  owned simulator the data size simctl reports for it.
 
   So are the logs, and one of them is not small: build-ios.ndjson /
   build-android.ndjson hold the whole xcodebuild or gradle transcript at debug
@@ -5154,6 +5686,19 @@ WORKSPACE BUILD OUTPUTS
   React Native 0.86 Swift does not use it (explicit modules are off), so that
   build recompiles Swift.
 
+WORKSPACE LOGS
+  \`gc\` reports the size of each workspace's logs/ (the workspaceLogs
+  section of \`gc --json\`). metro.ndjson, client.ndjson and device.ndjson and
+  their .1 generations rotate at 8 MiB (\`guide logs\`), but a file written by
+  a Stim version before the cap can be hundreds of MB. \`gc --delete\` trims
+  each of those six files that is over 16 MiB to its newest 8 MiB, cut at a
+  record boundary; a file just past 8 MiB is normal rotation and stays.
+  \`--older-than\` does not limit it. It skips a workspace that is in use (a
+  dev server, a native run, a build or a held tunnel) or that has a device
+  log collector recorded; \`stim stop\`
+  stops the collector. Build transcripts keep the whole run and are never
+  trimmed, and nothing else under logs/ is touched.
+
 SHARED BUILD CACHES
   The caches that make a second workspace fast are alive by design and never
   included in a plain \`gc --delete\`. Every \`gc\` run reports them anyway,
@@ -5202,7 +5747,9 @@ shape, before anything is written. Writes to the machine file take its lock
 and replace it atomically; a committed write keeps the file's other keys and
 indentation. Run \`stim settings\` from the app directory: workspace and
 committed resolve from the nearest package.json, repo from its Git
-repository. worktree.exclude and worktree.defaultBranch are read only from
+repository. From a monorepo web package that resolves to its worktree's app
+(see stim guide ports), workspace and committed are that app's entry and
+.stim.json. worktree.exclude and worktree.defaultBranch are read only from
 the repo layer and the repository root's .stim.json.
 
 android.keystorePassword is sensitive: its value prints as ******** in every
@@ -5332,6 +5879,12 @@ KEYS STIM READS
                         profile. When this workspace already owns an AVD of
                         another profile, a requested profile refuses rather
                         than booting it; reap the AVD to create the new one.
+                        "pixel_fold" and "resizable" need a system image
+                        whose advancedFeatures.ini turns on SupportPixelFold
+                        (recent images such as API 34 google_apis do); the
+                        emulator quits on boot without it, so Stim refuses
+                        the pair with
+                        STIM_BAD_ARG and names an installed image that has it.
                         Existing AVDs keep their display settings; parked AVDs
                         from the old generic profile are not adopted.
   android.dataPartitionSizeGb
@@ -5360,6 +5913,10 @@ ${ANDROID_AVD_CONFIG_HELP.map((line) => `                          ${line}`).joi
                         keys are protected. The emulator may normalize a valid
                         value. These overrides apply only to a newly created
                         AVD; existing and recovered AVDs are never rewritten.
+                        Unless these settings set hw.keyboard, every AVD Stim
+                        creates gets hw.keyboard=yes, so the emulator takes
+                        gRPC key events. The one rewrite: a parked AVD created
+                        before that default gets it when a workspace adopts it.
                         On displayless Linux, Stim launches with
                         -gpu swiftshader_indirect -noaudio; those arguments
                         override hw.gpu.enabled, hw.gpu.mode, hw.audioInput,
@@ -5442,6 +5999,21 @@ ${ANDROID_AVD_CONFIG_HELP.map((line) => `                          ${line}`).joi
                         driven. Read
                         when \`start\` spawns the supervisor; see
                         \`guide metro\`.
+  web.url               the page \`stim web\` opens in the owned Chrome, an
+                        http:// or https:// URL. {port:<label>} becomes the
+                        workspace's named port (allocated like \`stim ports
+                        get <label>\`), and {port:metro} its Metro port.
+                        Unset, Expo apps open http://localhost:<metroPort>/
+                        and other apps refuse until it is set. Example:
+                        http://localhost:{port:web}/apps/groups/.
+                        See \`guide web\`.
+  web.ignoreCertificateErrors
+                        true starts the owned Chrome with
+                        --ignore-certificate-errors, for dev servers with
+                        self-signed certificates (default false). It applies
+                        only to Stim's own profile, never to your browser.
+  web.viewport          desktop (default, 1280x800) or phone (390x844 at 3x
+                        with touch events) for the owned Chrome page.
   worktree.exclude      ignored-path skip list for worktree warm. Settings
                         come from the source checkout's repository-root
                         .stim.json. A nonempty .worktreeexclude in the source
@@ -5484,7 +6056,7 @@ ${ANDROID_AVD_CONFIG_HELP.map((line) => `                          ${line}`).joi
                         them from the environment or the machine layers.
 
 Each setting takes its documented type: string, array of strings, number,
-boolean, or object. ios.remote, android.remote, metro.tunnel,
+boolean, or object. ios.remote, android.remote, metro.tunnel, web.viewport,
 optimizations.android.compilerCache and optimizations.android.pch take only
 their listed choices. A value of the wrong
 type or outside those choices is refused by name on every command that resolves
@@ -5543,8 +6115,13 @@ STIM_BAD_ARG. See \`guide lifecycle budget\` for what each limit reclaims.
 THE IOS SIMULATOR APP IS MACHINE-LEVEL
 Top-level \`iosSimulatorApp\` in ~/.stim/config.json selects the macOS app that
 displays Stim's owned local iOS simulator after boot. It is not a project
-setting. Unset or \`"xcode"\` opens the selected Xcode's Device Hub on Xcode 27,
-or Simulator on older Xcode. To use an installed Siniulator instead:
+setting. Unset, it is \`"stim-desktop"\` while Stim Desktop is installed and
+\`"xcode"\` otherwise. \`"xcode"\` opens the selected Xcode's Device Hub on Xcode 27,
+or Simulator on older Xcode. On Xcode 27 (confirmed on 27A266a), quitting
+Device Hub by default shuts down every booted simulator on the machine,
+including ones it never opened a window for and ones other workspaces or
+agents are using; never quit it to free memory or clean up. To use an
+installed Siniulator instead:
 
   { "iosSimulatorApp": "siniulator" }
 
@@ -5554,6 +6131,10 @@ To show the booted simulator in Stim Desktop and open no simulator window:
 
 Stim Desktop selects the workspace that owns the simulator and focuses that
 device. It only displays the simulator; it never boots or shuts it down.
+When Stim Desktop is not running, Stim starts it without the command's
+\`STIM_HOME\`, so it reads the same Stim home as when you open it yourself.
+It shows only devices from that home: under another \`STIM_HOME\`, pick
+\`--simulator-app xcode\` to see the simulator.
 
 Override the preference for one local launch with
 \`stim ios --simulator-app siniulator\`, \`stim ios --simulator-app stim-desktop\`,
@@ -5570,9 +6151,10 @@ window behavior.
 
 THE ANDROID EMULATOR APP IS MACHINE-LEVEL
 Top-level \`androidEmulatorApp\` in ~/.stim/config.json selects how an owned
-Android emulator that Stim boots on macOS is displayed. Unset or
-\`"emulator"\` opens the emulator's own window. To boot it headlessly and show
-it in Stim Desktop instead:
+Android emulator that Stim boots on macOS is displayed. Unset, it is
+\`"stim-desktop"\` while Stim Desktop is installed and \`"emulator"\`
+otherwise. \`"emulator"\` opens the emulator's own window. To boot it
+headlessly and show it in Stim Desktop:
 
   { "androidEmulatorApp": "stim-desktop" }
 
@@ -5581,8 +6163,17 @@ Stim then starts the emulator with \`-no-window -gpu host\` and opens
 frames and sends input over the emulator's gRPC endpoint. The setting applies
 only when Stim boots the emulator: one that is already running keeps its
 current display until it next boots, and physical devices are unaffected.
-An invalid value refuses before boot. On Linux and Windows the setting has
-no effect.
+Like the iOS viewer, it starts Stim Desktop without the command's
+\`STIM_HOME\`. An invalid value refuses before boot. On Linux and Windows the
+setting has no effect.
+
+Stim finds Stim Desktop by its bundle id, dev.stim.desktop, in Launch Services.
+A command Stim Desktop runs skips that lookup: Desktop sets \`STIM_DESKTOP_APP\`
+to its app path for every command it starts.
+\`stim settings\` shows that default as \`(default: Stim Desktop installed)\`,
+\`settings get\` prints it on stderr, and \`--json\` adds
+\`"defaultReason": "Stim Desktop installed"\`. A set value always wins; set
+\`"xcode"\` or \`"emulator"\` to keep the device windows.
 
 THE DEVICE POOL BOUNDS ARE MACHINE-LEVEL TOO
 \`pool.iosParkedMax\` caps how many parked simulators \`worktree remove\` may
@@ -5614,6 +6205,22 @@ test suites and the end-to-end harness use one -- and a scoped config must not
 leave simulators on the machine it cannot account for. A redirected home that
 wants a pool says so with the variable.
 
+THE GC WORKTREE GRACE PERIOD IS MACHINE-LEVEL
+\`gc.worktreeGraceMinutes\` is how long \`gc --delete\` waits before it removes
+a merged or idle linked worktree. The clock starts at the worktree's latest
+activity: a write to its git index, HEAD or HEAD reflog, its Stim workspace
+state or logs, the merge of its branch into the default branch, or when its
+pull request was merged or closed.
+
+  {
+    "gc": { "worktreeGraceMinutes": 120 }
+  }
+
+in ~/.stim/config.json, or STIM_GC_WORKTREE_GRACE_MINUTES in the environment,
+which overrides the file. Absent means 120. \`0\` removes a finished worktree at
+once. A value that is not a whole number 0 or more is warned about by \`gc\`,
+which then uses 120. See \`guide cleanup\` for what else keeps a worktree.
+
 STIM NEEDS NO PROJECT CHANGES TO RUN
 Nothing above is required to use Stim. The performance caches that used to
 be setup steps are supplied by Stim on the command lines it composes itself:
@@ -5841,6 +6448,176 @@ platform instead of one entry. Pass prune: 'atomic' for a cache whose index
 references its own data (an LLVM CAS): it is then left alone by --older-than
 and emptied whole only by 'gc --delete --cache all'.
 Registration is idempotent and keyed on the directory.`
+	},
+	web: {
+		summary: "stim web: an owned headless Chrome per workspace, its logs, launched, and teardown",
+		body: () => `WEB: AN OWNED CHROME PER WORKSPACE
+
+If Stim is not installed globally, replace stim with npx stim.
+
+stim web opens this workspace's page in a Chrome that Stim owns, captures the
+page's console, uncaught errors and failed requests in stim logs, and reports
+whether the page loaded. It uses the installed Google Chrome (or Chromium)
+with a profile Stim creates under STIM_HOME. Stim never installs a browser;
+stim doctor reports a missing Chrome.
+
+stim web never starts a web server, for any framework. It opens, reuses or
+reloads the owned Chrome at the page URL. Every web project follows the same
+two steps: start your dev server, then run stim web.
+
+  stim web                 # headless, the default
+  stim web --headed        # show the Chrome window
+  stim web --json          # one payload on stdout; progress on stderr
+  stim logs --errors       # page errors land here with platform "web"
+  stim reload web          # Page.reload on the owned page
+  stim stop                # closes Chrome with the rest; the profile stays
+
+WHICH PAGE AND WHICH DEV SERVER
+
+Expo web runs on the workspace's Metro. With web.url unset, an Expo app
+opens http://localhost:<metroPort>/. Its dev server is stim start:
+
+  npx expo install react-dom react-native-web @expo/metro-runtime   # once
+  stim start
+  stim web
+
+Any other web server (Vite, Next, webpack) starts with its own command.
+Reserve its port with stim ports get, start it with strict-port behavior, and
+point web.url at it. {port:<label>} in web.url becomes that named port,
+{port:metro} the Metro port:
+
+  pnpm exec vite --port "$(stim ports get web)" --strictPort
+  stim settings set web.url 'http://localhost:{port:web}/' --scope workspace
+  stim web
+
+When nothing serves the page, stim web still opens Chrome, reports launched
+"unverified", and prints the remedy for this workspace: stim start for an
+Expo web app, the stim ports get web recipe for any other server. A Metro
+port held by another process is also "unverified", and the page it serves
+still reaches stim logs; stim start then reserves a free port for this
+workspace. When this workspace's supervisor is still recorded, run stim stop
+first.
+
+In a monorepo whose web app is its own package (apps/web beside apps/mobile),
+stim ports, web, settings, logs, reload, stop and status run from the web
+package resolve to the one Stim app registered in the same Git worktree; each
+names the app on stderr, and status stars it. The port, the browser, web.url
+and the logs all belong to that app's workspace, so every command can run from
+the web package. Register the app first, from its directory. See stim guide
+ports for the exact rule.
+
+HTTPS dev servers with a self-signed certificate, such as Vite with
+@vitejs/plugin-basic-ssl, fail with net::ERR_CERT_AUTHORITY_INVALID until
+web.ignoreCertificateErrors is true, which accepts the certificate in the
+owned profile only:
+  stim settings set web.url 'https://localhost:{port:web}/' --scope workspace
+  stim settings set web.ignoreCertificateErrors true --scope workspace
+An https:// URL on a plain HTTP server fails with ERR_SSL_PROTOCOL_ERROR, and
+an http:// URL on an HTTPS server with ERR_EMPTY_RESPONSE; the remedy line
+prints the settings command that switches the scheme. web.viewport phone
+gives the page a 390x844 touch screen at 3x instead of the 1280x800 desktop
+window. See stim guide settings.
+
+MONOREPO RECIPE: A VITE PACKAGE WITH A BASE PATH AND HTTPS
+
+apps/web runs Vite through its dev script, serves the app under /apps/groups/,
+and uses @vitejs/plugin-basic-ssl; apps/mobile is the Stim app. The flow is
+the same as for any web project: start the dev server, then run stim web.
+
+  cd apps/mobile && stim ports get web     # registers the app; no Metro
+  cd ../web
+  stim settings set web.url 'https://localhost:{port:web}/apps/groups/' --scope repo
+  stim settings set web.ignoreCertificateErrors true --scope repo
+  pnpm dev --port "$(stim ports get web)" --strictPort   # keep it running
+  stim web
+  stim logs --errors
+  stim reload web
+  stim stop               # closes Chrome; stim ports stop web stops Vite
+  stim worktree remove    # in a linked worktree: Chrome, Vite and profile
+
+The repo layer is shared by every worktree of the repository, so a new
+worktree skips the two settings lines; the certificate and scheme remedies
+print --scope workspace, which overrides it for one worktree only. Run ports
+get from the app directory before any ports or web command in the web
+package: a reservation made there first keeps the web package as its own
+workspace until you release it and stop. Pass --port and --strictPort
+through the dev script: Vite otherwise binds its config default and moves to
+the next free port when that one is taken. Put the base path in web.url: a
+path outside it can reach the dev server's proxy instead of the app. API
+calls the dev server proxies to a backend that is not running fail as device
+errors in stim logs --errors; the page still loads.
+
+LAUNCHED
+
+The web payload's launched keeps its native meaning, from evidence in the
+owned page rather than a shared port:
+  true           the page's document answered and its load event fired; on
+                 Metro, the page also fetched a web bundle
+  "bundling"     Metro was still building the web bundle when the check ended
+  "unverified"   the document failed (for example ERR_CONNECTION_REFUSED:
+                 the dev server is not running, or ERR_CERT_AUTHORITY_INVALID: a
+                 self-signed certificate), loaded without a Metro bundle, or
+                 did not finish: 20 seconds with no answer, 60 once a server
+                 other than Metro answered. The remedy line names the fix
+false is never produced. A page that loads and then throws is still launched
+true; read stim logs --errors.
+
+A second stim web with the same options reuses the running Chrome and
+navigates it again. Changing --headed, web.viewport or the certificate
+setting restarts it.
+
+LOGS
+
+Records go to web.ndjson in the workspace log directory, all with
+platform "web":
+  src client   console calls at their level (console.error is error) and
+               uncaught errors and rejections, with stack frames
+  src device   failed requests, which stim logs --errors includes: a failed
+               page document is error whatever its
+               status; another request's network failure or HTTP 5xx is
+               error, a 4xx warn, a canceled request debug; browser messages such
+               as CSP violations; the browser's own lifecycle
+Expo also prints web console calls on Metro ("Web LOG"), so they can appear
+twice: once from the page (client), once from Metro (metro, level info).
+Each load of the page's top-level document is a page-load marker: stim web,
+stim reload, and a reload or navigation the page makes itself. logs --errors
+and the status error count report the page's records (platform web) from the
+latest load only, the way Chrome DevTools clears its console when the page
+navigates. A page load does not hide the native app's errors, and an ios or
+android launch does not hide the page's.
+
+AGENTS AND OTHER TOOLS ON THE SAME BROWSER
+
+stim status --json shows environments[].web.cdpEndpoint, a reserved loopback
+DevTools endpoint on 127.0.0.1. Point browser tools at it instead of letting
+them start their own browser:
+  Playwright MCP    --cdp-endpoint http://127.0.0.1:<port>
+  agent-browser     --cdp <port>
+The port reaches only the Stim profile: Chrome refuses remote debugging on
+your default profile, and Stim never attaches to a browser it did not start.
+The port is managed like metro: stim ports lists it as web-cdp (managed),
+and ports get, stop and release refuse it.
+
+OWNERSHIP AND CLEANUP
+
+A browser supervisor process holds the DevTools session and an ownership
+claim for its lifetime; Chrome is the claim's child. Stim signals the
+supervisor or Chrome only after verifying the process identity it recorded.
+  stim stop               closes Chrome and keeps the profile, so cookies and
+                          storage survive the next stim web
+  stim worktree remove    closes Chrome and deletes the profile
+  stim gc --delete        does the same for a workspace whose path is gone,
+                          and forgets ledger entries of deleted profiles
+The profile is deleted only when the created-devices ledger lists it. After
+Chrome is gone, Stim removes the SingletonLock files a killed Chrome leaves,
+which would otherwise block the next launch. status reports
+browser-unverified when an identity cannot be proven; follow stim guide
+errors teardown.
+
+LIMITS
+
+Chrome and Chromium only. No Stim Desktop or phone viewer yet. The owned page
+is one tab: a page the app opens in a new window is not captured.`
 	}
 };
 //#endregion