stim 1.25.0 → 1.26.0

package/dist/{guide-DR0K0xW9.mjs → guide-D7K0X6KG.mjs}

@@ -1,8 +1,8 @@
-import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-B5tCoq9N.mjs";
-import { i as findProjectRoot$1 } from "./project-BiC68mIp.mjs";
-import { h as RECENT_LAUNCH_MS } from "./eas-session-ledger-BMCA1gdO.mjs";
-import { o as guideStatus, t as WATCHMAN_NESTED_WORKTREES } from "./doctor-watchman-BovI1y3-.mjs";
-import "./status-watch-Bc2J4TZn.mjs";
+import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-CosW5X-S.mjs";
+import { i as findProjectRoot$1 } from "./project-BUu6Is4k.mjs";
+import { h as RECENT_LAUNCH_MS } from "./eas-session-ledger-B5vygTiD.mjs";
+import { o as guideStatus, t as WATCHMAN_NESTED_WORKTREES } from "./doctor-watchman-BStK05nt.mjs";
+import "./status-watch-B5wDIH_o.mjs";
 import { SETTINGS, SETTINGS_SCHEMA_URL, TUTORIAL_VERSION } from "@stim-cli/core/state";
 import chalk from "chalk";
 //#region src/guide/agent.ts
@@ -188,6 +188,11 @@ RULES DURING THE LOOP
   you do other work.
 - Run ios or android again after a native input changes. A JavaScript-only
   change does not need one.
+- The build cache counts an installed package by its name and version, so it
+  cannot see a file you edit inside node_modules/. Change a dependency's native
+  code with a patch (patch-package or pnpm patch), which is hashed, or run ios or
+  android with --no-build-cache --remote-build local to compile it here. See
+  guide lifecycle builds.
 - For stale Metro transforms or file-map state, use stim start --reset-cache.
   It restarts only this app's verified owned Metro, preserving devices and other
   apps' caches. See guide lifecycle for reset scope.
@@ -395,7 +400,7 @@ FULL TOPIC LIST
   stim guide errors fallbacks     # swap, cache, and install notes on a release cache hit
   stim guide lifecycle            # the ordered flow, consent rules, and capacity
   stim guide lifecycle verification # reproduce, edit, verify the UI, and retain proof
-  stim guide lifecycle readiness  # add optional app readiness logs; no package required
+  stim guide lifecycle readiness  # add recommended app readiness logs; no package required
   stim guide lifecycle builds     # build optimizations, optional cache warm-up, fingerprints
   stim guide lifecycle concurrency # shared builds, wait timeouts, capacity limits
   stim guide lifecycle budget     # disk and memory budgets, automatic reclaim
@@ -1009,7 +1014,7 @@ leased until <time>" for each one.`,
                                  JavaScript running -- the first screen may
                                  still be rendering\` (\`stable for 3s\` when
                                  no \`Running\` log arrived). Poll the UI
-                                 before you trust a screenshot. Optional
+                                 before you trust a screenshot. Recommended
                                  app-declared readiness adds a separate
                                  stderr readiness phase; it does not change
                                  this field. See
@@ -1256,13 +1261,27 @@ 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, dnsName?, deviceId?, requestedAt?,
+  remoteMachines  one { machine, state, diagnosis?, dnsName?, 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",
                   "not-on-tailnet", "tailscale-off", "unreachable" or
-                  "invalid". host has the same shape and presence rule as in
+                  "invalid". diagnosis is { layer, code, title, message, remedy }
+                  for the first layer that stopped this machine, present for
+                  "tailscale-off", "not-on-tailnet", "outdated" and "unreachable"
+                  (deviceHosts carries it too); the codes are
+                  tailscale-stopped, tailscale-logged-out, tailscale-unavailable
+                  (this machine's Tailscale), peer-not-found, peer-ambiguous,
+                  peer-offline (with last seen), peer-no-answer (the connection
+                  got no reply and tailscale ping fails), route-missing (nothing accepts
+                  connections on the serve port), route-tls, route-http-error
+                  (any HTTP status but 502 and 503), server-not-running (502:
+                  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).
+                  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
                   time) and "lapsed" (--fix asks again). An approved machine also carries offloadable,
                   true when it would take this app's builds now (iOS
@@ -1278,7 +1297,16 @@ leased until <time>" for each one.`,
                   checkout, stim-build, arch, xcode, simulator-sdk, macos-sdk,
                   cocoapods, bundler, runtime, jdk, android-sdk, ndk,
                   build-tools, compile-sdk, disk, busy or platform). problems lists the same
