stim 1.17.1 → 1.18.0

package/dist/{guide-DC3n6-NH.mjs → guide-tm6igAaa.mjs}

@@ -1,7 +1,7 @@
-import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-Cfd-0r2d.mjs";
-import { s as findProjectRoot$1 } from "./project-D47Rh0ly.mjs";
-import { t as RECENT_LAUNCH_MS } from "./status-CzS4bPO9.mjs";
-import { t as guideStatus } from "./guide-status-Du-ZQ3FD.mjs";
+import { s as findProjectRoot$1 } from "./project-C3ChRLZy.mjs";
+import { t as RECENT_LAUNCH_MS } from "./status-Dcr0Qexd.mjs";
+import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-CQyMElEP.mjs";
+import { t as guideStatus } from "./guide-status-Bhf9SJXc.mjs";
 import { SETTINGS, SETTINGS_SCHEMA_URL } from "@stim-cli/core/state";
 import chalk from "chalk";
 //#region src/guide/agent.ts
@@ -293,6 +293,11 @@ Ask the user before these actions:
   nothing else.
 - gc --delete --worktrees, because it runs worktree remove on every clean,
   idle linked worktree Stim manages, across projects.
+- settings set maintenance.mode on in a home where it is off or report, because
+  it lets Stim itself clear build outputs, trim caches and remove finished
+  worktrees later, with no command from you. It is on by default outside CI
+  and scoped STIM_HOME homes. maintenance.keep true pins a workspace against
+  that; maintenance.mode report or off stops it.
 - stop when the workspace owns an EAS session, because it irreversibly ends
   that remote session. For a local device, stop shuts it down but does not
   delete it. An explicit stop shuts down a Stim-owned simulator even when
@@ -382,6 +387,7 @@ FULL TOPIC LIST
   stim guide lifecycle options    # every flag, Android variants, --device-type, --system-image, --device-profile
   stim guide lifecycle devices    # ios --device and android --device on a physical phone
   stim guide lifecycle release    # Release configurations and ...Release variants
+  stim guide api                  # typed run, stop, diagnostics and cancellation from the main package
   stim guide facts                # the --json payloads
   stim guide facts devmenu        # the Expo dev menu or Tools button over the app
   stim guide macos                # Swift Package Debug apps, logs, local preview, --remote on another Mac
@@ -397,6 +403,64 @@ FULL TOPIC LIST
   stim guide settings             # configuration files and supported keys`
 };
 //#endregion
+//#region src/guide/api.ts
+var api_default = {
+	summary: "Typed lifecycle API: createStim, run, stop, diagnostics, and cancellation",
+	body: () => `PROGRAMMATIC API
+
+Install stim as a project dependency: npm install --save-dev stim.
+Import { createStim, StimError } from 'stim'. Node 22.12 or later is required.
+
+  const stim = createStim({ projectRoot: process.cwd() });
+  try {
+    const result = await stim.run({ platform: 'ios' });
+  } finally {
+    try {
+      const diagnostics = await stim.diagnostics({ errors: true });
+    } finally {
+      const cleanup = await stim.stop();
+      if (!cleanup.ok) throw new Error(cleanup.summary);
+    }
+  }
+
+createStim takes projectRoot, optional absolute home and buildCache paths,
+and onProgress({ stream, message }). message is an output chunk. Without
+onProgress, operations write nothing to the caller's stdout or stderr. Each
+operation uses a bundled worker that calls the same lifecycle operations as
+the CLI; it never parses CLI arguments or changes the caller's cwd/environment.
+
+run takes platform plus its options:
+  ios:     configuration, scheme, deviceType, runtime
+  android: variant, systemImage, deviceProfile
+  macos:   remoteBuild
+  web:     headed (default false)
+iOS and Android also accept slot, metroCheck, buildCache, and remoteBuild.
+All methods accept signal. run builds, installs and launches; build-only is
+not available. Web requires a running server, just like stim web.
+
+run returns { platform, facts }. iOS facts include udid; Android includes
+serial; both include bundleId, appPath, metroPort, cacheHit and launched.
+macOS facts include bundle, bundleId, executable, pid, build and launched.
+Web facts contain the owned browser's existing launch and page facts.
+Do not interpret 'bundling' or 'unverified' as proven application readiness.
+
+stop({ slot? }) returns { ok, outcomes, summary }. It acts on the workspace,
+including resources from earlier runs. Use a dedicated workspace in CI.
+Cancellation waits for the operation worker to exit; stop with a fresh signal
+after cancellation or partial failure. Always inspect cleanup.ok.
+
+diagnostics({ tail: 200, errors: false }) returns { directory, records } from
+the local timeline, even before a successful run. tail: 0 returns paths only.
+It does not fetch remote logs or capture new crashes. Stim failures reject with
+StimError carrying code, message, remedy and details (including the log path).
+An exception thrown by onProgress cancels its worker and propagates unchanged.
+
+Normal ownership, device creation, cache locks and coordination remain active.
+All concurrent artifact-cache writers must share the same coordinating home.
+Do not point independent Stim homes at a concurrently writable shared cache.
+`
+};
+//#endregion
 //#region src/guide/facts.ts
 const facts = {
 	summary: "The --json payloads: `start`, `ios`, `android`, `web`, `ios|android --plan`, `reload`, `stop`, `status`, `doctor`, `device lock`/`unlock`, `gc`, and the error contract",
@@ -910,9 +974,9 @@ leased until <time>" for each one.`,
                   null when off; plan lists what the next start, ios or
                   android would reclaim, in the \`reclaimed\` shape without
                   freedMb, and is empty while under budget
-  deviceHosts     one { machine, state, dnsName?, deviceId?, requestedAt?, host? }
-                  per remote.machines entry. state is "approved", "pending",
-                  "not-asked", "revoked", "node-changed", "not-on-tailnet",
+  deviceHosts     one { machine, state, dnsName?, deviceId?, requestedAt?, expiresAt?,
+                  host? } per remote.machines entry. state is "approved",
+                  "pending", "not-asked", "revoked", "lapsed", "node-changed", "not-on-tailnet",
                   "tailscale-off", "unreachable", "invalid",
                   "credentials-unavailable" or "busy". Tokens stay private.
                   Only --fix asks for access or forgets removed names.
@@ -920,13 +984,17 @@ leased until <time>" for each one.`,
                   build approval; see \`guide settings\`.
                   host is { name, screenRecording, accessibility }, present
                   only for approved machines whose worker reports it.
+                  expiresAt is when a pending request lapses; "lapsed" is
+                  a pending request whose expiry passed. --fix asks again.
   remoteMachines  one { machine, state, dnsName?, deviceId?, requestedAt?,
-                  offloadable?, reasons?, problems?, capacity?, host? } per
+                  expiresAt?, offloadable?, reasons?, problems?, capacity?, host? } per
                   remote.machines entry, for its build approval; state is "approved", "pending", "not-asked",
-                  "revoked" (revoked, or the request lapsed), "node-changed",
+                  "revoked" (revoked or denied), "lapsed" (the request lapsed
+                  before approval), "node-changed",
                   "not-on-tailnet", "tailscale-off", "unreachable" or
                   "invalid". host has the same shape and presence rule as in
-                  deviceHosts. An approved machine also carries offloadable,
+                  deviceHosts, as do expiresAt (a pending request's lapse
+                  time) and "lapsed" (--fix asks again). An approved machine also carries offloadable,
                   true when it would take this app's builds now (iOS
                   simulator unless --platform android, Android emulator when
                   --platform android or the app has android/ or uses Expo,
@@ -941,7 +1009,7 @@ leased until <time>" for each one.`,
                   reasons as { code, reason } with that code. capacity
                   is the machine's offer: { running, max, diskFreeBytes,
                   minDiskFreeBytes, cpus?, loadPerCore?, builds?, maxBuilds?,
-                  maxLoadPerCore?, declined? }; an older stim-server omits the
+                  maxLoadPerCore?, memoryUsedBytes?, memoryTotalBytes?, declined? }; an older stim-server omits the
                   optional fields
   findings        the diagnostic findings; a lower resolved Stim is a
                   costs-time finding with a PATH or installation remedy
