stim 1.27.0 → 1.29.0

package/dist/{guide-_rfEh_zM.mjs → guide-CeRlWVsS.mjs}

@@ -1,8 +1,8 @@
-import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-BDVI8Ivc.mjs";
-import { i as findProjectRoot$1 } from "./project-DYj-HVx6.mjs";
-import { h as RECENT_LAUNCH_MS } from "./eas-session-ledger-DrP4OuuM.mjs";
-import { o as guideStatus, t as WATCHMAN_NESTED_WORKTREES } from "./doctor-watchman-CxDbyrrt.mjs";
-import "./status-watch-BfabQn03.mjs";
+import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-D776ygML.mjs";
+import { i as findProjectRoot$1 } from "./project-D1n0K4yg.mjs";
+import { h as RECENT_LAUNCH_MS } from "./eas-session-ledger-B0KLZx5m.mjs";
+import { o as guideStatus, t as WATCHMAN_NESTED_WORKTREES } from "./doctor-watchman-CJr2aXXv.mjs";
+import "./status-watch-okrpea4i.mjs";
 import { SETTINGS, SETTINGS_SCHEMA_URL, TUTORIAL_VERSION } from "@stim-cli/core/state";
 import chalk from "chalk";
 //#region src/guide/agent.ts
@@ -288,6 +288,12 @@ activity prevent reclaim. The supervisor's own idle shutdown default is 30m.
 Read the holder names in progress and build.waitingFor in status; do not start
 replacement runs while one is queued. See \`stim guide lifecycle concurrency\`.
 
+After maintenance.idleStopHours (default 6) with no Stim command, native run,
+Metro bundle or HMR request, agent-device command or live view, automatic
+maintenance stops the workspace as stim stop does. Device and app logs do not
+count. After a long pause, run stim ios or android again before driving the
+app; see \`stim guide cleanup\`.
+
 Treat a refusal as an ownership or state mismatch: read its code and remedy.
 Never reach for --force first.
 Stim leaves externally started Metro servers alone. Stop them with their original
@@ -1236,9 +1242,10 @@ 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?, expiresAt?,
-                  host? } per remote.machines entry. state is "approved",
-                  "pending", "not-asked", "revoked", "lapsed", "key-changed", "outdated",
+  deviceHosts     one { machine, state, dnsName?, fingerprint?, deviceId?, requestedAt?,
+                  expiresAt?, host? } per remote.machines entry. state is "approved",
+                  "pending", "not-asked", "revoked", "lapsed", "key-changed",
+                  "key-unconfirmed", "outdated",
                   "not-on-tailnet", "tailscale-off", "unreachable", "invalid",
                   "credentials-unavailable" or "busy". Setup tickets stay private.
                   Only --fix asks for access or forgets removed names. A
@@ -1254,7 +1261,12 @@ leased until <time>" for each one.`,
                   expires, absent for a Stim Desktop ticket; "lapsed" is a
                   pending request whose expiry passed. --fix asks again.
                   "key-changed" means the worker did not prove the
-                  stim-server key pinned at approval. "outdated" means its
+                  stim-server key pinned at approval. "key-unconfirmed" is a
+                  local: machine that approved this one but whose key no
+                  person confirmed, so nothing pinned it; fingerprint is the
+                  key's fingerprint to compare with the one stim-server setup
+                  printed there, and only stim doctor --fix in a terminal asks.
+                  A local: entry has no dnsName. "outdated" means its
                   stim-server speaks protocol 1; the finding names the
                   stim-server service update command to run there.
   toolchain       { entries, projectNode } on macOS, else null. entries is one { name, value,
@@ -1267,11 +1279,12 @@ leased until <time>" for each one.`,
                   pins Node (bin, version and match are null when no install
                   fits the pin; match is "exact", or "major" for the newest
                   install of the pinned major not older than the pin), else null
-  remoteMachines  one { machine, state, diagnosis?, dnsName?, deviceId?, requestedAt?,
-                  expiresAt?, offloadable?, reasons?, problems?, capacity?, host? } per
+  remoteMachines  one { machine, state, diagnosis?, dnsName?, fingerprint?, deviceId?,
+                  requestedAt?, expiresAt?, offloadable?, reasons?, problems?, capacity?, host? } per
                   remote.machines entry, for its build approval; state is "approved", "pending", "not-asked",
                   "revoked" (revoked or denied), "lapsed" (the request lapsed
-                  before approval), "key-changed", "outdated",
+                  before approval), "key-changed", "key-unconfirmed" (as in
+                  deviceHosts), "outdated",
                   "not-on-tailnet", "tailscale-off", "unreachable" or
                   "invalid". diagnosis is { layer, code, title, message, remedy }
                   for the first layer that stopped this machine, present for