-                  reasons as { code, reason } with that code. capacity
+                  reasons as { code, reason } with that code; an ndk, build-tools,
+                  compile-sdk, jdk, xcode or runtime problem can also carry commands and a
+                  lead, the lines to run on that machine (sdkmanager, the JDK install,
+                  xcode-select, xcodebuild or xcodes) and what they do, or followsFrom, the
+                  code of the problem whose fix also clears it. notes lists what a build there does without stopping:
+                  { code, reason, commands, lead } for an ndk, build-tools or compile-sdk package its
+                  Android SDK lacks and Gradle downloads on the first build (licenses
+                  accepted there, no android.builder.sdkDownload=false in the app), with the sdkmanager
+                  command that installs it ahead of time; each
+                  also a build-machine-<code> finding at level note. capacity
                   is the machine's offer: { running, max, diskFreeBytes,
                   minDiskFreeBytes, cpus?, loadPerCore?, builds?, maxBuilds?,
                   maxLoadPerCore?, memoryUsedBytes?, memoryTotalBytes?, declined? }; an older stim-server omits the
@@ -1289,6 +1317,7 @@ leased until <time>" for each one.`,
                   with an abnormally large footprint and, when it is safe to
                   restart, the command
                   offload-candidate is a note after 3+ successful local cold builds in 7 days average over 3 min, with no remote.machines and an online tailnet Mac; open Stim Desktop Settings > Remote Machines > Add