@@ -1199,7 +1267,7 @@ RULES
                     cannot read. A macOS privacy denial (EPERM) names the
                     Privacy & Security setting to grant
   maintenance     top-level { mode, pressure, actions, blocked,
-                  skips, note, invalid? }, the next report-only maintenance plan
+                  skips, note, invalid? }, the next maintenance plan
                   from live pressure and cached sizes. note says when no
                   pass has run yet. No du runs for this preview.
   sections        one array per report section, in the text order. Every key
@@ -1374,8 +1442,8 @@ RULES
               "ready"    its last warm succeeded and nothing has run there
                          since: no start, ios, android, web or reload, for
                          at most 2 hours
-              "live"     live is true: Metro, a device, Chrome or a remote
-                         session of it runs
+              "live"     the workspace is active (live is true): Metro, a
+                         device, Chrome or a remote session of it runs
               "idle"     none of these
   phaseSince  when the warm started ("warming") or finished ("ready"); null
               for "live" and "idle"
@@ -1403,8 +1471,8 @@ RULES
   The first kind that applies wins:
 
   kind        "building"      a build runs; platform names it
-              "warming"       phase is "warming" and nothing is live
-              "ready"         phase is "ready" and nothing is live
+              "warming"       phase is "warming" and nothing is active
+              "ready"         phase is "ready" and nothing is active
               "build-failed"  the newest run of either platform failed;
                               platform names it
               "running"       live is true or a remote session runs
@@ -1688,7 +1756,8 @@ RULES
                    with detail), install (staging the bundle, or fetching
                    it from a build machine) and launch. It has no cache
                    lookup: outcome is null, plannedPhases is null, and
-                   builds.macos holds its finished runs and their phases.
+                   builds.macos holds its finished runs, their phases and
+                   compileSteps.
   startedAt        when the run started; phaseStartedAt when its phase did
   outcome          "cold" after the local/provider lookups resolve a miss;
                    "hit" after a cached artifact is ready to reuse, including