@@ -1286,6 +1299,11 @@ leased until <time>" for each one.`,
                   nothing behind the route), server-not-ready (503: running but
                   not serving; its message gives the cause the server reports),
                   server-no-answer (silent route while tailscale ping reaches the Mac), server-outdated and connect-failed (none of the above).
+                  A local: machine never reads Tailscale and reports
+                  lan-not-listening (nothing accepts connections on its
+                  stim-server port), lan-no-answer (no reply: the network, or
+                  the macOS firewall on that machine), server-not-ready or
+                  connect-failed.
                   Tailscale's own "offline" flag lags a reachable peer, so an
                   answer from the machine outranks it. host has the same shape and presence rule as in
                   deviceHosts, as do expiresAt (a pending request's lapse
@@ -1834,8 +1852,8 @@ RULES
   reason is null for an entry --delete acts on, and otherwise a stable code
   to branch on; detail is the text line, for the user. Never parse detail.
   A linked worktree's detail is never null.
-    workspaceBuildOutputs   unresolved | in-use | last-use-unknown |
-                            recently-used
+    workspaceBuildOutputs   unresolved | locked | lock-unknown | in-use |
+                            last-use-unknown | recently-used
     workspaceLogs           unresolved | in-use | collector
     recordings              unresolved | retained | recently-recorded
     memory                  in-use | busy | unknown | build-running |
@@ -2041,7 +2059,7 @@ RULES
   Each booted simulator and detected emulator in environments (and in
   slots) carries activity; a shut-down or physical device has none:
 
-  activity  { state, driver?, lastActivityAt?, recent?, basis }
+  activity  { state, driver?, lastActivityAt?, recent?, basis, unknown? }
 
   state            "driven"   a live claim or driver holds the device now
                    "active"   no driver, but activity in the last 10 minutes
@@ -2064,6 +2082,8 @@ RULES
                    workspace-use, supervisor-start, page-log or viewer, each
                    rounded down to the minute. viewer is now while a
                    stim-server client streams the device's frames
+  unknown          for "driven" only: the checks that could not be read, in
+                   basis's vocabulary; absent when every check was read
   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
@@ -2445,8 +2465,8 @@ RULES
   minutes. It caches them in $STIM_HOME/agent-sessions.json, which one-shot
   status reads and ignores once it is 2 minutes old. Both sources are other
   tools' internal files; a missing or changed one only drops its sessions.
-  \`start\`, \`ios\`, \`android\`, \`web\`, \`reload\` and \`worktree warm\`
-  also record the CLAUDE_CODE_SESSION_ID or CODEX_THREAD_ID of the shell
+  \`start\`, \`ios\`, \`android\`, \`web\`, \`reload\`, \`logs\` and
+  \`worktree warm\` also record the CLAUDE_CODE_SESSION_ID or CODEX_THREAD_ID of the shell
   that ran them, so that session is listed for 30 minutes after the command
   even when status cannot see it, and for as long as it runs.
 
@@ -2480,7 +2500,35 @@ RULES
 
   capacity.committedMb sums memoryMb; in a \`status --watch --json\` line each
   figure, including an environment's memoryMb, is held on its own (see
-  \`guide lifecycle\`), so the sums can differ from what they sum. The memory budget plans before a boot
+  \`guide lifecycle\`), so the sums can differ from what they sum.
+
+  capacity.load is always present. capacity.builds is present only while
+  concurrency.maxBuilds is set, and capacity.devices only while
+  concurrency.maxDevices is set (see \`guide lifecycle concurrency\`):
+
+  load     { cpus, loadPerCore, busyAt, limit, state }. loadPerCore is the
+           5-minute load average divided by cpus, to one decimal. busyAt is
+           server.maxLoadPerCore (\`guide settings\`). state is free under
+           busyAt, busy at or over it, where automatic placement prefers
+           another machine, or holding at or over limit. limit is null
+           because no setting sets it yet, so state is never holding.
+
+  builds   { max, inUse, holders: [{ slot, workspace, client, since,
+           unresolved? }] }. inUse counts the slots below max that a new
+           build cannot take. workspace is the root of the local build in
+           the slot; client is the device id of the client whose offloaded
+           build this machine runs in it. An unresolved slot has a claim
+           whose holder Stim cannot identify; both are null, and the slot
+           stays in use until that claim is removed.
+  devices  { max, inUse, unknown?, holders: [{ platform, label, workspace,
+           slot, booting? }] }, the owned devices the cap counts: booted or
+           booting stim simulators, owned emulators adb lists, and boots in
+           progress. label is the label of the workspace that records the
+           device, with its device slot; for a device no workspace records,
+           label is its name and workspace and slot are null. inUse is null
+           and unknown says why when the devices could not be listed.
+
+  The memory budget plans before a boot
   and always uses the estimate. What is using CPU and memory now is the
   top-level machine section:
 
@@ -2779,19 +2827,19 @@ comes from \`start --remote\`, eas/proxy in \`ios.remote\`, or \`android.remote\
 
 HOSTED IOS METRO
   ios --remote <machine> keeps Metro local and needs no start --remote.
-  The supervisor watches private gateway requests in workspace state, binds
-  only this machine's Tailscale address and accepts only the pinned hosting peer
-  with a per-session secret. The host's bridge is loopback-only. For an Expo
-  dev client it listens on this machine's Metro port, which the dev server
+  The supervisor watches hosted Metro requests in workspace state and keeps a
+  few authenticated connections open to the host for each session. The host
+  pairs one with each connection the device makes to its loopback-only bridge,
+  and the supervisor forwards it to this Metro, so the host never connects back
+  to this machine and a shared or ACL-restricted host works. For an Expo
+  dev client the bridge listens on this machine's Metro port, which the dev server
   writes into the manifest. ios --remote starts Metro on a port free on both
   Macs; a running Metro or a pin on a port the host uses refuses the run before
-  the build. Port and secret
-  stay in 0600 workspace state and never appear in status, JSON or logs.
-  metro.tunnel and metro.publicUrl are ignored. Supervisor restart recreates
-  the recorded gateway; stop or a stopped hosted session closes it. A recorded
+  the build. metro.tunnel and metro.publicUrl are ignored. Supervisor restart
+  reopens the recorded links; stop or a stopped hosted session closes them. A recorded
   hosted session prevents Metro idle stop. Release runs skip the bridge.
-  Hosted Debug runs require the supervisor's private gateway support before
-  reservation. --no-metro-check refuses; restart a missing or older supervisor
+  Hosted Debug runs require a supervisor and a stim-server that support these
+  links before reservation. --no-metro-check refuses; restart a missing or older supervisor
   with stim stop; stim start.
   Native iOS and Android logs are pulled from the host by stim logs, including --errors;
   JavaScript logs still arrive through Metro. Stop pulls native logs before
@@ -2853,8 +2901,8 @@ BUNDLE WARMUP
   device logs may prove a request, but bundle completion may stay unverified.
 
 HOSTED ANDROID
-  android --remote <machine> keeps Metro here through the private tailnet
-  gateway. The host reverses the client Metro port into its loopback bridge
+  android --remote <machine> keeps Metro here through the same client-opened
+  links as hosted iOS. The host reverses the client Metro port into its loopback bridge
   on the exact owned emulator. Each run and reload restores that reverse;
   no adb command for the host serial runs here. metro.tunnel and metro.publicUrl
   are ignored. See guide lifecycle hosted-android.
@@ -2962,8 +3010,8 @@ WHAT THE SUPERVISOR IS
   (default 60; 0 never stops) with no bundle request, no client log record
   (in-app console logs; for Expo or metro.command, any stdout line of the
   dev server) and no Stim
-  command in the workspace (start, ios, android, reload, worktree warm). It
-  checks once a minute. It keeps running while a bundle response is in
+  command in the workspace (start, ios, android, reload, logs, worktree
+  warm). It checks once a minute. It keeps running while a bundle response is in
   flight, while a build in the workspace is in progress, while a stim ios,
   android or stop run holds the workspace's native-run lock, while the
   workspace holds an unexpired device lease (\`stim device lock\` or a
@@ -2996,8 +3044,9 @@ WHAT THE SUPERVISOR IS
   own stops show only in the log).
     requested      a Stim command stopped it and says which: stim stop,
                    stim worktree remove, stim gc --delete, stim start
-                   --reset-cache, or budget reclaim (with the workspace whose
-                   ios, android or start run reclaimed it)
+                   --reset-cache, budget reclaim (with the workspace whose
+                   ios, android or start run reclaimed it), or automatic
+                   maintenance with its idle reason (guide cleanup, IDLE STOP)
     signal         a SIGTERM or SIGINT with no Stim stop request recorded,
                    so it likely came from outside Stim (level warn)
     server-exited  the dev server exited on its own (level error). Expo CLI
@@ -3487,7 +3536,15 @@ msg and
   failure         failed or cancelled runs: { code, message, remedy, phase }
   device          { name, runtime? } of the simulator, emulator or device;
                   never its serial or UDID
+  loadPerCore     this machine's 5-minute load average per CPU when the run
+                  started, to one decimal
+  boot            { startedAt, loadPerCore } of the run's first owned
+                  simulator or emulator boot: epoch milliseconds when it
+                  started, once any concurrency.maxDevices wait was over,
+                  and the load per core then. Absent when the run booted
+                  nothing.
   stimVersion     the stim that ran the build
+Records written before these fields existed lack loadPerCore and boot.
 A run that stopped before it had an app to build (a refused flag, a missing
 project) writes no record. Writing the record never changes the run's result.
 
@@ -3591,7 +3648,9 @@ WHAT WRITES WHAT
                        and, on Expo, one per dev-client manifest
                        request (manifest_request_started, _finished,
                        _failed: debug level, with platform and requestId;
-                       launch verification reads them as progress)
+                       launch verification reads them as progress), and
+                       an hmr_update debug record, at most once a minute,
+                       when Metro pushes a Fast Refresh change to the app
   client.ndjson        in-app console logs and redboxes -- BARE PROJECTS ONLY.
                        In expo-child and command-child mode everything the
                        dev server prints lands in metro.ndjson with raw: true,
@@ -5661,7 +5720,7 @@ STIM_SUPERVISOR_EXITED, ...) before any build work. Release builds and
 \`--no-metro-check\` neither check nor start the dev server; hosted Debug iOS
 refuses --no-metro-check with STIM_BAD_ARG. \`--remote\`
 with eas or proxy starts it the way \`stim start --remote\` does. A named
-hosting Mac keeps Metro local through a private bridge; see hosted-ios. Step 2 remains useful to warm
+hosting Mac keeps Metro local through links this machine opens; see hosted-ios. Step 2 remains useful to warm
 Metro while other work happens.
 
 Each time Stim boots an owned local simulator or emulator, it mutes it: iOS
@@ -5841,7 +5900,8 @@ 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. In a watch line, a usage
   figure repeats its value in the previous line until it moves by a step: an owner's cpuPercent 5 points, an
-  owner's or environment's memoryMb and capacity.committedMb 16 MB. An owner's row
+  owner's or environment's memoryMb and capacity.committedMb 16 MB, and
+  capacity.load as a whole until its loadPerCore moves 1 per core or its state changes. An owner's row
   changes as a whole, so its residentMb and processes update with it. A change
   in only a bookkeeping timestamp prints no line: each pullRequest.checkedAt,
   maintenance.lastChecks, maintenance.lastPass.startedAt and durationMs, and
@@ -6087,8 +6147,8 @@ soon as it exists, then delivers one App.apk. The emulator boots headless;
 androidEmulatorApp is ignored with a note.
 
 React Native Debug requires the local Metro supervisor. metro.publicUrl and metro.tunnel
-are ignored with a note. A private tailnet gateway reaches the host loopback
-bridge; the host reverses the client's Metro port into that bridge on its exact
+are ignored with a note. Connections this machine opens to the host carry each
+device connection from the host loopback bridge to local Metro; the host reverses the client's Metro port into that bridge on its exact
 ledger-owned serial and sets debug_http_host to localhost:<clientMetroPort>.
 Each run and stim reload android restores the reverse, including after a host
 adb server restart. Reload broadcasts through the local Metro and never runs
@@ -6111,7 +6171,7 @@ session probe states; a conflicting local emulator remains visible with a
 warning. A recorded placement keeps the workspace in use and blocks idle stop.
 
 stop and worktree remove wait for device-host.stop, park the host's eligible owned
-emulator within pool.androidParkedMax (delete otherwise), close the gateway and clear placement. stop --json reports
+emulator within pool.androidParkedMax (delete otherwise), close the Metro links and clear placement. stop --json reports
 outcomes.device["android:host:<slot>"]. Forbidden or unknown-session also clears
 placement; an unreachable host keeps it and fails cleanup. A clean host restart
 parks eligible devices; a later reserve by the same client adopts a compatible
@@ -6317,9 +6377,10 @@ sessions.
 
 
 Stim builds or fetches before reserving, records the session immediately, then
-uploads the app on every run. React Native and Expo Debug keep Metro here; the supervisor owns a
-private gateway bound to this machine's Tailscale address, pinned to the host peer
-and protected by a per-session secret. The host exposes only a loopback bridge.
+uploads the app on every run. React Native and Expo Debug keep Metro here; the supervisor keeps
+authenticated connections open to the host, and the host pairs one with each
+connection the simulator makes to its loopback-only bridge. The host never
+connects back to this machine.
 For an Expo dev client the bridge listens on this machine's Metro port, because
 the dev server writes that port into the manifest's bundle URL. When this run
 starts Metro, it asks the host and picks a port free on both Macs, moving the
@@ -6327,8 +6388,8 @@ recorded port if the host uses it. A running Metro or a metro.port pin on a port
 the host uses refuses before the build: run stim stop, then stim ios --remote
 <machine> without stim start, or pin a port free on both Macs.
 No start --remote is needed; metro.tunnel and metro.publicUrl are ignored.
-Debug requires a running supervisor with private gateway support before reserving
-a simulator. --no-metro-check refuses with STIM_BAD_ARG for hosted Debug runs.
+Debug requires a running supervisor and a host stim-server that support these
+links before reserving a simulator. --no-metro-check refuses with STIM_BAD_ARG for hosted Debug runs.
 If its supervisor is missing or older, run stim stop; stim start, then retry.
 Non-Debug runs skip Metro. Launch is unverified until this workspace's Metro
 provides bundle evidence, or the host proves a live release process. Native Xcode
@@ -6341,14 +6402,14 @@ hosting Mac, refuses for that slot: run stim stop first.
 Status adds ios.host { machine, session, selected, device: { name, runtime },
 agent, state } per slot. A shutdown local simulator is replaced in status; a
 booted or unknown local simulator stays visible alongside ios.host with a warning.
-The default slot appears only in ios, never in slots[]. No host UDID or gateway secret enters local device state or
+The default slot appears only in ios, never in slots[]. No host UDID enters local device state or
 status. Ready is normal; stopped has a rerun hint; unknown or unreachable is
 unverified. A clean host server restart stops its sessions and retains eligible
 parked devices. A running session left by a crash stays unknown until explicit
 stop; the restarted server never re-attaches to a booted device.
 
 stop and worktree remove wait for the host to stop, park its eligible owned
-simulator within pool.iosParkedMax (delete otherwise), close the gateway and clear placement. stop --json
+simulator within pool.iosParkedMax (delete otherwise), close the Metro links and clear placement. stop --json
 reports each hosted slot under outcomes.device["ios:host:<slot>"], retaining
 local device outcomes and successful siblings when another slot fails. Revoked or
 missing sessions clear placement too. An unreachable host retains placement
@@ -7866,7 +7927,7 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
 
   Warm registers the app it prepares, so \`stim status\` lists the workspace
   with phase "warming" while it runs and "ready" once it succeeds, until the
-  first start, ios, android, web or reload there or for 2 hours
+  first start, ios, android, web, reload or logs there or for 2 hours
   (\`guide facts status\`). In a monorepo worktree root, that app is the one
   the source checkout has registered.
 
@@ -8651,6 +8712,52 @@ supervisor's idle rules and records (guide lifecycle budget). While the level is
 check also names abnormally large processes (guide lifecycle simslim) in
 status's maintenance block and the maintenance log.
 
+IDLE STOP: the idle check, and gc --delete unless maintenance.mode is off (its
+dry run lists them in the maintenance plan), stop a workspace whose dev server
+runs or whose owned simulator or emulator is booted once it has had no real
+activity for maintenance.idleStopHours (default 6; 0 never; machine or project
+layers; STIM_MAINTENANCE_IDLE_STOP_HOURS overrides; fractions work). Six hours
+outlasts a lunch break, a meeting or an agent's pause between tasks, and still
+frees the memory overnight. Real activity is the newest of: a Stim command in
+the workspace (start, ios, android, macos, web, reload, logs, worktree warm),
+the end of its last native build, the start, progress or end of a Metro
+bundle or manifest request, or an HMR update, in metro.ndjson, an agent-device command in the workspace's
+agent-device sessions, and an open stim-server live view of its device.
+Device and system log lines, in-app console logs, dev server output,
+collector writes and maintenance's own records never count, and an app that
+only stays connected does not either. The stop is stim stop's: the dev
+server stops, the owned devices shut down through centralized teardown
+(never deleted), and the port is released; device leases stay. A build, a
+held native-run or metro-start lock, a build lock or slot, a running macOS
+app, a hosted or remote session, an unexpired device lease, a managed tunnel
+or remote lock, a running owned Chrome, a device driver other than
+agent-device, a live agent-device claim with no session activity to judge,
+device activity, an emulator list or an emulator's AVD name that cannot be read keeps
+the workspace;
+the check decides again under the native-run and metro-start locks. Each stop
+is a maintenance_action line naming the idle time (gc --delete records itself
+as the requester), each workspace kept past the window a maintenance_skip line
+with the reason. The port is released, so status shows the workspace idle as
+after stim stop, and the supervisor_stopped line in metro.ndjson names
+automatic maintenance and the idle time as the requester. The next start, ios or android starts it
+again. An owned emulator the activity check missed keeps the workspace while
+adb lists it, and so does any emulator adb lists without an AVD name, such as
+a stale offline entry that adb kill-server clears. A dev server that may still run after its supervisor
+exited is kept until stim stop ends it. So is a dev server whose requests Stim
+does not record: an Expo project before SDK 54, which cannot load Stim's Metro config
+adapter, or a dev server an older Stim started, until stim stop and stim start
+restart it. Unlike the other actions, it can stop the workspace whose dev server
+supervisor or status --watch timer started the pass; a pass a command starts,
+gc --delete included, never stops the command's own workspace.
+A dev server run through metro.command is kept: Stim sees none of its
+bundle or HMR requests. A Metro log that cannot be read, or that rotated
+within the window, and agent-device sessions, a state.json or a stim-server
+viewer record that cannot be read or verified keep the workspace too. A STIM_HOME-scoped home never
+idle-stops, because its devices are machine-wide. maintenance.keep does not keep a workspace from idle
+stop, which deletes nothing; set maintenance.idleStopHours 0 at workspace
+scope instead.
+  stim settings set maintenance.idleStopHours 1 --scope machine
+
 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
@@ -8695,7 +8802,8 @@ live build lock, or in a Metro store with a running or unverifiable dev
 server. Anything the pass cannot verify is kept. A device is deleted only when
 its workspace is idle: no dev server, native run, build, lease, managed lock,
 driven or busy device, and no recorded use within the window. Below disk
-pressure level 3 a pass never stops a dev server or watchman; removing a
+pressure level 3 a pass stops a dev server only by IDLE STOP above and never
+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.
@@ -8751,8 +8859,8 @@ DISK PRESSURE LEVELS
        gradle-versions, run again after step 5 so a daemon that did not exit
        still keeps them
   A directory is cleared only when it is a real directory inside its
-  worktree, git tracks nothing in it, its worktree is not in use, holds no
-  lock or build and is not pinned, and, for the node_modules and ios/Pods of
+  worktree, git tracks nothing in it, its worktree is not in use, is not
+  locked with git worktree lock, holds no build lock and is not pinned, and, for the node_modules and ios/Pods of
   level 3, nothing under it, nor the worktree's git index, HEAD or Stim
   state, changed within the short window. A build directory of level 2 also
   stays in a worktree where no Stim workspace has recorded any state; a build
@@ -9729,7 +9837,12 @@ WORKSPACE BUILD OUTPUTS
   detected cache, "Workspace build outputs", with a per-workspace size, last
   use and verdict. Plain \`gc --delete\` lightens every workspace, before
   anything else, by clearing them, and prints the bytes freed per workspace.
-  A running dev server, a booted or hosted simulator or emulator and a managed
+  A workspace whose worktree is locked with git worktree lock is never
+  lightened: not its outputs, not its project's build directories, at any
+  disk pressure level, including gc --older-than and the budget, and gc and
+  the maintenance log name the lock. The outputs also stay when git lists
+  nothing for a project inside a git checkout (code lock-unknown). A
+  running dev server, a booted or hosted simulator or emulator and a managed
   tunnel no longer keep them. They stay while the workspace is building (its
   native-run.lock is held, a live or unresolvable build lock or slot names
   it, or its build claim is live), while its macOS app or build runs or cannot
@@ -9749,8 +9862,8 @@ WORKSPACE BUILD OUTPUTS
   1 keeps its own rules. A running, building, unverified or hosted macOS app
   keeps its workspace untouched.
     stim gc --delete --cache workspaces --older-than 7
-  Last use is the newest of the lastUsedAt that start, ios, android, reload
-  and worktree warm record in state.json, lastBuild.startedAt,
+  Last use is the newest of the lastUsedAt that start, ios, android, reload,
+  logs and worktree warm record in state.json, lastBuild.startedAt,
   supervisor.startedAt and the mtimes under logs/, so a dev server that keeps
   logging keeps its workspace in use.
   A workspace with none of those was last used when its workspace.json was
@@ -9768,10 +9881,11 @@ WORKTREE DEPENDENCIES
   Plain \`gc --delete\` also lightens linked worktrees: it deletes the
   node_modules and ios/Pods at the root or a project root of a linked
   worktree that has a Stim workspace, never the source checkout. A worktree
-  keeps them while it is in use (its dev server runs, a native run or build
-  holds it), while it was used in the last 15 minutes (a git index, HEAD or
-  reflog write, a Stim state or log write, or a write at the top of the
-  directory), while git tracks a file in them, while a stim-server service
+  locked with git worktree lock keeps them always, so a rollback checkout
+  stays runnable. Otherwise a worktree keeps them while it is in use (its
+  dev server runs, a native run or build holds it), while it was used in
+  the last 15 minutes (a git index, HEAD or reflog write, a Stim state or
+  log write, or a write at the top of the directory), while git tracks a file in them, while a stim-server service
   or the stim on PATH runs from it, while a live process has its command
   line or working directory in it, and when the running processes cannot be
   listed (always on Windows). It also keeps them when \`stim worktree warm\`
@@ -10485,6 +10599,8 @@ 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.
+maintenance.idleStopHours takes machine or project layers, so one workspace can
+stop sooner, later or never.
 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 ?? "project setting"}  ${setting.default === void 0 ? "unset" : `default ${setting.default}`}
@@ -10653,6 +10769,38 @@ machine a \`priority\` in its JSON:
 A host reports its own load limit in its device offer; a stim-server older than
 that does not, and this machine's \`server.maxLoadPerCore\` stands in for it.
 
+REMOTE MACHINES ON THE LOCAL NETWORK
+A machine on the same local network, without Tailscale, is named
+\`local:<host>\`: its private IPv4 address or host name, with an optional
+stim-server port (default 7787). On the worker, a person first chooses where
+stim-server listens with the machine setting \`server.lanAddresses\`, a list of
+network interface names or private IPv4 addresses. It defaults to [], which
+listens on no local network address; wildcard, loopback, public and IPv6
+addresses are refused, and the running server applies a change within seconds.
+An interface name follows the interface onto whatever private network it
+joins, so name the address on a machine that moves between networks, and an
+interface only on a worker that stays put. Then the person runs the setup
+command \`stim doctor --fix\` prints here:
+
+  stim settings set server.lanAddresses '["10.0.0.92"]'     # on the worker
+  stim settings set remote.machines '["local:10.0.0.92"]'   # on this machine
+  stim doctor --fix
+
+Every connection runs Stim's Noise handshake, so plain WebSocket carries it
+without TLS, and the address never identifies anyone. Nothing on a local network
+vouches for the worker's key, so \`stim-server setup\` prints the worker's server
+key fingerprint and \`stim doctor --fix\`, run by a person in a terminal, shows
+the fingerprint the worker answered with and pins the key only after they
+confirm it matches. Until then the entry reports key-unconfirmed and is not
+used. Agents never answer that question. The printed setup command carries the
+ticket, which is a credential: whoever spends it first, after setup stores it,
+gets the approval, and on a local network that takes only the ticket and a
+route to the worker, not tailnet membership. Agents show it only to the user.
+Offloaded builds and hosted Debug and
+Release runs work there; agent control of hosted apps needs a tailnet machine.
+\`stim-server pair\` puts \`ws://<address>:<port>\` in the phone pairing code
+when Tailscale is not running and \`server.lanAddresses\` is set.
+
 Automatic membership is separate from approval. In Desktop Settings > Remote
 Machines, use Builds enabled and Simulators enabled for this machine or a
 configured remote. The equivalent machine settings list the excluded members;
@@ -10893,7 +11041,8 @@ the ones it offloaded.
 \`server.maxLoadPerCore\` (default 2) is also the busy threshold for
 automatic iOS, Android and macOS placement. It is the load per core at which a
 machine counts as saturated: each machine applies its own value, and a remote
-machine past it is skipped like a full one.
+machine past it is skipped like a full one. \`stim status\` shows this machine's
+load per core against it, as \`capacity.load\` in JSON.
 
 Device, Release and
 \`--remote eas|proxy\` builds, Android builds with the Apple Clang CAS compiler cache,
@@ -11090,7 +11239,7 @@ scope, so it needs no --scope. Run it from the workspace:
 
 \`stim status --json\` then reports hidden: true on that environment, and
 clients that read it list the workspace under Hidden. The next start, ios,
-android, web, macos, reload or worktree warm in the workspace clears it, so
+android, web, macos, reload, logs or worktree warm in the workspace clears it, so
 a workspace in use is never hidden. \`worktree remove\` drops it with the
 workspace.
 
@@ -11625,7 +11774,10 @@ owned app, including copies opened through LaunchServices (open, agent-device
 open). stim macos, stim stop, stim worktree remove and stim gc --delete stop all
 of them: SIGTERM, up to 5 s, then SIGKILL, and success only once each has
 exited. When an app cannot be verified or does not exit, stop reports
-STIM_MACOS_OWNER_UNVERIFIED or a failure, and removal keeps the workspace.
+STIM_MACOS_OWNER_UNVERIFIED or a failure, and removal keeps the workspace. For
+a hosted session the same rule covers every app bundle the session received, so
+stop and a replacement launch also end a copy that LaunchServices started from
+an earlier attempt.
 Local stim macos starts the app in the background without activating it or
 changing focus: it sets STIM_BACKGROUND_LAUNCH=1 in the app's environment, which
 Stim Desktop honors, including for reopen events from open -g. An app that
@@ -12015,6 +12167,12 @@ method the relay does not forward, is refused with an agent-device UNAUTHORIZED
 error whose details.reason is STIM_AGENT_REQUEST_REFUSED and whose message names
 the refused command or method; do not retry it.
 
+longpress, swipe, back and the other gestures are not in that list; the
+longpress and swipe that stim guide lifecycle lists belong to hosted Android and
+iOS sessions. click <ref> --button secondary reaches agent-device, but its native
+macOS backend, which the lease requires, answers UNSUPPORTED_OPERATION, so a
+hosted macOS app has no right click or context menu yet.
+
 Agents that built, launched and drove test copies on another Mac with an SSH
 script such as mini-desktop.sh use these instead:
 
@@ -12023,7 +12181,8 @@ script such as mini-desktop.sh use these instead:
   launch                     the same command; the host launches it under the
                              session's own home
   shot <out.png>             agent-device screenshot --remote-config <path>
-  click, rclick, key, type   agent-device click, press or type --remote-config <path>
+  click, key, type           agent-device click, press or type --remote-config <path>
+  rclick                     unavailable: secondary click is not supported
   quit                       stim stop (verified stop; the host frees the slot
                              and removes the app's defaults)
   clean                      stim worktree remove
@@ -12034,6 +12193,15 @@ The host's own owned devices count toward concurrency.maxDevices.
 
 The agent-device rows work once the host's agent field names agent-device.
 
+On macOS 27, agent-device screenshot of a hosted app can return an image of the
+window-sharing indicator (66x20 points, 132x40 pixels) instead of the app
+window. macOS adds that small window to the app while something captures the
+app, and agent-device picks it as the front window (callstack/agent-device#3961).
+snapshot -i lists it as an axdialog named "Window" with a
+WindowSharingSessionButton before the real window. Read the UI with snapshot
+until agent-device selects the app's main window. Commands that use the front
+window's frame, such as scroll, may also target the indicator.
+
 DESKTOP DOGFOOD
 
 This repository's apps/desktop/.stim.json selects the full StimDesktop app,

package/dist/{hosted-android-BMKzUNnY.mjs → hosted-android-DI_vvv7U.mjs}

@@ -1,7 +1,7 @@
 import { c as throwIfCancelled } from "./exec-aULwtNly.mjs";
-import { c as call, l as connectHost } from "./hosted-client-D7Pk_Oo1.mjs";
-import { i as requestHostedMetro } from "./metro-gateway-BnHdqMO_.mjs";
-import { a as stopHostedNative, i as prepareHostedNative, r as placeHostedNative } from "./hosted-native-CdgaiuyP.mjs";
+import { c as call, l as connectHost } from "./hosted-client-CgoxdU9j.mjs";
+import { i as requestHostedMetro } from "./metro-request-BtF7ox53.mjs";
+import { a as stopHostedNative, i as prepareHostedNative, r as placeHostedNative } from "./hosted-native-DvZENAL-.mjs";
 //#region src/device-host/hosted-android.ts
 async function prepareHostedAndroid(machine, selectors, recorded, mode) {
 	return await prepareHostedNative(machine, selectors, recorded, "android", false, mode);
@@ -19,12 +19,11 @@ async function stopHostedAndroid(root, slot, signal) {
 async function reopenHostedAndroidMetro(root, placement, clientMetroPort, signal) {
 	const host = await connectHost(placement.machine, void 0, true, signal);
 	try {
-		const gateway = await requestHostedMetro(root, placement.session, host.credential, signal);
+		await requestHostedMetro(root, placement.session, host.credential, signal);
 		throwIfCancelled(signal, "reload");
 		await call(host, "device-host.metro.open", {
 			session: placement.session,
-			clientMetroPort,
-			...gateway
+			clientMetroPort
 		});
 	} finally {
 		host.connection.close();