+                  readiness-markers-missing is a note when no JS or TS source under the app directory contains [stim:readiness]; the scan skips node_modules, native and build output directories and dot-directories, and reports nothing past 5000 source files; see stim guide lifecycle readiness
 
 ON FAILURE
   \`start\`, \`ios\`, \`android\` and \`web\` all print the error contract instead,
@@ -2440,6 +2469,8 @@ RULES
     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.
+    What each run cleared, kept or failed is in $STIM_HOME/gc/gc.ndjson,
+    read with \`stim logs --source gc --json\` (\`guide logs\`, GC LOG).
     invalid names invalid settings; invalid cache caps use their defaults,
     while invalid maintenance settings disable passes. claim contains an
     unresolved claim's path and reason, plus removeCommand from the claim
@@ -3168,6 +3199,7 @@ FLAGS
                   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, placement (one or more), or all.
+                   gc alone reads the machine-wide gc log (GC LOG below).
                    An unknown value is REJECTED rather than quietly matching
                    nothing.
   --level <l>      minimum level: debug, info, warn, error, fatal
@@ -3344,6 +3376,27 @@ 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.
 
+GC LOG
+stim logs --source gc reads $STIM_HOME/gc/gc.ndjson from any directory: one
+record per item that a gc run, a maintenance action or the budget gate
+cleared, kept or failed to clear. It cannot be combined with other sources,
+and --source all does not include it. --errors shows the failed items.
+Each record has src: gc, level (info, or error for a failed item), msg and
+  runId    the stim invocation, or the pass id of maintenance.ndjson
+  trigger  manual (stim gc in a terminal), desktop (STIM_DESKTOP_APP is set, so also a gc run through a stim-server Desktop started),
+           maintenance, or budget (the disk, memory or workspace check before
+           start, ios and android)
+  via      maintenance only: the command whose run started the pass
+  options  gc only: delete, worktrees, olderThan, cache, idleMs
+  kind     what the item was (the kind of gc --json results, plus devServer
+           for a dev server the budget gate stops; maintenance also writes
+           buildDirectory and dependencies)
+  status   done, kept or failed
+  label, id, path, bytes, detail
+           name, identifier, absolute path when the item is one, bytes freed,
+           and the reason a kept or failed item was left
+Records of one run share runId. See stim guide cleanup, WHAT WAS CLEARED.
+
 REMOTE REQUEST RECORDS
 A request to another machine that fails is a warn record with src: build in the
 run's build log: remote_connect_failed { host, capability, ms, timeoutMs, msg,
@@ -3403,6 +3456,8 @@ they stay in the local logs. These records carry no tokens.
 
 WHAT WRITES WHAT
   maintenance.ndjson   workspace maintenance actions, failures and explaining skips
+  $STIM_HOME/gc/gc.ndjson  machine-wide, not in a workspace: what gc, maintenance
+                       and the budget gate cleared (stim logs --source gc)
   metro.ndjson         the bundler, in every supervisor mode. Stim's
                        middleware adds one record per bundle request
                        (bundle_response_started, _progress, _finished,
@@ -3436,7 +3491,7 @@ WHAT WRITES WHAT
                        The count does not attribute unknown OS errors to the app.
                        Known JavaScript errors also print individually: Android
                        ReactNativeJS records, and iOS com.facebook.react.log /
-                       javascript records. These can interrupt an optional
+                       javascript records. These can interrupt a recommended
                        readiness wait even without a client or Metro copy.
                        Client and Metro errors still print individually.
                        A native app that loaded its bundle but reported app errors
@@ -3987,7 +4042,12 @@ too old to speak protocol 2, incompatible
 toolchain/runtime/CPU, low disk, busy, sync/build failure, artifact failure,
 or a checkout that changed while it built. Unsupported build kinds also refuse.
 No local xcodebuild, Gradle or SwiftPM compile or alternate machine follows a
-refusal. Prebuild and pod install still run on this machine before a named offload.
+refusal. For stim ios, a toolchain difference on the named machine, such as Xcode,
+the simulator runtime or the CPU, refuses before this machine runs prebuild or pod
+install, even when prebuild would have produced an app the local cache already holds, or the
+machine already holds the exact artifact. A
+missing or different global CocoaPods never refuses a named machine; a pod install
+that fails on it reports "pod install failed" with the command to run there.
 Unlisted or unpaired names refuse at setup before consulting the cache, without
 a build record or failed-run stats. A listed paired name with a cache hit needs
 no build and does not contact the selected machine.
@@ -5442,10 +5502,11 @@ simulators to volume zero through Xcode's devicectl, and Android 15 and later
 emulators to media volume zero. The iOS mute runs after SimSlim has applied its
 profile and once SpringBoard has finished starting, because both a SimSlim
 reboot and SpringBoard's startup reset the volume. A device that is already
-running keeps its volume, except that SimSlim reboots a running simulator whose
-profile changed. Turn sound on for one device with Sound (iOS) or
-Media sound (Android) in its Stim Desktop options; the choice lasts until that
-device next boots. Android 14 and older images have no shell command that can
+running keeps its volume, except that a running simulator SimSlim reboots (a
+first slim, a profile change, or restoring stock services) is muted again once
+SpringBoard is back; an already slim simulator is not touched. Turn sound on
+for one device with Sound (iOS) or Media sound (Android) in its Stim Desktop
+options; the choice lasts until that device next boots. Android 14 and older images have no shell command that can
 set media volume, so startup warns, as it does whenever a mute is not
 confirmed. Host volume, Android alarm and ringtone volumes, hosted devices and
 physical devices are unchanged.
@@ -6320,8 +6381,8 @@ command before any EAS lookup. stim doctor reports it in a project with eas.json
 If another run holds the artifact claim, wait for it to finish and retry.`
 		},
 		readiness: {
-			summary: "implement optional pending/ready app logs, deadlines, errors, and platform isolation",
-			body: () => `OPTIONAL APP READINESS
+			summary: "implement recommended pending/ready app logs, deadlines, errors, and platform isolation",
+			body: () => `RECOMMENDED APP READINESS
 
 No package or SDK is needed. This applies to debug ios/android launches with
 Metro verification enabled, not release builds or --no-metro-check.
@@ -6382,7 +6443,10 @@ Only exact standalone info/debug messages captured from this app's device log
 for this platform and current launch are accepted. Stale, other-platform,
 error-level, and embedded example messages are ignored. Unlabelled shared
 Metro output cannot identify a platform. If pending is not captured in time,
-including when device logs are unavailable, the default check applies.
+including when device logs are unavailable, the default check applies. On a
+device hosted on another Mac (--remote <machine>), the device log is the copy
+pulled from that Mac during the launch check, and each window waits up to 10
+seconds for the copy to cover it.
 
 The app declares readiness; Stim does not inspect a rendered frame. This does
 not change launched JSON semantics or the need to inspect the expected UI and
@@ -6674,7 +6738,8 @@ result as proof instead of requiring an unrelated screenshot.`
 
   \`gc --older-than <days>\` reports and deletes, or with \`--cache parked\`
   erases, only the devices parked at least that long; one parked at an unknown
-  time stays.
+  time stays. Automatic maintenance's daily age sweep deletes the devices
+  parked for maintenance.olderThanDays (7; 0 never) the same way.
 
   If simulator listing or deletion fails, \`gc --delete\` reports the failure
   and keeps that entry. It never turns an unverified absence into a dropped
@@ -6846,11 +6911,27 @@ IOS SCHEME SELECTION
 
 AN ARTIFACT THE DEVICE ALREADY HOLDS IS NOT INSTALLED AGAIN
   Both platforms store the artifact verbatim, so its hash is its identity.
-  Before installing, Stim hashes the artifact it is about to install and the
-  one the device already has -- \`pm path\` then \`sha256sum\` on Android, the
-  \`simctl get_app_container\` bundle on iOS. Byte-identical means the install
-  is skipped. The phase still reports the cost of proving that identity, but
-  avoids the ~43s a 400MB APK can cost to copy and install over USB.
+  Before installing, Stim compares the artifact it is about to install with
+  the one the device already has. On iOS it hashes both bundles: the
+  \`simctl get_app_container\` bundle and the one about to be installed.
+  Byte-identical means the install is skipped. The phase still reports the
+  cost of proving that identity, but avoids the ~43s a 400MB APK can cost to
+  copy and install over USB.
+
+  On Android the proof is one \`adb shell\` call that returns the installed
+  APK's path, size, and the SHA-256 of its tail: the v2 or v3 signing block,
+  the central directory, and the end record. That tail carries the signed
+  digests of every other byte, and Android verified them when it installed
+  the APK. Stim verifies the local APK against the same digests once, with
+  \`apksigner verify\`, and keeps the size and tail digest in
+  \`apk-signed-tail.json\` beside the APK in its build cache entry (stored with
+  the build; an older entry gets it on first use). The same size and tail
+  digest mean the same file, on an owned emulator, an adopted one, a
+  \`--device\` phone and a plain rerun. A different size or tail digest
+  installs without hashing the whole APK. An APK outside a build cache entry,
+  one without a v2 or v3 signing block, an apksigner that is missing or fails,
+  and a device whose \`tail\` or \`stat\` does not answer as expected fall back
+  to \`pm path\` then \`sha256sum\` of the whole installed APK.
 
     install     unchanged (emulator-5584 already has this build) (0.4s)
 
@@ -6863,8 +6944,9 @@ AN ARTIFACT THE DEVICE ALREADY HOLDS IS NOT INSTALLED AGAIN
     install     unchanged (stim-app already has this build) (0.4s)
     install     dev client prepared (0.9s)
 
-  The skip needs PROOF. A package that is not installed, a split install, an
-  image without \`sha256sum\`, and any adb or simctl failure all read as
+  The skip needs PROOF. A package that is not installed, a split install, a
+  device that answers neither probe (no \`tail\` and no \`sha256sum\`), and any
+  adb or simctl failure all read as
   "cannot determine", and the run installs exactly as it always did. A release
   run swaps this workspace's JS into a COPY of the artifact, which is a
   different artifact and is therefore always installed.
@@ -7065,6 +7147,67 @@ THE BUILD CACHE HAS THREE LEVELS
   trims, and clears local caches only: the provider contract has no delete
   operation, so no local command can remove data a team or CI system shares.
 
+  WHAT THE KEY COUNTS. Stim runs @expo/fingerprint with its default
+  \`balanced\` preset, the one the project's own Expo uses. An installed
+  dependency, and a config plugin loaded from node_modules, counts by its name
+  and version, not by its files. A package whose real path is outside
+  node_modules -- a workspace package, a link: dependency, a local Expo module
+  -- counts by its files, and so do patches/, the app's committed ios/ or
+  android/, the evaluated app config and its local plugins. patches/ and
+  .yarn/patches/ next to a monorepo's lockfile count too, and so do the patch
+  hashes pnpm-lock.yaml records, wherever the patch files live. The app's
+  version, ios.buildNumber and android.versionCode, eas.json, .easignore and
+  the path overrides of react-native.config.js are left out, so a Release
+  cache hit keeps the version it was built with. A project that wants native
+  package files hashed sets \`preset: 'strict'\` in fingerprint.config.js, at
+  about twice the fingerprint's CPU.
+
+  AN EDIT INSIDE node_modules/ IS NOT SEEN. Editing a dependency's native file
+  in place (node_modules/<pkg>/ios, android, cpp, a podspec or build.gradle)
+  leaves the key unchanged, so the next run installs the cached app without
+  the edit. Make the change a patch (patch-package's patches/, or pnpm patch,
+  whose patches the fingerprint hashes), or build it with
+  \`--no-build-cache --remote-build local\`. --no-build-cache alone can still
+  place the build on another machine, which installs dependencies from the
+  lockfile and so builds without the edit. The fresh build is stored under the
+  unchanged key in the machine-wide cache and handed to any cache provider, so
+  every worktree reuses it, edit included, until the dependency's version or
+  patches change; undo the edit with another --no-build-cache build.
+
+  A KNOWN TREE SKIPS THE FULL FINGERPRINT. After a full fingerprint at the
+  first lookup of a React Native or Expo run, Stim records it in
+  $STIM_HOME/fingerprint-memo (~/.stim by default) under a static digest of
+  the tree: git blob ids of the native inputs git tracks, the contents of the
+  untracked, modified and ignored ones, the app config's sources and the files
+  and directories it names, each installed package's path, version and native
+  markers, the lockfile, and the environment variables the config and its
+  .env files read. Any worktree whose tree has the same digest, a fresh one
+  included, reuses the record instead of evaluating the config and running
+  autolinking:
+
+    fingerprint matches a recorded fingerprint of this tree; confirming it in the background
+
+  A full fingerprint then runs at low priority while the app installs and
+  launches. The record is put back only when it agrees. If the run reaches its
+  end first, it waits up to 3 seconds more, then gives the check up and leaves
+  no record, so the next run fingerprints in full. A disagreement prints a
+  warning naming both hashes at the end of the run and writes a
+  fingerprint_memo_stale record to the build log; run the command again to use
+  the current tree.
+
+  A config the digest cannot follow always fingerprints in full: a dynamic
+  require or import, process.env used other than by literal name, file,
+  process or network access while it is evaluated, a dotenv import, a
+  fileHookTransform, or a preset that hashes package files. A local config
+  plugin counts as evaluated too, with one exception: the digest does not
+  track the files a plugin that applies mods reads, assuming it reads them in
+  its mods at prebuild. A plugin that also puts what it reads into the config
+  is a gap only the background check catches. So does a project outside git or on Yarn Plug'n'Play. The record is
+  never consulted after prebuild or pod install, by a build worker, by doctor,
+  or with --no-build-cache; ios --plan and android --plan read one without
+  writing. Records are 0600, at most 256 per platform, and gc prunes them by
+  age with the other caches.
+
   A MISS EXPLAINS ITSELF. Each local cache entry keeps the per-source hashes
   of its fingerprint (hashes only, pruned with the entry). Before compiling,
   Stim compares the sources it is about to store with a baseline: the entry
@@ -7397,9 +7540,13 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   status\` shows "shut down after 30m idle" on the device until the next
   \`ios\` or \`android\` run boots it again. When metro.idleStopMinutes is
   shorter, the dev server's idle stop first shuts down the devices idle that
-  long, because no supervisor is left to check afterwards. The supervisor
-  path does not check without a supervisor: release runs, and after
-  \`stim stop\`. The setting is read when the supervisor starts. Stim Desktop's simulator view is not a
+  long, because no supervisor is left to check afterwards. Devices with no
+  supervisor (release runs, a dev server that exited) are shut down by
+  automatic maintenance while maintenance.mode is on (guide cleanup): every maintenance.idleCheckMinutes
+  (5) a command starts a background check that applies each workspace's
+  current setting with the same idle rules, native-run lock recheck, status
+  and log record, and skips the workspace of the command that started it.
+  The supervisor reads the setting when it starts. Stim Desktop's simulator view is not a
   stim-server client and does not count as a viewer. Change it with
   \`stim settings set devices.idleShutdownMinutes <minutes> --scope machine\`;
   0 turns it off, and an explicit 0 stays 0.
@@ -8160,17 +8307,23 @@ THE POOL: WHICH DEVICE AN ID-LESS \`--device\` PICKS
   \`ios.simslim off\` opts that app out and restores stock services on its
   simulator. The defaults disable push, StoreKit, iCloud, Safari sync, Mail,
   Calendar and Contacts services, among others; move an app that needs them
-  to a profile that keeps those categories, or to \`off\`. A running or
-  parked simulator is slimmed the next time Stim boots or adopts it, and an
-  already slim simulator is left alone, so only the first slim reboots it.
+  to a profile that keeps those categories, or to \`off\`. A running
+  simulator is slimmed on the next \`stim ios\`, without a boot first, and a
+  parked simulator when Stim adopts it. An already slim simulator is left
+  alone, so only the first slim reboots it.
   Without the \`simslim\` command, doctor reports it and \`stim ios\` boots
   the simulator unslimmed with a one-line note. Hosted simulators on a named
   Mac are never slimmed, whatever either Mac's setting says.
 
   SimSlim 0.8 requires iOS 18.5 or newer. On each local \`stim ios\`,
   Stim reconciles that profile on the owned simulator before the app build.
-  The first change can update services and reboot the simulator. A matching
-  profile is a fast no-op on later launches. The settings persist across normal
+  The first change can update services and reboot the simulator. Stim records
+  the applied profile (the default categories, or a hash of the profile file)
+  and the boot of the simulator it was applied on, so a later launch on the
+  same boot with the same profile skips the \`simslim\` call. A changed
+  profile, a reboot, or a missing record reconciles again. A manual
+  \`simslim off\` on a running simulator is not noticed until the simulator
+  reboots or the profile changes. The settings persist across normal
   shutdowns and reboots. Removing the setting restores stock services when
   Stim applied the profile. Stim never changes an unowned or remote simulator.
   Each SimSlim operation has a 12-minute outer deadline, including discovery.
@@ -8267,13 +8420,14 @@ 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, help and every gc
+(every minute), idle devices (every 5 minutes, maintenance.idleCheckMinutes),
+directory sizes (hourly), finished worktrees (every 15 minutes) and the age
+sweep (daily). guide, settings, help and every gc
 invocation do not trigger it; gc without --delete prints the maintenance plan
 itself.
 status --watch and every running dev server supervisor also trigger checks
 each minute, so the disk check runs while no command does.
-Size, worktree and sweep checks defer under high load. Attempts back off for at
+Size, idle, 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. The size
 check also records the disk of each owned and parked simulator and emulator
@@ -8282,7 +8436,10 @@ 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. While the level is warning or critical, the
+and helpers for memory is not automatic. The idle check shuts down (never
+deletes) owned simulators and emulators idle for their workspace's
+devices.idleShutdownMinutes, also with no supervisor running, through the
+supervisor's idle rules and records (guide lifecycle budget). While the level is warning or critical, the
 check also names abnormally large processes (guide lifecycle simslim) in
 status's maintenance block and the maintenance log.
 
@@ -8299,13 +8456,25 @@ In on mode a pass runs, cheapest to rebuild first:
      claim (taken for each xcodebuild run that compiles with it) or that
      claim is unresolved; the emptying holds the exclusive claim
   5. linked worktrees whose branch or pull request finished (gc's finished
-     worktree rules and gc.worktreeGraceMinutes; maintenance.removeFinishedWorktrees)
-  6. owned simulators and emulators of a finished worktree that is kept, such
+     worktree rules and gc.worktreeGraceMinutes; maintenance.removeFinishedWorktrees),
+     and, with maintenance.removeIdleWorktrees (off by default), in the age
+     sweep clean, pushed ones unused for olderThanDays, as gc --delete
+     --worktrees --older-than removes them, git-ignored files included; never
+     a dirty one, one with unpushed commits, the source checkout, or one whose
+     last use is unknown
+  6. parked simulators and emulators unused for olderThanDays in the age
+     sweep, through centralized teardown with ownership checked again
+  7. owned simulators and emulators of a finished worktree that is kept, such
      as a dirty one (not one locked with git worktree lock), once it finished
      and was idle for gc.worktreeGraceMinutes (at least protectRecentHours),
      and of any
      workspace idle for maintenance.deviceIdleDays (3; 0 turns it off) in the
      age sweep. Devices are recreated on the next run.
+The age sweep runs every maintenance.sweepHours (24) in the background of
+commands, never at a set hour.
+maintenance.olderThanDays (7) is its age for steps 2, 3, 5 and 6; with 0 the
+sweep removes nothing in them by age, while step 1, step 7, finished
+worktrees and the cap and disk-driven parts of steps 2 and 3 still run.
 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
@@ -8401,6 +8570,23 @@ claim fails with ENOSPC or EDQUOT, the pass deletes it and retries once, so a
 pass starts at zero free disk as long as an earlier pass left the reserve; the
 pass writes it again at its end.
 
+WHAT WAS CLEARED
+Every run that deletes or changes something appends one record per item to
+the machine gc log, $STIM_HOME/gc/gc.ndjson: gc --delete with any flags, gc
+--idle, gc --cache --delete, each maintenance action taken, and what the budget gate
+reclaims before stim start, ios or android. A dry run writes nothing, and a
+gc run that only kept items writes nothing. Failed and kept items carry their
+reason. The file rotates at maintenance.logMaxMb and its old generation is
+kept for maintenance.logRetentionDays, like the maintenance log.
+  stim logs --source gc           the retained records, oldest first
+  stim logs --source gc --json    one record per line
+  stim logs --source gc --errors  only the items that failed
+gc works from any directory because the log is machine-wide; it cannot be
+combined with other --source values and --source all leaves it out. Fields
+(\`guide logs\`, GC LOG): runId, trigger (manual, desktop, maintenance or
+budget), options, kind, status (done, kept or failed), label, id, path,
+bytes, detail.
+
 CLEANUP AND DISK
 
 worktree remove stops the agent-device daemon when the workspace's
@@ -8805,7 +8991,9 @@ SWEEPING FINISHED WORKTREES
   one, else by the RECENT ACTIVITY sources above being older than
   --older-than days (reason recently-used while they are newer, and
   last-use-unknown when they cannot be read). Automatic maintenance removes it
-  only at disk pressure level 3, once that activity is older than
+  the same way in its daily age sweep, after maintenance.olderThanDays, only
+  with maintenance.removeIdleWorktrees (off by default), and at disk pressure
+  level 3 once that activity is older than
   maintenance.pressureProtectMinutes and at least 5 minutes old, whatever
   the setting; unreadable activity keeps it. Removal re-checks, under the removal
   locks, that HEAD did not move and the worktree is still idle, and
@@ -9495,9 +9683,9 @@ KEYS STIM READS
                         iOS work after reviewing service tradeoffs; see
                         \`stim guide lifecycle simslim\`. Each local \`stim ios\`
                         reconciles the profile on its Stim-owned simulator.
-                        The first change can reboot it; a matching profile is a
-                        fast no-op. Removing the setting restores stock services
-                        when Stim applied the profile. Absolute paths, root or
+                        The first change can reboot it; an unchanged profile on
+                        the same boot is skipped. Removing the setting
+                        restores stock services when Stim applied the profile. Absolute paths, root or
                         symlink escapes, and missing files are refused before
                         simulator creation. Remote and unowned simulators are
                         never changed.
@@ -10088,6 +10276,11 @@ never decide who the worker is. With --fix, a pending entry is replaced when
 STIM_ACCESS_TICKET names another ticket.
 Approved doctor entries under remoteMachines and deviceHosts include host
 { name, screenRecording, accessibility } when the worker reports it.
+A remote machine doctor cannot use carries a diagnosis { layer, code, title,
+message, remedy } naming the first layer that failed: Tailscale on this machine,
+the peer, the serve route, stim-server, or compatibility. Tell the user its
+message and remedy; the remedies run on the remote machine or in Tailscale, so
+agents do not run them. \`stim guide facts doctor\` lists the codes.
 
 REMOTE MACHINES AND PHONE APP
 When the user mentions slow builds, a busy machine, a full disk or device limit, or
@@ -10263,7 +10456,8 @@ at setup before consulting the cache; they create no build record or failed-run
 stats. A listed paired name with a cache hit compiles nothing, contacts no worker
 and records buildMachine with builtOn absent. Build failures retain the selected
 value; builtOn is here or the configured machine entry when compilation ran.
-Prebuild and pod install still run on this machine before a named offload. A refusal
+Prebuild and pod install still run on this machine before a named offload; stim ios
+checks the machine's toolchain first. A refusal
 starts no local xcodebuild, Gradle or SwiftPM compile.
 A React Native offload sends the tracked and untracked files, and the gitignored
 files the native fingerprint hashes or the Expo config reads, such as .env.local
@@ -10360,18 +10554,44 @@ match. Completed archives survive worker checkout changes or removal; hits
 need no source upload or build slot. Disabled remote artifact reads skip this
 lookup. Release and physical-device builds keep their existing paths.
 SwiftPM, compiler and dependency caches use their existing paths.
-For iOS the machine's Xcode and simulator SDK must match, and it needs an
-iPhone simulator on the target runtime. Its project-selected CocoaPods must match too, unless
-the app's Gemfile.lock, in ios/ or the project root, pins CocoaPods: both machines then run that version through
-bundler, so the machine needs only Bundler on its stim-server PATH and
+For iOS the machine's Xcode and simulator SDK must match. Its offer reports the
+developerDir xcode-select prints and the Xcode apps in /Applications (version,
+build, and license and first-launch checks while no Xcode works), so doctor's
+fix for no usable Xcode is the exact command to run there: sudo xcode-select -s
+<the Xcode with this machine's build, else the newest>/Contents/Developer when
+the Command Line Tools or another Xcode is selected, sudo xcodebuild -license
+accept and sudo xcodebuild -runFirstLaunch for the checks that fail, or xcodes
+install <version> with no Xcode app. A runtime the machine lacks gets
+xcodebuild -downloadPlatform iOS -buildVersion <version>, or a pointer to the
+Xcode problem when xcode-select is the cause. A stim-server that reports no
+developerDir keeps the prose fix. It also needs an
+iPhone simulator on the target runtime. A missing or different global CocoaPods
+keeps automatic placement from choosing the machine for a project that does not
+pin it, unless the machine already holds the exact artifact; the placement line
+says why and doctor shows the install command. A named --remote-build still
+sends the build, and a pod install that fails there reports "pod install failed"
+with the fix on that machine. When the app's Gemfile.lock, in ios/ or the project
+root, pins CocoaPods, both machines run that version through
+bundler, so the machine needs Bundler on its stim-server PATH and
 installs the pinned gems itself on the first build. This Mac's side of the
 comparison runs \`pod --version\` in the directory pod install runs in. The comparison selects
 the app's .ruby-version when installed, otherwise rvm's or rbenv's default Ruby, and only when neither exists the GEM_HOME, GEM_PATH and Ruby-related PATH entries of the machine's login shell (read once with $SHELL -lic), unless the caller already sets GEM_HOME, with pod install's UTF-8 locale defaults. pod install, including the Bundler run, uses the same environment.
 For Android its CPU may differ, since the APK's ABIs come from the NDK, so an
 x86_64 Linux or Windows machine running stim-server can build for an Apple silicon Mac. Its JDK major
-version must match, and its Android SDK must hold the NDK, build-tools and
+version must match this machine's, which can be an installed JDK that is not the
+worker's default: its offer lists \`jdks\`, and a build sent with the build-jdk
+feature runs with JAVA_HOME at the one of that major. A major no installed JDK
+has gets the install command for the worker's OS as doctor's fix. A nearby major
+never counts (Gradle, AGP and Kotlin support and the shared build cache assume
+one JDK). Also, 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
+gradle/libs.versions.toml; Gradle and AGP come from the synced project. A
+package the SDK lacks is a note, not a blocker, when its offer reports the SDK
+licenses accepted (\`licenses/android-sdk-license\`) and the app's
+Gradle root's gradle.properties does not set android.builder.sdkDownload=false:
+Gradle downloads the package on the first build there (the NDK is about 1-2 GB).
+Otherwise it blocks, and doctor's fix is the sdkmanager commands to run on that
+machine; a stim-server that does not report its licenses keeps that rule. When
 no machine takes the build in auto placement, the run prints one line with each machine's
 reason, such as \`janics-mac-mini: busy (load at or above 2/core; load
 8.2/core, 2 builds) -> building here\`, and compiles here. It sends the files

package/dist/{hosted-android-Bvb2-ZxD.mjs → hosted-android-Bk54ej6n.mjs}

@@ -1,7 +1,7 @@
 import { c as throwIfCancelled } from "./exec-VFRpu1iA.mjs";
-import { c as call, l as connectHost } from "./hosted-client-rsRqysJc.mjs";
-import { i as requestHostedMetro } from "./metro-gateway-Bp9gJQAN.mjs";
-import { a as stopHostedNative, i as prepareHostedNative, r as placeHostedNative } from "./hosted-native-BxTizGU2.mjs";
+import { c as call, l as connectHost } from "./hosted-client-fHO8yqzc.mjs";
+import { i as requestHostedMetro } from "./metro-gateway-B6_PgD0L.mjs";
+import { a as stopHostedNative, i as prepareHostedNative, r as placeHostedNative } from "./hosted-native-CpDB3-PO.mjs";
 //#region src/device-host/hosted-android.ts
 async function prepareHostedAndroid(machine, selectors, recorded, mode) {
 	return await prepareHostedNative(machine, selectors, recorded, "android", false, mode);

package/dist/{hosted-client-rsRqysJc.mjs → hosted-client-fHO8yqzc.mjs}

@@ -1,7 +1,7 @@
 import { c as throwIfCancelled, o as cancellableSleep } from "./exec-VFRpu1iA.mjs";
-import { rt as resolveEndpoint } from "./config-BZhXY15H.mjs";
-import { t as BuildConnection } from "./client-BQsmyp_-.mjs";
-import { d as configuredMachines } from "./selection-D5cxEl3t.mjs";
+import { at as resolveEndpoint } from "./config-BktkY_zC.mjs";
+import { t as BuildConnection } from "./client-D9CaRks-.mjs";
+import { m as configuredMachines } from "./selection-BNPBZ6T5.mjs";
 import { createHash } from "node:crypto";
 import { lstatSync, readFileSync, readdirSync, readlinkSync } from "node:fs";
 import { join } from "node:path";
@@ -50,11 +50,11 @@ async function connectHost(machine, timeoutMs = CONNECT_TIMEOUT_MS, strict = fal
 	signal?.throwIfAborted();
 	if (typeof target === "string") throw Object.assign(/* @__PURE__ */ new Error(`Stim does not connect to ${machine}: ${target}.`), { code: "STIM_HOSTING_REFUSED" });
 	const opened = await BuildConnection.open(target, credential.serverKey, timeoutMs, "device-host", signal).catch((error) => {
-		throw Object.assign(new Error(`${machine} is unreachable. Check stim-server and its tailnet serve route on ${machine}.`, { cause: error }), { code: strict ? "STIM_HOSTING_REFUSED" : "closed" });
+		throw Object.assign(new Error(`${machine} is unreachable. Run stim doctor to see which layer failed.`, { cause: error }), { code: strict ? "STIM_HOSTING_REFUSED" : "closed" });
 	});
 	if (signal?.aborted && opened instanceof BuildConnection) opened.close();
 	signal?.throwIfAborted();
-	if (!(opened instanceof BuildConnection)) throw Object.assign(/* @__PURE__ */ new Error(opened.code === "server-outdated" ? `${machine} runs a stim-server that speaks an older protocol than this Stim. Run stim doctor for the command that updates it there, then retry.` : opened.refused ? `${machine} refused this machine: ${opened.failure.replace(/\.+$/, "")}. Run stim doctor.` : `${machine} is unreachable: ${opened.failure}. Check stim-server and its tailnet serve route on ${machine}.`), {
+	if (!(opened instanceof BuildConnection)) throw Object.assign(/* @__PURE__ */ new Error(opened.code === "server-outdated" ? `${machine} runs a stim-server that speaks an older protocol than this Stim. Run stim doctor for the command that updates it there, then retry.` : opened.refused ? `${machine} refused this machine: ${opened.failure.replace(/\.+$/, "")}. Run stim doctor.` : `${machine} is unreachable: ${opened.failure}. Run stim doctor to see which layer failed.`), {
 		code: strict ? "STIM_HOSTING_REFUSED" : opened.refused ? "STIM_HOSTING_REFUSED" : opened.code ?? "closed",
 		hostCode: opened.code
 	});

package/dist/{hosted-ios-RtVcJH3u.mjs → hosted-ios-D55QhYaD.mjs}

@@ -1,4 +1,4 @@
-import { a as stopHostedNative, i as prepareHostedNative, r as placeHostedNative } from "./hosted-native-BxTizGU2.mjs";
+import { a as stopHostedNative, i as prepareHostedNative, r as placeHostedNative } from "./hosted-native-CpDB3-PO.mjs";
 //#region src/device-host/hosted-ios.ts
 async function prepareHostedIos(machine, selectors, recorded, mode) {
 	return await prepareHostedNative(machine, selectors, recorded, "ios", false, mode);