@@ -1884,7 +1953,7 @@ RULES
                       under CoreSimulator/Devices, or the AVD's .avd folder
 
   \`status --watch\` runs one du at a time off its refresh path, and measures
-  a folder at most every 5 minutes while its environment is live and every
+  a folder at most every 5 minutes while its environment is active and every
   hour otherwise. It caches each size under $STIM_HOME/disk-usage, which
   one-shot status only reads, so the fields appear once a watcher, such as
   stim-server or Stim Desktop, has measured.
@@ -1953,13 +2022,15 @@ RULES
   and always uses the estimate. What is using CPU and memory now is the
   top-level machine section:
 
-  maintenance { mode, lastChecks: { pressure, size }, pressure, sizes,
+  maintenance { mode, lastChecks: { pressure, size, worktree, sweep }, pressure, sizes,
                 lastPass, running, recent, plan, invalid?, claim? }
-    Report-only observations; every plan action's kind starts with would-.
+    mode is off, report or on. Plan actions start with would-; the records
+    of actions taken drop the prefix (clear-outputs, trim-cache, empty-cache,
+    remove-worktree, remove-orphan, unregister-cache).
     lastChecks are epoch milliseconds or null. running comes only from a
     live maintenance/run.claims owner, never from a check stamp.
-    lastPass carries startedAt, durationMs, trigger, mode, freedBytes (0),
-    actions, stopped (0), blocked. recent holds the last 20 action, failure
+    lastPass carries startedAt, durationMs, trigger, mode, freedBytes
+    (0 in report mode), actions, stopped (0), blocked. recent holds the last 20 action, failure
     and blocked NDJSON records from maintenance/maintenance.ndjson.
     invalid names invalid settings; invalid cache caps use their defaults,
     while invalid maintenance settings disable passes. claim contains an
@@ -2004,7 +2075,7 @@ RULES
   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 one run of the footprint helper. It is null when no
-  simulator is booted, no workspace is live and no build runs: status then
+  simulator is booted, no workspace is active and no build runs: status then
   runs neither. \`status --watch --json\` rereads both every 15 seconds while
   machine is not null, with no other subprocess.`
 		},
@@ -2014,7 +2085,7 @@ RULES
 
   { platform, slot?, fingerprint, cacheKey, cacheHit, provider,
     cacheSkipped, prebuild, outcome, expectedMs, basis, missReason?,
-    refusal? }
+    placement?, refusal? }
 
   fingerprint   the fingerprint the run would look up first; with
                 --eas-profile, the one EAS CLI computes
@@ -2040,6 +2111,9 @@ RULES
                 plan does not, so changes compare the fingerprint before that
                 prebuild; changeCount 0 then means those inputs match the
                 baseline. rekeyedBy is empty.
+  placement     with ios.remote or android.remote set to auto or a Mac,
+                where the plan assumes the device runs: "on <machine>" or
+                "this Mac; auto may use <machines>"; absent otherwise
   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
@@ -2642,7 +2716,7 @@ FLAGS
   --slot <name>   only this slot's records plus, once it has launched, the
                   shared untagged Metro and app client records (not the web
                   page's); default also includes untagged legacy records
-  --source <s...>  metro, client, device, build, agent, maintenance (one or more), or all.
+  --source <s...>  metro, client, device, build, agent, maintenance, placement (one or more), or all.
                    An unknown value is REJECTED rather than quietly matching
                    nothing.
   --level <l>      minimum level: debug, info, warn, error, fatal
@@ -2779,6 +2853,12 @@ THE RECORD
     event    the producer's own event name (bundle_build_done, client_log, ...)
     stack    frames of { file, line, column, fn }, passed through as reported
     marker   true on the records that close an error window
+    runId    the id of the stim invocation that wrote the record: STIM_RUN_ID
+             when set to a valid id (letters, digits, . _ -, at most 64),
+             else generated per run. Processes a command starts, such as the
+             Metro supervisor and the collectors, keep the id of the command
+             that started them. Debug records and the hello to stim-server
+             carry it too, and stim-server puts it on its log lines.
     deviceTs Android logcat's original epoch milliseconds; ts is aligned to
              host time using a bounded clock query at each collector attachment
     clockOffsetMs the offset added to deviceTs; absent if the query failed.
@@ -2796,6 +2876,59 @@ Add --errors to --source maintenance to show only maintenance_failure events;
 failures before a later launch marker are hidden. Machine passes are reported in
 status and maintenance/maintenance.ndjson; this command reads workspace logs.
 
+REMOTE REQUEST RECORDS
+A request to another Mac that fails is a warn record with src: build in the
+run's build log: remote_connect_failed { host, capability, ms, timeoutMs, msg,
+code } (could not connect or say hello, e.g. "no reply in time" when the Mac
+did not answer hello) and remote_request_failed { method, ms, code, msg }.
+Timings of requests that succeed are debug records (below).
+stim-server writes to its service log (~/Library/Logs/Stim/<label>.log), with
+no tokens or tickets: "request failed method=<m> client=<device id> run=<runId>
+ms=<n> error=<code>" for an error reply (once a minute per client, method and
+code) and "host_connect ... error=<reason_with_underscores>" when its connection to a hosting
+Mac fails. With debug.logs on or STIM_DEBUG=1 for the server it logs every
+request instead: "debug request method=<m> client=<id> run=<runId> ms=<n>
+slow=true error=<code> whois=<ms> probe=<ms>" (slow means 1000 ms or more;
+whois and probe are the hello's Tailscale identity lookup and its wait for
+the host permission probe; a method name that is not a plain dotted lowercase
+name is logged as unknown)
+and "debug host_connect host=<mac> ms=<n> connectMs=<n> helloMs=<n>" (reused=true instead of the two
+timings when an open connection was shared), also as
+records in STIM_HOME/logs/debug/server.ndjson. Search the run id in both logs.
+
+DEBUG LOGS
+With debug.logs on or STIM_DEBUG=1 (stim guide settings), the CLI also appends
+debug records to STIM_HOME/logs/debug/cli.ndjson, outside any workspace, so
+stim logs does not show them. Read them with jq:
+  jq -c 'select(.event=="exec" and .ms>1000)' ~/.stim/logs/debug/cli.ndjson
+Events: run_start, run_end { exit, ms }, exec { program, ms, ok, exit? }, and
+remote_connect and remote_request { ms, ok, code? } for requests to another
+Mac. They carry no arguments, tokens or tickets.
+
+Placement records use src: placement and sit in the run's build log
+(build-*.ndjson), so a new run replaces the previous run's. A run writes one
+record per decision it makes (a build that compiles and has a remote Mac to
+consider, or ios/android --remote auto), with event build_placement,
+device_placement or placement_fallback. A cache hit, a project with no paired
+remote Mac and a named --remote target write none:
+  stim logs --source placement
+  stim logs --source placement --json
+Fields: kind (build or device), platform, settings [{ key, value, from }] with
+from flag, env, setting or default (remote.build and remote.buildMode for a
+build, ios.remote or android.remote for a device), candidates [{ machine, code,
+msg, detail? }], choice { machine, code, msg } with machine local when the run
+stays on this Mac, and fallback { code, msg, machine? } when a remote Mac that
+was meant to take the run did not (level warn). The msg is the same text the
+placement: and build: phase lines print.
+Candidate codes: accepted, unreachable, busy, disk, load, version-mismatch
+(detail lists the toolchain parts: xcode, arch, jdk, ...), no-matching-device,
+declined, memory, no-capacity. Choice codes for a build: placed, named,
+forced, this-mac-busy, this-mac-free, mode-off, local-selected, no-remote-mac,
+unsupported; fallback codes: no-remote-mac-took-it, offload-failed, fallback.
+Choice codes for a device: placed, sticky, this-mac-free, no-remote-mac,
+device-count-unknown, no-host-admits. Machine names appear in these records;
+they stay in the local logs. These records carry no tokens.
+
 WHAT WRITES WHAT
   maintenance.ndjson   workspace maintenance actions, failures and explaining skips
   metro.ndjson         the bundler, in both supervisor modes
@@ -3001,6 +3134,9 @@ Branch on the code, never on the message.`,
   an unavailable choice. A session that exists stays recorded even if delivery
   fails: retry stim ios|android --remote <machine>, or run stim stop to reconcile it.
   An unreachable stop keeps the placement; rerun stim stop when the host answers.
+  To see why a host was slow or refused: stim logs --source placement (hosts checked and
+  reason codes), stim logs --source build (remote_connect_failed, remote_request_failed),
+  and the host's stim-server service log, searched for the run id (stim guide logs).
   A failed build handoff uses upload instead. If native log queries are unavailable,
   logs prints a note on stderr and shows copied records. Update an older stim-server
   on the host to enable handoff and native logs (hello features hosted-ios-data
@@ -4393,7 +4529,12 @@ not on any remote"  (worktree remove)
   Warm copied ignored Pods from the source checkout, but their Manifest.lock
   differs from the tracked Podfile.lock in this worktree. Warm does not change
   tracked files. Run the printed pod-install command before building directly.
-  \`stim ios\` detects a mismatch and runs \`pod install\` for you.
+  \`stim ios\` detects a mismatch and runs \`pod install\` for you. A mismatch
+  limited to checksums of podspecs that embed the source checkout's path is
+  resolved by warm itself ("carry moved <dir>/Pods to this checkout's path")
+  and does not print this line. When the locks match but Pods still name the
+  source path and warm cannot move it, it prints "removed <dir>/Pods/Manifest.lock
+  so pod install runs" and \`stim ios\` runs \`pod install\`.
 
 "carry       carried <dir>/Pods but there is no <dir>/Podfile.lock"
   Warm copied Pods but the destination has no Podfile.lock. Follow the printed
@@ -4519,6 +4660,22 @@ not on any remote"  (worktree remove)
   Expo build-cache provider would each use a different store. Set the named
   variable to an absolute path, or unset it to use the default. Metro and the
   cache provider, which cannot refuse, ignore a relative value with a warning.`
+		},
+		STIM_WORKER_FAILED: {
+			summary: "a programmatic API worker exited without returning an operation result",
+			body: () => `STIM_WORKER_FAILED  (programmatic API)
+  The worker process ended without a structured result. StimError.details
+  includes its final stderr output. Inspect that output and call diagnostics()
+  for existing workspace logs, then stop() with a fresh signal to clean up
+  any resources created before the failure. See stim guide api.`
+		},
+		STIM_RUN_FAILED: {
+			summary: "a programmatic operation failed without a more specific Stim code",
+			body: () => `STIM_RUN_FAILED  (programmatic API)
+  The underlying operation threw an error without a specific code. Its
+  message and workspace log path are preserved in StimError. Read diagnostics()
+  and call stop() in cleanup, including after a partial run. If the error is
+  unexpected, report its message and logs at github.com/appandflow/stim/issues.`
 		},
 		STIM_NODE_UNSUPPORTED: {
 			summary: "stim or stim-server started on a Node older than 22.12.0, often a project pin",
@@ -4775,7 +4932,7 @@ STOP DURING A BUILD
 
 CAPACITY
   A booted iOS sim is roughly 1-2 GB of RAM, an Android emulator 2-3 GB. On a
-  16 GB machine plan for 2-3 live environments. Nothing enforces this;
+  16 GB machine plan for 2-3 active environments. Nothing enforces this;
   \`stim status\` is how you check -- it reports every workspace on the
   machine, not just this one.
 
@@ -4982,6 +5139,8 @@ offload resolves later, after the device architecture is known.
 When no host admits, auto runs here and may wait in the existing FIFO device
 slot queue; --no-wait and --wait 0 refuse with STIM_AT_CAPACITY. The placement
 line explains the decision and the skipped hosts. JSON progress goes to stderr.
+The same decision, with a reason code per host, is a src: placement record in
+stim logs (stim guide logs).
 A recorded hosted session wins over load; a live local owned slot stays here.
 A stopped recorded session places again; unreachable or unknown sessions refuse.
 
@@ -5732,8 +5891,16 @@ PREDICTING THE NEXT BUILD (--plan)
   An Android plan reads the ABI from the emulator the slot records, or from
   the system image a new one would use. A plan refuses --device, --remote,
   --wait, --no-wait, --no-metro-check and --simulator-app with STIM_BAD_ARG.
-  Without --eas-profile it also refuses the ios.remote and android.remote
-  settings with STIM_BAD_ARG. Without --eas-profile an Android plan also
+  With ios.remote or android.remote set to a Mac name, a plan reads the
+  architecture or ABI from that Mac's device offer, the question a run asks
+  before it reserves anything. With auto it repeats the placement decision a
+  run would make now and reports where in the payload's placement field, for
+  example "this Mac; auto may use janics-mac-mini". When the plan stays on
+  this Mac and a listed Mac would build for another architecture, placement
+  says so, since that Mac's key differs. The plan only predicts the key: a
+  run reads the architecture of the device it actually gets. A Mac that does
+  not answer, or ios.remote or android.remote set to eas or proxy, refuses
+  with STIM_BAD_ARG. Without --eas-profile an Android plan also
   refuses the experimental compiler CAS with STIM_BAD_ARG, and refuses with
   STIM_NO_DEVICE when no system image is installed.
 
@@ -6204,7 +6371,7 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
                             and the command to remove that exact claim.
                             See \`guide errors STIM_AT_CAPACITY\`.
 
-  \`stim doctor\` prints one note echoing the caps and the current live count,
+  \`stim doctor\` prints one note echoing the caps and the current active count,
   but ONLY when a cap is set. \`stim gc\` reports stale build slots the way it
   reports stale build locks, and \`gc --delete\` clears them. Set the caps
   with \`stim settings set concurrency.maxBuilds 2\`, by editing
@@ -6220,7 +6387,7 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
                                  $STIM_HOME. Default 20. Below it, Stim reclaims.
     budget.hardFloorDiskGb       default 5. Still below it after reclaiming,
                                  the run refuses with STIM_LOW_DISK.
-    budget.maxCommittedMemoryGb  the rough memory of live environments, the
+    budget.maxCommittedMemoryGb  the rough memory of active environments, the
                                  figure \`stim status\` prints (a booted
                                  simulator 1.5 GB, an emulator 2.5 GB, a dev
                                  server 0.7 GB). Default 60% of physical memory.
@@ -6489,6 +6656,24 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   overlapping a nested destination worktree or below a symlink ancestor.
   Tracked .idea settings come from Git and stay untouched by warm.
 
+  A carried ios/Pods still names the source checkout's path in its generated
+  files and in the checksum of a podspec that embeds that path (the
+  precompiled ExpoModulesCore). When ios/Podfile.lock and the carried
+  ios/Pods/Manifest.lock differ only by those checksums, warm rewrites the
+  source path to the worktree's path in Pods/Target Support Files,
+  Pods.xcodeproj, Local Podspecs and absolute symlinks, then makes
+  Manifest.lock equal Podfile.lock, so the first \`stim ios\` skips
+  \`pod install\`. Any other difference, a missing podspec, or a podspec
+  that does not embed the source path, any other file in Pods that names
+  the source path, or carried node_modules that do not match the worktree's
+  lockfile leaves Pods as copied, and \`pod install\` runs. Warm does not edit Podfile.lock.
+
+  When the two locks already match but the copied Pods still name the source
+  path, warm applies the same rewrite and scan so builds do not read the
+  source checkout's files (entitlements, Podfile.properties.json). If it
+  cannot (stale node_modules, a leftover path, an error), warm deletes
+  ios/Pods/Manifest.lock so \`stim ios\` runs \`pod install\`.
+
   Other generated state stays eligible: .gradle, .cxx, *.tsbuildinfo, build
   directories, and embedded JavaScript need project-specific decisions about
   regeneration. Native intermediates can record the source checkout's paths;
@@ -7038,35 +7223,66 @@ $STIM_HOME/archive by default. See stim guide cleanup archive.
 
 MAINTENANCE
 
-Automatic maintenance is report-only in this release: it measures, plans and
-logs, and never stops or deletes resources. The default mode is report; it is
-off in CI and scoped STIM_HOME homes unless STIM_MAINTENANCE is explicit.
-Commands trigger a detached pass when disk and memory checks (every minute)
-or directory sizes (hourly) are due. guide, settings and help do not trigger
+Automatic maintenance has three modes. on (the default) runs the disk actions
+below through gc's own removal code and logs each one. report measures, plans
+and logs, and never deletes anything. off disables it. It is off in CI and
+scoped STIM_HOME homes unless STIM_MAINTENANCE is explicit, so a scratch home
+or CI run never deletes on its own.
+Commands trigger a detached pass when a check is due: disk and memory pressure
+(every minute), directory sizes (hourly), finished worktrees (every 15
+minutes) and the age sweep (daily). guide, settings and help do not trigger
 it; gc --delete also skips the hook. status --watch also triggers checks.
-Size checks defer under high load. Attempts back off for at least one minute.
-Measured directories are workspace build outputs and Stim's shared native,
-Metro, ccache, Swift compilation and registered caches. Pressure checks read
-free disk on the Stim home, projects and worker root volumes. On macOS the
-memory signal is the sysctl pressure level, with no signal if sysctl fails.
-Other platforms use os.freemem(); macOS never falls back to it.
-Memory pressure is recorded only; memory stops are deferred to a later phase.
+Size, worktree and sweep checks defer under high load. Attempts back off for at
+least one minute. Measured directories are workspace build outputs and Stim's
+shared native, Metro, ccache, Swift compilation and registered caches.
+Pressure checks read free disk on the Stim home, projects and worker root
+volumes. On macOS the memory signal is the sysctl pressure level, with no
+signal if sysctl fails. Other platforms use os.freemem(); macOS never falls
+back to it. Memory pressure is recorded only; stopping devices, dev servers
+and helpers is not automatic.
+
+In on mode a pass runs, cheapest to rebuild first:
+  1. orphaned workspace directories whose project is gone, and registered
+     caches whose directory no longer exists
+  2. build outputs of idle workspaces, over maintenance.workspaceOutputsMaxGb,
+     below the free-disk floor, or unused for maintenance.olderThanDays
+  3. build-cache and Metro entries, least recently used first, down to
+     maintenance.capTargetPercent of caches.buildCacheMaxGb or
+     caches.metroCacheMaxGb, and entries unused for olderThanDays
+  4. the Swift compilation cache, emptied whole, only below
+     budget.hardFloorDiskGb and with no build lock or slot held
+  5. linked worktrees whose branch or pull request finished (gc's finished
+     worktree rules and gc.worktreeGraceMinutes; maintenance.removeFinishedWorktrees)
+Disk-driven steps stop once free space is back above the floor. Kept for
+every pass: a workspace that is in use, holds a lock, was used within
+maintenance.protectRecentHours, is pinned with maintenance.keep, or is the
+workspace of the command that started the pass; cache entries used within
+protectRecentHours, named by a project's last builds, a parked device or a
+live build lock, or in a Metro store with a running or unverifiable dev
+server. Anything the pass cannot verify is kept. A pass never shuts down idle devices or dev servers or stops watchman; removing a
+finished worktree or orphaned directory does tear down that workspace's own
+dev server, owned devices and Chrome profile, as gc --delete does. ccache evicts by itself under
+caches.ccacheMaxGb.
 
   stim status                     last checks, plan and running pass
   stim status --json              maintenance observations and recent records
   stim logs --source maintenance  this workspace's maintenance records
   stim gc                         live pressure and cached-size preview
-  stim settings set maintenance.mode off
+  stim settings set maintenance.mode off     turn automatic cleanup off
+  stim settings set maintenance.mode report  plan and log, delete nothing
 
 The machine log is $STIM_HOME/maintenance/maintenance.ndjson, rotated at
 maintenance.logMaxMb with the old generation retained for
 maintenance.logRetentionDays. Child crashes use maintenance/child.log.
-Actions and explaining skips are logged only when newly planned. A pass is
-logged after a size check or a change to actions, skips or blocked reasons.
+In report mode actions and explaining skips are logged only when newly
+planned; in on mode every action taken, failure and explaining skip is logged
+with its bytes, and a pass record carries the bytes freed. Removal of a
+worktree or orphaned directory is logged to the machine log only.
 maintenance.logChecks enables debug observations; default false.
 status and doctor report invalid settings and unresolved claims with a removal
 command to run only after confirming the holder is gone. Invalid cache caps
 fall back to their own defaults; invalid maintenance settings disable passes.
+Pin a workspace with \`stim settings set maintenance.keep true\` in its project.
 The run claim serializes passes with gc --delete; gc refuses a held claim
 with the holder and recovery guidance instead of waiting.
 
@@ -8263,12 +8479,26 @@ overrides the file:
 budget is off. A value of the wrong shape refuses start, ios and android with
 STIM_BAD_ARG. See \`guide lifecycle budget\` for what each limit reclaims.
 
+DEBUG LOGS ARE MACHINE-LEVEL AND OFF BY DEFAULT
+debug.logs STIM_DEBUG  default false. STIM_DEBUG=1 (or 0) overrides the setting
+for one command. While on, the CLI writes debug records to
+STIM_HOME/logs/debug/cli.ndjson (run_start, run_end, exec with the program name,
+duration and exit status but never arguments, remote_connect and
+remote_request with durations and codes); stim-server writes server.ndjson there
+and logs every request with its timings to its service log. The file rotates at about 8 MiB and keeps one previous
+generation, and nothing is sent anywhere. Keys named like a secret are redacted.
+  stim settings set debug.logs true --scope machine
+See \`guide logs\` for reading the files.
+
 AUTOMATIC MAINTENANCE IS MACHINE-LEVEL
-Report-only in this release: it measures and plans, and deletes or stops nothing.
+maintenance.mode on (the default) removes what gc would under the caps and
+floors below; report measures and plans and deletes nothing; off disables it.
 STIM_HOME and CI make the mode off unless STIM_MAINTENANCE is set.
+maintenance.keep is a project setting: pin a workspace so a pass never clears
+its build outputs or removes its worktree.
 See \`guide cleanup\` for checks, plans and log paths.
 
-${SETTINGS.filter((setting) => setting.key.startsWith("maintenance.") || /^caches\..*MaxGb$/.test(setting.key)).map((setting) => `  ${setting.key}  ${setting.env}  ${setting.default === void 0 ? "unset" : `default ${setting.default}`}
+${SETTINGS.filter((setting) => setting.key.startsWith("maintenance.") || /^caches\..*MaxGb$/.test(setting.key)).map((setting) => `  ${setting.key}  ${setting.env ?? "project setting"}  ${setting.default === void 0 ? "unset" : `default ${setting.default}`}
     ${setting.description}`).join("\n")}
 
 Maintenance uses the sysctl pressure level on macOS, with no memory signal
@@ -8414,7 +8644,7 @@ DEVICE HOSTING
 Only \`doctor --fix\` asks for device-host access. A person on that Mac
 approves the printed id with \`stim-server devices grant <id> --device-host\`.
 A person can also run \`stim-server setup\` on the worker: one node, one ticket,
-one expiry, at most one request per capability, with per-grant y/N in a
+one expiry, at most one request per capability, with a per-grant Y/n question (Enter approves) in a
 terminal or \`--yes\` otherwise. Agents never run \`stim-server setup\` or
 approve requests. Setup never changes TCC or enables Funnel; an SSH-driven
 run is not offered. Without a terminal or --yes, setup refuses before installing
@@ -8422,9 +8652,9 @@ unless every chosen capability already has a matching approval. Desktop reuse
 requires an existing tailnet route. Ctrl-C or SIGTERM completes the journal,
 releases the setup claim and exits 1; a typed N also exits 1. Hosting grants
 include no read, control or build capability.
-On a remote Mac that hosts, Stim Desktop > Settings > Phones > Hosted here lists the
-simulators, emulators and apps approved Macs run there, below Device hosting
-approvals. Stop asks for confirmation, ends the session and deletes or parks
+On a remote Mac that hosts, Stim Desktop > Settings > Remote Macs > Running here lists the
+simulators, emulators and apps approved Macs run there, below Macs using this
+Mac. Stop asks for confirmation, ends the session and deletes or parks
 its device on that Mac. Parked sessions remain listed without Stop. The list
 refreshes every five seconds and stays hidden when the local server does not
 support it.
@@ -8559,10 +8789,12 @@ preferring the one that already holds this repository, then the least loaded,
 and moves to the next one in that order when a machine that offered fails the
 sync or refuses to start the build.
 For iOS the machine's Xcode and simulator SDK must match, and it needs an
-iPhone simulator on the target runtime. Its CocoaPods must match too, unless
+iPhone simulator on the target runtime. Its project-selected CocoaPods must match too, unless
 the app's Gemfile.lock pins CocoaPods: both Macs then run that version through
 bundler, so the machine needs only Bundler on its stim-server PATH and
-installs the pinned gems itself on the first build. For Android its JDK major
+installs the pinned gems itself on the first build. The comparison selects
+the app's .ruby-version when installed, with pod install's UTF-8 locale defaults.
+For Android its JDK major
 version must match, and its Android SDK must hold the NDK, build-tools and
 compile platform that the project's React Native version names in
 gradle/libs.versions.toml; Gradle and AGP come from the synced project. When
@@ -8621,7 +8853,8 @@ login-shell environment would otherwise replace.
 \`stim-server service update --release <version>\` there moves the service to
 that exact stim-server release from the public npm registry once npm verifies
 its integrity and registry signatures; \`--from <dir>\` installs the packed
-packages of a checkout instead. It waits for offloaded builds and hosted
+packages of a checkout instead, with the same signature check on each npm
+dependency but none for Stim's own packages. It waits for offloaded builds and hosted
 sessions to finish, restarts the job, and switches back when the new server
 exits or does not answer within 90 seconds; \`stim-server service rollback\` returns
 to the previous server. A client Mac approved for builds or device hosting
@@ -9152,7 +9385,14 @@ macos.arguments is an array of arguments passed directly to the executable:
 
 The plist must contain CFBundleIdentifier and CFBundleExecutable matching the
 product. Use a development plist without shared URL schemes or an update feed.
-Stim gives the copied bundle a workspace-specific identifier. SwiftPM resource
+Stim gives the copied bundle a workspace-specific identifier and name: it sets
+CFBundleDisplayName and CFBundleName on the copy to "<product> \u00b7 <label>",
+where label is the owned-device label (worktree and app directory names, cleaned
+to letters, digits, . _ -; at most 24 characters, cut with an ellipsis). The Dock,
+Cmd-Tab and lsappinfo show it, so several runs tell apart; the process name in
+System Events stays the executable. The project plist and the app's window titles
+are untouched. The name is displayName in the launch payload and status. Hosted
+(--remote) and offloaded builds get the same name. SwiftPM resource
 bundles and frameworks in the reported build directory are copied into it;
 macos.resources maps destinations under Contents/Resources to file or directory
 sources relative to the Swift Package directory, for example:
@@ -9194,8 +9434,9 @@ platform "macos": phase prepare, compile, install, then launch, and during
 compile detail.unit "steps" with SwiftPM's [done / total] counts (fetching and
 planning are detail.step "configure"). It has no cache lookup, so outcome and
 plannedPhases are null; finished runs and their phase times are in
-environments[].builds.macos. An offloaded build reports the worker's steps the
-same way.
+environments[].builds.macos, where phases includes launch once the launch step finishes
+and compileSteps is SwiftPM's step total. An offloaded build reports the worker's
+steps the same way.
 Runtime stdout and stderr become client records; build output becomes build
 records, all with platform "macos". Unexpected app exits are error records.
 Stim runs the app with NSUnbufferedIO=YES, so Swift print output arrives per
@@ -9649,7 +9890,7 @@ const TUTORIAL_RESTART_PROMPT = "Restart the Stim tutorial.";
 const TUTORIAL_STEPS = [
 	{
 		id: "begin",
-		title: "Create the tutorial",
+		title: "Create the Tutorial",
 		who: "agent",
 		optional: false,
 		prompt: TUTORIAL_PROMPTS.begin,
@@ -9678,7 +9919,7 @@ const TUTORIAL_STEPS = [
 	},
 	{
 		id: "sidebar",
-		title: "Workspace in sidebar",
+		title: "Workspace in Sidebar",
 		who: "you",
 		optional: false,
 		prompt: null,
@@ -9687,7 +9928,7 @@ const TUTORIAL_STEPS = [
 	},
 	{
 		id: "build",
-		title: "First iOS build",
+		title: "First iOS Build",
 		who: "you",
 		optional: false,
 		prompt: null,
@@ -9705,7 +9946,7 @@ const TUTORIAL_STEPS = [
 	},
 	{
 		id: "rebuild",
-		title: "Rebuild from cache",
+		title: "Rebuild from Cache",
 		who: "agent",
 		optional: false,
 		prompt: TUTORIAL_PROMPTS.rebuild,
@@ -9718,7 +9959,7 @@ const TUTORIAL_STEPS = [
 	},
 	{
 		id: "device",
-		title: "Live view and control",
+		title: "Live View and Control",
 		who: "you",
 		optional: false,
 		prompt: null,
@@ -9727,7 +9968,7 @@ const TUTORIAL_STEPS = [
 	},
 	{
 		id: "logs",
-		title: "App logs",
+		title: "App Logs",
 		who: "you",
 		optional: false,
 		prompt: null,
@@ -9736,7 +9977,7 @@ const TUTORIAL_STEPS = [
 	},
 	{
 		id: "agent",
-		title: "Agent actions and replay",
+		title: "Agent Actions and Replay",
 		who: "agent",
 		optional: false,
 		prompt: TUTORIAL_PROMPTS.agent,
@@ -9775,7 +10016,7 @@ const TUTORIAL_STEPS = [
 	},
 	{
 		id: "phone",
-		title: "Watch on your phone",
+		title: "Watch on Your Phone",
 		who: "you",
 		optional: true,
 		prompt: null,
@@ -9784,7 +10025,7 @@ const TUTORIAL_STEPS = [
 	},
 	{
 		id: "machine",
-		title: "Build on another Mac",
+		title: "Build on Another Mac",
 		who: "both",
 		optional: true,
 		prompt: TUTORIAL_PROMPTS.machine,
@@ -9793,7 +10034,7 @@ const TUTORIAL_STEPS = [
 	},
 	{
 		id: "finish",
-		title: "Finish and archive",
+		title: "Finish and Archive",
 		who: "agent",
 		optional: false,
 		prompt: TUTORIAL_PROMPTS.finish,
@@ -9819,6 +10060,7 @@ function commands(id) {
 //#region src/guide/index.ts
 const TOPICS = {
 	agent: agent_default,
+	api: api_default,
 	facts,
 	metro: metro_default,
 	ports: ports_default,
@@ -9966,7 +10208,7 @@ Remove the target-v1 evidence and dismiss-overlay lines before replay: replaying
 them can fail with REPLAY_DIVERGENCE on the recorded button identity.
 The scripts and screenshot stay in the tour worktree and are git-ignored.
 
-PAUSE: end the turn. Point at Agent actions, or the agent log records just
+PAUSE: end the turn. Point at Agent Actions, or the agent log records just
 printed. Expect another error-button line after replay. When screen recording
 is enabled, the user can scrub Replay in Desktop. Give the next prompt:
 "${TUTORIAL_PROMPTS.refresh}".`
@@ -10063,7 +10305,7 @@ first failure. Read stderr and do not continue to later commands. Follow stim gu
 safety. Reuse only this version's tutorial app, never overwrite another folder.
 The creation block skips writes on reuse and checks the repository root.
 
-Replace {base} and {tour} with absolute paths; {base} must end in stim-tutorial. For Agent actions, replace
+Replace {base} and {tour} with absolute paths; {base} must end in stim-tutorial. For Agent Actions, replace
 {stateDir} with agentDevice.stateDir from stim ios or stim status --json;
 when read -r iosUdid waits, type this workspace's ios.udid from that status.
 For the optional machine step,
@@ -10072,9 +10314,9 @@ replace {machine} with a machine you have already approved, or skip it.
 Look at the sidebar during warm and Build during the first build (about four
 minutes on a cold cache). Compare cacheHit and missReason on rebuild. At Live
 view and control, open the device viewer and tap Log an error; without Desktop
-use the simulator. At App logs, try Crash me or Slow request if wanted. A JS
+use the simulator. At App Logs, try Crash me or Slow request if wanted. A JS
 crash shows a red box; the slow request is a local timer, not network capture.
-At Watch on your phone, optionally open an already paired Stim phone to see
+At Watch on Your Phone, optionally open an already paired Stim phone to see
 the tour workspace; phone setup and machine approval stay with you.
 Use stim status, stim logs --errors, and stim stats without Desktop.