stim 1.15.0 → 1.16.0

package/dist/{guide-cCSGRFd3.mjs → guide-B_uyKTxW.mjs}

@@ -1,8 +1,8 @@
-import { a as findProjectRoot$1 } from "./project-CV3tDFHl.mjs";
-import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-CduVcoxj.mjs";
-import { t as RECENT_LAUNCH_MS } from "./status-l84Gbvp2.mjs";
-import { t as guideStatus } from "./guide-status-CIoWK6mG.mjs";
-import { SETTINGS_SCHEMA_URL } from "@stim-cli/core/state";
+import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-oTSkkNrM.mjs";
+import { o as findProjectRoot$1 } from "./project-Du91Ilvc.mjs";
+import { t as RECENT_LAUNCH_MS } from "./status-BuvBFeII.mjs";
+import { t as guideStatus } from "./guide-status-CjEZMAD4.mjs";
+import { SETTINGS, SETTINGS_SCHEMA_URL } from "@stim-cli/core/state";
 import chalk from "chalk";
 //#endregion
 //#region src/guide/index.ts
@@ -43,6 +43,22 @@ reach multiple devices. A launch counts a bundle delivery only when it can
 attribute it to its own device; read guide lifecycle options for the rule.
 Use stop --slot <name> for one slot, or plain stop for the whole workspace.
 
+HOSTED IOS
+
+For ios --remote <machine>, read guide lifecycle hosted-ios. Stop before switching
+between a local simulator and a hosting Mac. Hosted Debug requires the local
+Metro supervisor; restart a missing or older one with stim stop; stim start.
+It never falls back here; stop reconciles the recorded host before changing placement.
+For hosted iOS, use agent-device <command> --remote-config <file> from ios.host.agent
+in stim status --json. Open the installed app first; never use the host UDID locally.
+See guide lifecycle hosted-ios for the agent policy and setup.
+
+When driving a device yourself with agent-device, set AGENT_DEVICE_STATE_DIR
+from agentDevice.stateDir in stim ios|android|macos --json or status --json.
+Its sessions and logs are then cleaned with the workspace. Do not set
+AGENT_DEVICE_IOS_RUNNER_DERIVED_PATH or AGENT_DEVICE_CLAIMS_DIR; the runner
+build cache and device claims stay shared. Read stim guide logs for examples.
+
 NORMAL WORKFLOW
 
 Create a linked worktree with Git and warm its ignored state. If a harness
@@ -114,6 +130,9 @@ To learn whether the next build is a cache hit and how long it should take,
 without building, run stim ios --plan (or stim android --plan); see stim guide
 lifecycle builds.
 
+Agents never set STIM_ACCESS_TICKET, run stim-server setup, edit offload.*
+or hosting.* for the user, or approve requests. Read stim guide settings for
+Desktop access tickets and person-owned approval.
 Read stim guide settings to select a build machine. Keep a requested named
 placement when recovering STIM_OFFLOAD_REFUSED: report its reason and remedy.
 
@@ -140,6 +159,8 @@ waiting times out.
 
 RULES DURING THE LOOP
 
+- Agents never run stim-server setup and never approve access requests.
+  A person on the worker approves builds and device hosting (guide settings).
 - Run Stim from the app directory: the one whose package.json depends on
   react-native or expo. Anywhere else -- a monorepo root, a tools package --
   start, ios and android refuse with STIM_NO_PROJECT naming that package.json,
@@ -370,6 +391,15 @@ stdout for \`--json\`. Every other line goes to stderr, so it is always safe
 to pipe. \`logs --json\` is the one exception: it is NDJSON, one record per
 line by design (see \`guide logs\`), not this single-payload contract.
 
+status adds archived (newest first, bounded by archive.maxCount) and
+archivedUsage { count, bytes, byKind: { logs, recordings, agentActions, record } }.
+Each archive carries id, projectRoot, project, workspace, worktree facts,
+removedAt, removedBy, lastUsedAt, builds, agents, bytes, expires and version.
+replacedBy is the live environment path when its canonical root matches.
+Older producers may omit both fields.
+Plain status prints Archived: <count> workspace(s), <size> when count is positive;
+status --watch reuses archive reads until archive changes and emits no duplicates.
+
 status's unprovisionedWorktrees lists the linked worktrees with no Stim
 environment in every repository with a registered environment, plus the
 repository status runs from. A worktree counts as having an
@@ -501,7 +531,7 @@ Plain status prints "ios: Old iPhone (physical, iPhone 12 Pro) connected --
 leased until <time>" for each one.`,
 		sections: {
 			payloads: {
-				summary: "every field of the start, ios, android, web and reload payloads, the error contract, the device rules",
+				summary: "every field of the start, ios, android, macos, web and reload payloads, the error contract, the device rules",
 				body: () => `  stim start --json
 
   port            the Metro port RESERVED for this workspace
@@ -509,6 +539,8 @@ leased until <time>" for each one.`,
                   already answering that Stim did not start
   mode            "bare-inproc" | "expo-child" | null (see \`guide metro\`)
   logsDir         where the NDJSON timeline is written
+  agentDevice     { stateDir }: absolute workspace agent-device state path;
+                  set AGENT_DEVICE_STATE_DIR to it (see guide logs)
   alreadyRunning  true when nothing needed starting
   links           { desktop }: a stim-desktop://workspace?path=<workspace>
                   link that shows this workspace in Stim Desktop. Absent when
@@ -516,6 +548,13 @@ leased until <time>" for each one.`,
                   prints it on stderr as "Open in Stim Desktop: <link>"; so
                   does worktree warm, which has no JSON payload
 
+  stim macos --json
+
+  platform        "macos"
+  product, launchId, build, host?  the launch record (see guide macos)
+  agentDevice     { stateDir }: absolute workspace agent-device state path
+                  for local or hosted launches with a local workspace
+
   stim ios --json
 
   platform        "ios"
@@ -669,6 +708,7 @@ leased until <time>" for each one.`,
                   launch with no process id is "unverified", and
                   \`stim logs --errors\` has the device log that says why
   logs            { dir }
+  agentDevice     { stateDir }: absolute workspace agent-device state path
   durationMs      wall time for the whole run
 
   stim android --json
@@ -742,6 +782,7 @@ leased until <time>" for each one.`,
                   error, and this field is separate from cacheHit. On an
                   offloaded APK it is the build machine's ccache
   logs            the workspace log directory
+  agentDevice     { stateDir }: absolute workspace agent-device state path
   durationMs      wall time for the whole run
   reclaimed       present only when the run was over its disk or memory
                   budget and reclaimed first (\`start\`, \`ios\` and
@@ -838,7 +879,7 @@ 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? }
+  deviceHosts     one { machine, state, dnsName?, deviceId?, requestedAt?, host? }
                   per hosting.machines entry. state is "approved", "pending",
                   "not-asked", "revoked", "node-changed", "not-on-tailnet",
                   "tailscale-off", "unreachable", "invalid",
@@ -846,12 +887,15 @@ leased until <time>" for each one.`,
                   Only --fix asks for access or forgets removed names.
                   An approved hosting machine does not imply build approval
                   or change ios/android placement; see \`guide settings\`.
+                  host is { name, screenRecording, accessibility }, present
+                  only for approved machines whose worker reports it.
   buildMachines   one { machine, state, dnsName?, deviceId?, requestedAt?,
-                  offloadable?, reasons?, problems?, capacity? } per
+                  offloadable?, reasons?, problems?, capacity?, host? } per
                   offload.machines entry; state is "approved", "pending", "not-asked",
                   "revoked" (revoked, or the request lapsed), "node-changed",
                   "not-on-tailnet", "tailscale-off", "unreachable" or
-                  "invalid". An approved machine also carries offloadable,
+                  "invalid". host has the same shape and presence rule as in
+                  deviceHosts. 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,
@@ -870,6 +914,7 @@ leased until <time>" for each one.`,
                   optional fields
   findings        the diagnostic findings; a lower resolved Stim is a
                   costs-time finding with a PATH or installation remedy
+                  offload-candidate is a note after 3+ successful local cold builds in 7 days average over 3 min, with no offload.machines and an online tailnet Mac; open Stim Desktop Settings > Build machines > Add
 
 ON FAILURE
   \`start\`, \`ios\`, \`android\` and \`web\` all print the error contract instead,
@@ -937,15 +982,17 @@ RULES
   that is the URL the launcher hands to the check; on the
   outer deep link it does nothing there. Android reads it on
   either.
-  ON A SIMULATOR, before a local dev-client openurl, Stim
-  preapproves CoreSimulatorBridge for exactly the installed
-  bundle id and discovered scheme on its owned simulator. That
-  suppresses iOS's first-launch confirmation;
-  unrelated schemes remain unapproved. The approvals persist
-  until the simulator is erased, so Stim records the ones it
-  wrote on the workspace's device record and writes only the
-  ones missing from it. Parking drops the record, so an
-  adopted simulator gets them again once.
+  ON AN OWNED SIMULATOR, Stim preapproves CoreSimulatorBridge
+  for the installed bundle id and every URL scheme its Info.plist
+  declares, except system and third-party SDK schemes, also for
+  apps without expo-dev-client. The "Open in <App>?" alert can
+  still appear for an unapproved scheme, on a physical device or
+  user-created simulator, or from another opener such as Safari.
+  After \`simctl openurl\` or \`agent-device open <url>\`, expect
+  it for such schemes; take a snapshot and tap Open.
+  Approvals persist until erasure; Stim records them and writes
+  only missing ones. Parking drops the record, so adoption
+  rewrites them once.
   THE DEV MENU AND ITS BUTTON stay off a simulator two ways,
   which the onboarding flag does NOT cover. Stim's own
   \`simctl launch --initialUrl\` ends in
@@ -1119,6 +1166,10 @@ RULES
                     timing out or an AVD or system image folder Stim
                     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
+                  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
                   is present, empty when there is nothing to report:
     deadProjects            { path }
@@ -1206,6 +1257,11 @@ RULES
                               directories that --delete removes whole (dead
                               projects and orphanedWorkspaces), and --cache
                               all does not
+    agentDevice             <AgentDeviceUsage|null>  report-only; workspace state
+                              goes only with its workspace;
+                              null with any --cache scope
+    swiftpmCache            <SwiftpmCacheUsage|null> report-only, never deleted;
+                              null with any --cache scope
     caches                  { name, dir, source, bytes, note, willEmpty,
                               emptySkipped, scopedEmpty }  alive, not
                               garbage; willEmpty marks the ones --delete
@@ -1267,6 +1323,11 @@ RULES
 				summary: "the status payload's lifecycle phase and stage, issues and their codes, build and device activity fields: a running build, its estimate, each platform's last build, who drives each device, whether the app runs on it, and what uses CPU and memory now",
 				body: () => `  stim status --json
 
+  logs        { dir, errorsSinceMarker }, or null without a log directory
+  agentDevice { stateDir }: absolute workspace agent-device state path on
+              every environment, shared by its slots. Reporting it creates
+              no directory; agent-device creates it when used.
+
   Each environment carries phase, where the workspace is in its lifecycle:
 
   phase       "warming"  stim worktree warm runs in it now
@@ -1280,6 +1341,15 @@ RULES
               for "live" and "idle"
   warmStep    "refresh" or "copy", the step a warming workspace is in;
               absent in other phases
+  platforms   ordered supported app platforms: ios, android, macos, web;
+              always present, [] when none are detected. Expo uses its
+              explicit platforms list, otherwise ios and android plus web
+              with react-native-web. Bare apps use ios/*.xcodeproj or
+              *.xcworkspace and android/ Gradle project files. web.url adds
+              web to any app and overrides an Expo list; a bare app has no
+              other route to web. macOS needs Package.swift, macos.product
+              and macos.infoPlist. Detection reads config literals and
+              files, never runs project scripts.
   recording   { enabled }: whether stim-server may record the workspace's
               device screens for replay, from recording.enabled
 
@@ -1544,7 +1614,8 @@ RULES
   run that holds this workspace's native-run.lock:
 
   build   { platform, slot, state, phase, startedAt, phaseStartedAt,
-            outcome, outcomeKnown, cacheLookupOutcome?, expectedMs, expectedPhaseMs, basis,
+            outcome, outcomeKnown, cacheLookupOutcome?, expectedMs, expectedPhaseMs,
+            completedPhaseMs?, basis,
             plannedPhases, missReason?, missProvisional?, detail?, placement,
             waitingOn? }
 
@@ -1589,6 +1660,10 @@ RULES
                    not change the estimate.
   expectedPhaseMs  the median duration of this phase in those runs, or null
                    when none of them entered it
+  completedPhaseMs  milliseconds spent in each phase the run already left,
+                   summing repeated visits. The current visit is excluded;
+                   its phase appears only if visited earlier. Absent before
+                   any phase completes and on older Stim versions
   basis            how many runs the expectedMs median comes from (at most
                    10 per kind: device-setup runs keep their own 10)
   plannedPhases    [{ phase, expectedMs }] in phase order: the phases at
@@ -1818,6 +1893,19 @@ 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,
+                lastPass, running, recent, plan, invalid?, claim? }
+    Report-only observations; every plan action's kind starts with would-.
+    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
+    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
+    unresolved claim's path and reason, plus removeCommand from the claim
+    protocol; inspect the holder before running that command.
+
   machine   null, or { memorySource, owners: [{ kind, name, workspace,
             slot?, id, owned, cpuPercent, residentMb, memoryMb,
             processes }] }
@@ -1913,7 +2001,9 @@ RULES
     "offload": { "today": { "here", "offloaded", "fellBack" },
                  "machines": { "<machine>": { "today": <day>,
                                               "total": <totals> } },
-                 "placements": [<placement>, ...] } }
+                 "placements": [<placement>, ...] },
+    "agentDevice": <AgentDeviceUsage|null>,
+    "swiftpmCache": <SwiftpmCacheUsage|null> }
 
   \`project\` is null outside a project; a platform with no run yet is null.
   A bucket carries runs, failed, hits, misses, coldRuns, coldRunMs, hitRuns,
@@ -1924,6 +2014,44 @@ RULES
   average, time saved and build estimates stay local. Milliseconds are
   integers.
 
+AGENT-DEVICE DISK USAGE
+  agentDevice: { version: 1, measuredAt, bytes, complete, stateDir,
+                 runnerBuilds, workspaces, hosted }
+  bytes sums known state, separate runner builds, workspace and hosted bytes;
+  complete is false when a measurement fails. Individual unknown byte fields
+  are null. Absent directories have zero bytes and present: false.
+  stateDir defaults to ~/.agent-device. AGENT_DEVICE_STATE_DIR overrides it
+  only when it does not overlap a workspace agent-device dir or the hosted dir.
+  stateDir: { dir, present, bytes, sessions: { dir, bytes, count },
+              logs: { dir, bytes }, other: { bytes, largest: [{ name, bytes }] } }
+  runnerBuilds: { dir, present, bytes, sharedBytes, platforms: [
+    { platform, dir, bytes, entries: [{ name, dir, bytes, lastUsedAt,
+      packageVersion, xcodeBuildVersion, inUse, inUseReason }] }] }
+  inUseReason is lease, lock, unreadable or null. Lease means a live owner or
+  runner matched by start time; lock means a live or unknown lock owner.
+  Unreadable lock owners and unreadable or unknown leases use unreadable.
+  Dead lock owners and leases do not mark entries in use.
+  workspaces: [{ dir, projectRoot, bytes }]; hosted: { dir, bytes, sessions } | null.
+  $STIM_HOME/agent-device-usage.json caches the measurement and resolved roots
+  for 10 minutes. stats and unscoped gc measure; no other command measures this
+  state. Server stats.get reads only the cached value.
+  Stim never trims or deletes the shared runner builds, sessions, logs and other
+  state or the hosted driver dir; a workspace's own agent-device dir goes only with its workspace.
+
+SWIFTPM CACHE DISK USAGE
+  swiftpmCache: { version: 1, measuredAt, dir, present, bytes, complete } | null.
+  The user-level cache is ~/Library/Caches/org.swift.swiftpm on macOS and
+  org.swift.swiftpm under XDG_CACHE_HOME (default ~/.cache) elsewhere.
+  It is shared by every SwiftPM build on the machine; Stim never deletes it.
+  bytes is null and complete is false if du fails; absent directories have
+  present: false, bytes: 0 and complete: true. Plain output omits absent caches.
+  $STIM_HOME/swiftpm-cache-usage.json caches the measurement for 10 minutes,
+  keyed on the resolved dir. stats and unscoped gc alone run du -sk with a
+  20-second timeout. Server stats.get reads only the cached value. status,
+  start, ios, android and the budget gate never measure it. gc reports it as
+  sections.swiftpmCache, never in caches or actionable; --delete and
+  --older-than leave it untouched, and any --cache scope reports null.
+
 HOW A RUN IS COUNTED (\`stats\`)
   Every \`ios\` or \`android\` invocation that got as far as computing a
   cache key is one run, in this project's bucket and in the machine-wide one.
@@ -1968,9 +2096,9 @@ HOW A RUN IS COUNTED (\`stats\`)
   run's outcome.
 
 BUILD PLACEMENT (\`offload\`)
-  While at least one build machine is paired, every run that compiles
-  records where it built and why, in a placement: { at, project, platform,
-  decision, reason, machine?, buildMs?, localEstimateMs?, failed? }.
+  Every run that compiles records where it built and why, in a placement: { at, project, platform,
+  decision, reason, machine?, buildMs?, slotWaitMs?, localEstimateMs?, failed? }.
+  slotWaitMs is whole milliseconds waiting for a build slot, present only when positive.
   decision is "here", "offloaded", or "fell-back" (it tried a build machine
   and built here). reason is why: the run's \`placement:\` reason, such as
   "load 0.6/core, 1 of 3 build slots busy here" (auto keeps the build here
@@ -2013,9 +2141,25 @@ another worktree's bundler.
   --remote          expose Metro for a remote device
 
 Plain \`stim start\` is local and does not create a tunnel. Remote intent
-comes from \`start --remote\`, \`ios.remote\`, or \`android.remote\`. The
+comes from \`start --remote\`, eas/proxy in \`ios.remote\`, or \`android.remote\`. The
 \`metro.tunnel\` setting selects the provider after remote intent exists.
 
+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 Mac's Tailscale address and accepts only the pinned hosting peer
+  with a per-session secret. The host's bridge is loopback-only. 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
+  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
+  with stim stop; stim start.
+  Native iOS logs are pulled from the host by stim logs, including --errors;
+  JavaScript logs still arrive through Metro. Stop pulls native logs before
+  deleting the simulator. Read guide lifecycle hosted-ios for placement and cleanup.
+
 TAILNET-ONLY METRO
   Install Tailscale and sign in on this machine and the remote device or
   agent-device daemon's host, then select the mode explicitly:
@@ -2327,6 +2471,34 @@ instead of allocating a separate label in every worktree.`
 		summary: "Querying the merged NDJSON timeline, and what --errors means",
 		body: () => `LOGS
 
+If Stim is not installed globally, replace stim with npx stim.
+
+AGENT-DEVICE WORKSPACE STATE
+
+When you drive a device yourself with agent-device, opt in to the workspace's
+state directory reported as agentDevice.stateDir in the stim ios, android and
+macos output and in status. Read it once from status, run from the app root:
+
+  STATE_DIR="$(stim status --json | jq -r '.environments[] | select(.path=="'"$(pwd -P)"'") | .agentDevice.stateDir')"
+
+Then prefix each agent-device command, so the choice survives shells that do
+not keep exports:
+
+  AGENT_DEVICE_STATE_DIR="$STATE_DIR" agent-device open <bundle id> --platform ios --session <name>
+  AGENT_DEVICE_STATE_DIR="$STATE_DIR" agent-device snapshot --session <name>
+
+The path is $STIM_HOME/workspaces/<name>/agent-device. agent-device creates it
+itself. Sessions (including events, runner logs and request text), logs,
+metro-sessions, allocations and daemon files move there. The apple-runner build
+cache and device claims stay shared; do not set
+AGENT_DEVICE_IOS_RUNNER_DERIVED_PATH or AGENT_DEVICE_CLAIMS_DIR.
+Each active workspace adds one agent-device daemon, which exits after five
+idle minutes with no open session. The variable is opt-in per command: forgetting it falls back to
+~/.agent-device.
+stim stop closes owned-device sessions there, stim logs --source agent reads
+them, and stim worktree remove stops the daemon and removes the directory.
+Hosted/stim-server sessions use their own state directory and need none of this.
+
   stim logs [filters]
 
 Reads every *.ndjson file in the global workspace logs directory, merges them into one timeline
@@ -2365,7 +2537,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 (one or more), or all.
+  --source <s...>  metro, client, device, build, agent, maintenance (one or more), or all.
                    An unknown value is REJECTED rather than quietly matching
                    nothing.
   --level <l>      minimum level: debug, info, warn, error, fatal
@@ -2513,7 +2685,14 @@ THE RECORD
              there are none. Stim adds it at query time; it is not in the
              log files.
 
+Maintenance records use src: maintenance and appear in the plain timeline.
+  stim logs --source maintenance
+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.
+
 WHAT WRITES WHAT
+  maintenance.ndjson   workspace maintenance actions, failures and explaining skips
   metro.ndjson         the bundler, in both supervisor modes
   client.ndjson        in-app console logs and redboxes -- BARE PROJECTS ONLY.
                        In expo-child mode everything Expo prints lands in
@@ -2655,7 +2834,8 @@ WHAT WRITES WHAT
                        web.ndjson (\`guide web\`). For simulators and
                        emulators, no file: each query reads agent-device's
                        session records (~/.agent-device/sessions, or
-                       AGENT_DEVICE_STATE_DIR) for this workspace's owned
+                       AGENT_DEVICE_STATE_DIR, plus existing workspace
+                       agent-device directories) for this workspace's owned
                        simulators and emulators, read-only. An action is
                        info (msg is agent-device's summary, e.g. "Tapped
                        (201, 731)"; event agent_action with command, session,
@@ -2692,6 +2872,23 @@ WHAT WRITES WHAT
 Every refusal listed here carries a stable CODE, whichever command prints it.
 Branch on the code, never on the message.`,
 		sections: {
+			STIM_HOSTING_REFUSED: {
+				summary: "a named hosting Mac refused or could not confirm its iOS session; no local fallback",
+				body: () => `STIM_HOSTING_REFUSED
+  The message names the hosting Mac and its reason: unreachable or changed
+  tailnet node, no installed simulator choice, no capacity, elevated or unknown
+  memory pressure, or an unresolved reservation or delivery. Stim boots nothing
+  locally and never tries another Mac. Check stim-server and Tailscale there,
+  then run stim doctor. Correct --device-type / --runtime when the offer names
+  an unavailable choice. A session that exists stays recorded even if delivery
+  fails: retry stim ios --remote <machine>, or run stim stop to reconcile it.
+  An unreachable stop keeps the placement; rerun stim stop when the host answers.
+  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 iOS handoff and native logs (hello feature hosted-ios-data).
+  A name outside hosting.machines is STIM_BAD_ARG. Missing or pending hosting
+  approval keeps the doctor --fix and stim-server devices grant remedies.`
+			},
 			STIM_EAS_BUILD_MISSING: {
 				summary: "no completed EAS development build matches; build only with session authorization",
 				separator: "--- EAS BUILD CODES (`ios --eas-profile` / `android --eas-profile`) ---",
@@ -3004,7 +3201,9 @@ no build and does not contact the selected machine.
 
 Run stim doctor --fix to ask for build access if not paired. Check
 stim settings get offload.machines. A person on the worker finds the id with
-stim-server devices and approves this Mac with stim-server devices grant <id> --build.
+stim-server devices and approves this Mac with stim-server devices grant <id> --build,
+or runs stim-server setup on the worker with its node, ticket and expiry
+(guide settings). Agents never run setup or approve requests.
 Rerun with --build-machine auto for normal placement and local fallback, or
 --build-machine local to keep the build here.
 `
@@ -3730,7 +3929,7 @@ captured"  (in metro.ndjson, bare RN)
   cannot be verified,
   \`--device\` with an empty
   serial or UDID, \`--device\` together with \`--remote\`, \`ios --runtime\`
-  on a remote run (\`--remote\` or ios.remote; the remote backend picks the
+  on an eas/proxy run (\`--remote\` or ios.remote; that backend picks the
   iOS version), \`ios --device-type\` on the proxy backend or with an
   eas-cli older than 22.2.0 on the eas backend, \`android --system-image\` or
   \`--device-profile\` on a remote run (\`--remote\` or android.remote), a
@@ -4286,8 +4485,10 @@ apply. The run then reports \`devServer: { started: true, reason }\` in its
 JSON, with reason "not running" or "stopped (idle)". When that start fails,
 the run refuses with the start's own code (STIM_METRO_TIMEOUT,
 STIM_SUPERVISOR_EXITED, ...) before any build work. Release builds and
-\`--no-metro-check\` neither check nor start the dev server. \`--remote\`
-starts it the way \`stim start --remote\` does. Step 2 remains useful to warm
+\`--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
 Metro while other work happens.
 
 Repeat step 3 whenever a NATIVE input changes. A JS-only edit needs nothing --
@@ -4451,6 +4652,166 @@ WAITING FOR A CHANGE
   still running, which it notices at the next change.
   Without --json it reprints the human view on change.`,
 		sections: {
+			"hosted-ios": {
+				summary: "iOS on a named approved Mac: strict placement, private Metro, status and stop",
+				body: () => `IOS ON A HOSTING MAC
+
+If Stim is not installed globally, replace stim with npx stim.
+
+  stim settings set hosting.machines '["janics-mac-mini"]'
+  stim doctor --fix
+  # A person there approves: stim-server devices grant <id> --device-host
+  # Or runs stim-server setup on the worker with its client node, ticket and expiry.
+  stim doctor
+  stim ios --remote janics-mac-mini --device-type "iPhone 17 Pro" --runtime "iOS 27.0"
+  stim status --json
+  stim reload ios
+  stim stop
+
+The same setup serves macos --remote. Approval is separate from build, read
+and phone control. Set ios.remote to the machine name for a workspace default;
+no flag or setting runs here. eas and proxy keep their remote backend meanings.
+auto is accepted but refuses with STIM_BAD_ARG until automatic placement ships.
+Android --remote <machine> refuses with STIM_BAD_ARG: Android on a paired Mac
+is not available yet.
+
+A named Mac is strict: STIM_HOSTING_REFUSED names its reason; nothing boots
+here or elsewhere. --device cannot use a hosting Mac, and --simulator-app
+refuses. The host boots headless and ignores this Mac's iosSimulatorApp setting.
+--slot, --device-type and --runtime select the hosted simulator; --scheme,
+--configuration and --eas-profile select the app as usual. The build targets
+the offered simulator architecture, not this Mac's. --build-machine remains
+independent and selects a compatible build worker for a Debug cache miss.
+
+Stim builds or fetches before reserving, records the session immediately, then
+uploads the app on every run. Debug keeps Metro here; its supervisor owns a
+private gateway bound to this Mac's Tailscale address, pinned to the host peer
+and protected by a per-session secret. The host exposes only a loopback bridge.
+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.
+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.
+
+A rerun on the same named Mac reattaches and delivers a new app attempt. A
+stopped or missing session is replaced; an unreachable or unknown owner refuses
+replacement. Switching between this Mac and a hosting Mac, or to a different
+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
+status. Ready is normal; stopped has a rerun hint; unknown or unreachable is
+unverified. A host server restart stops its sessions.
+
+stop and worktree remove wait for the host to stop, delete exactly its owned
+simulator without parking, close the gateway 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
+and fails cleanup: rerun stim stop when it answers. Missing or unapproved local
+credentials require stim doctor to restore access before retrying stop. An
+unreadable machine or session remains recorded; status warns and stop names the
+workspace-state key to inspect. Only that slot's ios run refuses; restore its
+recorded machine and session from the host, then run stim stop for that slot.
+Reload returns a JSON error with that remedy when no other app can reload;
+logs remain readable. Unknown selection or agent metadata is normalized
+without discarding the owner. devices.idleShutdownMinutes
+does not stop a hosted simulator in this phase; its recorded session keeps Metro
+from idle stopping. Reruns upload only missing manifest and file digests from a
+session-scoped store; the host verifies bytes before reuse. When the iOS build
+ran on the hosting Mac's pinned node, it takes matching files from that build.
+A refused or timed-out handoff falls back to upload, retrying a still-busy host
+for at most one minute.
+
+stim logs and stim logs --errors pull native device records from bounded host
+queries. Concurrent followers share a collection, throttled per session, without
+blocking app delivery, viewing or control. Stop limits each log drain to 30 seconds with
+progress on stderr and a no-progress guard. The host collects a bounded final
+tail before deletion, including on revocation or server close; stop copies it
+back afterwards. If the final collection drops a backlog interval and eventually
+succeeds, a device warning record names that interval. A damaged collection checkpoint is ignored and
+rebuilt; it never blocks reading collected records. The client waits up to
+180 seconds for stop. The final collection and worker termination paths fit within
+that wait; an in-flight handoff copy and closing Metro or view transports are
+outside those worker bounds.
+Collected records remain in the session home after deletion;
+app blobs and materialized bundles are removed. Native queries read persisted
+entries, overlap by five seconds and de-duplicate; info-level or later-persisted
+entries may be unavailable. JavaScript logs arrive through Metro.
+The host advertises hosted-ios-data for iOS handoff and native logs. An older
+host gets an update note, uses uploads and shows logs already copied here.
+
+AGENT CONTROL
+
+On the hosting Mac, set hosting.agentDriver to agent-device. Both Macs need
+agent-device 0.21.20 or later (the policy and remote-config contract). The host
+starts one loopback daemon per installed iOS session under a child-aware
+ownership claim. Its daemon policy pins exactly that simulator UDID and denies
+shutdown. Stop, close, revocation, reinstall and graceful server close end its
+daemon and grant. A server crash can leave detached daemon processes and claims;
+restart alone does not prove they stopped. A daemon exit restarts only that
+session and rotates its grant; rerun stim ios to reattach and refresh the config.
+An unresolved proxy or daemon retains its claim and blocks reinstall and native
+teardown; clear a named claim only after proving its owner and child are gone.
+
+The client writes a separate 0600 remote-config file for each workspace slot.
+Status prints agent: <command>; ios.host.agent in --json carries driver,
+remoteConfig and command, never the token. Use the returned file:
+
+  agent-device open <bundleId> --remote-config <file>
+  agent-device snapshot --remote-config <file>
+  agent-device click <ref> --remote-config <file>
+  agent-device screenshot --remote-config <file>
+
+The command shape is agent-device <command> --remote-config <file>. Open leases
+the simulator automatically with ios-instance and the proxy provider, scoped
+to this session's tenant. Close releases it; Stim still owns the simulator.
+The config names daemonBaseUrl, daemonAuthToken, tenant, sessionIsolation,
+runId, clientId, deviceKey, leaseBackend, leaseProvider and platform; it carries
+no preallocated leaseId. stim stop closes the matching agent-device connection
+and removes that slot's config after the host confirms stop or revocation.
+The host stops the session daemon and identity-checked agent-device runners
+targeting its exact simulator UDID before deleting the simulator, even without close.
+
+Allowed: devices, open, close, snapshot, diff, wait, find, get, is, click, fill,
+press, type, focus, scroll, screenshot, longpress, swipe, back, home, orientation,
+appstate, alert and batch. These inspect or interact with the simulator and
+installed apps. devices lists only the session's simulator, filtered by the
+daemon policy. Its device claims are session-local and record / as the workspace;
+a host-side agent-device using the same simulator is not visible to the hosted daemon.
+Client device selectors are stripped and requests are pinned to iOS and that
+UDID; an explicitly named foreign UDID is refused. Selecting another device,
+boot/shutdown/erase, installs, uninstall, uploads, push, record, logs, network,
+perf, trace, clipboard and settings are refused. Stim installs; the agent cannot
+enumerate other host devices or write host files. Ambient client fields (cwd,
+stateDir, config and remoteConfig) are stripped, including inside batch steps.
+Host paths and launch inputs (--out, baseline, launchConsole, developerDir,
+installSource and similar fields) are refused, including inside batch steps.
+Only agent-device's generated screenshot temp artifact is accepted and returned
+to the client; arbitrary host screenshot destinations are refused. Runtime
+hints are dropped and only reporting/artifact metadata passes through.
+
+If hosting.agentDriver is none, the driver cannot enforce its policy, or the
+host does not advertise hosted-ios-agent, agent reports
+{ driver: 'none', setting: 'hosting.agentDriver' }. Update the host and check
+its setting and agent-device installation. No other simulator becomes reachable.
+Client hello carries only name and version, not features, so the host cannot gate
+daemon startup or grant issuance on client support. The client checks the host's
+hosted-ios-agent feature before using a grant.
+
+Stim Desktop and the phone app view and control the simulator through this
+Mac's stim-server relay, with an "on <machine>" label. Turn on Serve to phones
+in Desktop; pair the phone with this Mac, not the hosting Mac. frames.subscribe
+and control.begin address workspace, platform ios and slot, including named
+slots. The relay shares one authenticated host connection with hosted macOS
+viewers. Stopped sessions show a rerun remedy; unavailable hosts report why
+frames cannot arrive. Replay, duoFrame and physical targets are refused for
+hosted subscriptions. Desktop hides local Simulator.app, rotation, hardware
+buttons and simulator options; touch and text use the relay. The phone can also
+send the host's supported button, rotation and posture inputs.`
+			},
 			eas: {
 				summary: "download a matching EAS development build; explicit profile, costs, cache and miss remedies",
 				body: () => `EAS DEVELOPMENT BUILDS
@@ -4639,6 +5000,7 @@ result as proof instead of requiring an unrelated screenshot.`
   The labels are a closed set, and nothing else is ever printed in that
   column:
 
+    agent-device
     branch      budget      build       cache       caches      carry
     checkout    daemons     deps        device
     devices     error       failed      findings    fingerprint gems
@@ -5524,7 +5886,7 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
 				summary: "every flag per command, Android variants and flavors, the per-run simulator model, runtime and system image",
 				body: () => `THE OPTION SURFACE, IN FULL
   start           --json --wait <seconds> --remote --reset-cache
-  ios             --build-machine <auto|local|name> --slot <name> --json --plan --no-metro-check --no-build-cache --scheme <name> --configuration <name> --device-type <name> --runtime <version> --simulator-app <xcode|siniulator|stim-desktop> --device [udid] --wait <seconds> --no-wait --remote <proxy|eas>
+  ios             --build-machine <auto|local|name> --slot <name> --json --plan --no-metro-check --no-build-cache --scheme <name> --configuration <name> --device-type <name> --runtime <version> --simulator-app <xcode|siniulator|stim-desktop> --device [udid] --wait <seconds> --no-wait --remote <eas|proxy|auto|machine>
   android         --build-machine <auto|local|name> --slot <name> --json --plan --no-metro-check --no-build-cache --variant <name> --system-image <id> --device-profile <id> --device [serial] --wait <seconds> --no-wait --remote <proxy|eas>
   reload          [ios|android] --json
   device          lock <ios|android> [id] --slot <name> --for <duration> --wait <seconds> --json;
@@ -5559,7 +5921,7 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   and prints what it waits for. \`stop --slot\` interrupts a build only for
   its own slot or when it stops the workspace's only device (see STOP DURING
   A BUILD).
-  Named slots support local devices; remote sessions use the default slot.
+  Named slots support local devices and hosted iOS simulators; eas/proxy sessions use the default slot.
   Names use 1-64 letters, digits, underscores or hyphens, starting with a letter
   or digit. Reserved object-property names and web are refused.
 
@@ -5765,7 +6127,7 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   \`--device-type "iPhone 8" --runtime 26.5\` that each half would pass alone.
   \`--runtime\` takes a version (\`26.5\`) or a runtime's full name
   (\`iOS 26.5\`), exactly; no prefix or suffix matches. On a remote run
-  (\`--remote\` or the ios.remote setting) \`--runtime\` refuses with
+  (eas/proxy via \`--remote\` or ios.remote) \`--runtime\` refuses with
   STIM_BAD_ARG, because the remote backend picks the iOS version. So does
   \`--device-type\` on the proxy backend. The eas backend honors
   \`--device-type\`: Stim passes it to \`eas simulator:start --device\`,
@@ -5774,7 +6136,9 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   recorded EAS session still running another model refuses with
   STIM_REMOTE_DEVICE_MISMATCH instead of being reused; one that already
   ended is replaced on the requested model. The ios.deviceType and
-  ios.runtime settings do not refuse on a remote run; it ignores them.
+  ios.runtime settings do not refuse on an eas/proxy run; it ignores them.
+  A named hosting Mac uses both selectors and its installed choices instead;
+  an unavailable choice is STIM_HOSTING_REFUSED. See hosted-ios.
   \`android --system-image\` and \`--device-profile\` refuse with
   STIM_BAD_ARG on every remote run (\`--remote\` or the android.remote
   setting), and a remote run ignores android.systemImage and
@@ -6229,8 +6593,56 @@ wipe state to upgrade: it records ownership needed for safe teardown. Use the
 same slot-aware CLI for all commands while named assignments exist; older
 versions cannot reliably manage their assignments.
 
+ARCHIVE
+
+Linked-worktree removal and gc dead-project pruning keep history under
+$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
+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.
+
+  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
+
+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.
+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.
+The run claim serializes passes with gc --delete; gc refuses a held claim
+with the holder and recovery guidance instead of waiting.
+
 CLEANUP AND DISK
 
+worktree remove stops the agent-device daemon when the workspace's
+agent-device/daemon.json exists, then removes its state directory with the
+workspace. If agent-device is missing or the stop fails, it keeps the directory
+and reports the retry command: agent-device daemon stop --state-dir <dir> --clean.
+A daemon.json whose process is gone is stale and does not block removal.
+gc --delete of a finished worktree does the same.
+stop closes owned-device sessions in that directory without deleting it.
+See stim guide logs for AGENT_DEVICE_STATE_DIR examples.
+
 WHAT RECLAIMS AN OWNED DEVICE
   stim worktree remove    parks eligible owned simulators and emulators
                             (\`guide lifecycle pool\`); deletes them when
@@ -6300,9 +6712,77 @@ written by a newer Stim -- costs one dim line on stderr and is otherwise left
 alone; only the next \`ios\` or \`android\` run moves an unparseable one aside
 to stats.json.corrupt-<unix ms> and starts a new one.`,
 		sections: {
+			archive: {
+				summary: "retained workspace history and explicit archive cleanup",
+				body: () => `ARCHIVE
+  Linked-worktree removal and gc pruning a registered root that is gone keep
+  state, ended agents, the error index, logs, closed recording segments and
+  workspace-local agent-device sessions under $STIM_HOME/archive.
+  Build outputs and open recording segments are deleted with the workspace.
+  Archives have no checkout, devices, ports or running processes. A recreated
+  path starts fresh; status links its earlier archives with replacedBy.
+  Paired clients with read can select archived[].id with archive instead of
+  workspace for server log queries and replay. Archived log subscriptions send
+  retained records, then logs-ended. Archived frame subscriptions need at and
+  cannot be physical or go live. Replay ranges report recording disabled.
+  Reads stay on this Mac.
+  An updated server is required; older servers refuse with bad-request when
+  workspace is omitted. There is no CLI archive log flag.
+  archive.enabled defaults true and accepts every settings layer. STIM_HOME
+  disables archives unless STIM_ARCHIVE_ENABLED is set. Empty stubs and orphaned
+  workspace directories are not archived. A failure prints one stderr line
+  beginning "could not archive:" and removal continues with empty stdout.
+
+  Retention runs on every worktree removal, archived or not, once an archive
+  exists. It deletes records past their age or count limit first, then expires
+  recordings, agent actions and logs by age from removedAt; trims per-workspace
+  logs (oldest rotated generations, then build logs, then oldest other files);
+  and removes the largest kind of the oldest archive while over total caps.
+  Archives with expired artifacts keep their record until the record limit. recording.enabled false at machine scope deletes archived
+  recordings on the next retention pass. Sizes are binary GB/MB; 0 keeps none.
+  See stim guide settings for the nine archive.* keys and overrides.
+
+  stim gc --cache archived                     list ids, kinds, bytes and expiry
+  stim gc --delete --cache archived             delete every archive
+  stim gc --delete --cache archived --older-than 14
+                                                only removed at least 14 days ago
+  stim gc --delete --cache archived:<id>         delete one; ignores --older-than
+  stim gc --delete --cache archived-logs        delete logs, keep records
+  stim gc --delete --cache archived-recordings  delete recordings, keep records
+  stim gc --delete --cache archived-agent       delete agent actions, keep records
+  Per-kind selectors also accept --older-than, measured from removedAt.
+  Normal gc, --cache all, --worktrees and unscoped --older-than exclude archives.
+  Archive scopes report abandoned staging directories and delete only those
+  with no live or unresolved claim. An unresolved claim names its removal command.
+
+  Directories are 0700 and files 0600. No redaction is applied; logs and agent
+  actions can contain secrets. Use archive.enabled false for a sensitive repo.
+  Archived logs and replay are not exposed through CLI or app readers yet.`
+			},
 			gc: {
 				summary: "what gc and worktree remove delete, keep and refuse: orphans, stale records, locks, leases, EAS sessions",
-				body: () => `LINKED WORKTREES
+				body: () => `AGENT-DEVICE (REPORT ONLY)
+Unscoped gc reports agent-device runner builds by platform and entry, last use,
+agent-device and Xcode versions, sessions, logs, other state, workspace state
+and hosted driver state. Stim never selects this state as a cache.
+Stim never trims or deletes the shared runner builds, sessions, logs and other
+state or the hosted driver dir; a workspace's own agent-device dir goes only with its workspace.
+A live owner or runner lease marks an entry in use. A lock marks it in use only
+when its owner is live or unknown. Unreadable lock owners and unreadable or unknown
+leases conservatively mark entries in use. Dead lock owners and leases do not.
+Use agent-device's own tooling or remove directories yourself to clear unused
+state. --cache scopes omit this report, including --cache all.
+
+SWIFTPM CACHE (REPORT ONLY)
+Unscoped gc also reports the user-level SwiftPM cache after agent-device:
+~/Library/Caches/org.swift.swiftpm on macOS, or org.swift.swiftpm under
+XDG_CACHE_HOME (default ~/.cache) elsewhere. It is shared by every SwiftPM
+build on this machine. Stim reports it and never deletes it. It is never in
+caches, never changes actionable, and --delete and --older-than never select
+it. Any --cache scope, including all, omits measurement and reports
+sections.swiftpmCache: null. Only stats and unscoped gc measure it.
+
+LINKED WORKTREES
   \`stim worktree remove\` works with any linked worktree, warmed or not.
   Git registration identifies the worktree; a Stim registry entry is not
   required. Before it reclaims anything, the command refuses a worktree git
@@ -6900,7 +7380,7 @@ Resolution order, first match wins:
   4. machine         ~/.stim/config.json, top-level optimizations,
                      ios.deviceType, ios.runtime, android.systemImage,
                      android.deviceProfile and devices.idleShutdownMinutes
-                     only
+                     and archive.enabled
   5. Stim default
 An environment override, where a setting has one, wins over every layer.
 
@@ -6926,6 +7406,12 @@ An app's .stim.json can contain:
     "android": { "variant": "productionDebug" }
   }
 
+ARCHIVE SETTINGS
+${SETTINGS.filter((setting) => setting.key.startsWith("archive.")).map((setting) => `  ${setting.key}: ${setting.description}; default ${setting.default}; layers ${setting.scopes.join(", ")}; ${setting.env}`).join("\n")}
+Sizes use binary GB/MB. Archive ages and caps accept 0 to keep none.
+STIM_HOME makes archive.enabled false unless STIM_ARCHIVE_ENABLED is set.
+See stim guide cleanup archive for retention and explicit deletion.
+
 KEYS STIM READS
   ios.deviceType        e.g. "iPhone 17 Pro" -- the simulator model this
                         workspace's owned sim is created as, spelled exactly as
@@ -6952,9 +7438,10 @@ KEYS STIM READS
                         embedded JS, no Metro, cache keyed -release-sim, and
                         a JS-bundle swap on cache hits. The \`--configuration\`
                         flag overrides this per invocation. Unset means Debug.
-  ios.remote            "proxy" or "eas" to use that remote backend, the same
-                        as passing \`--remote proxy\` or \`--remote eas\`. The
-                        build still runs here; only the device is elsewhere.
+  ios.remote            "proxy", "eas", or a named approved Mac from
+                        hosting.machines, with the same meaning as --remote.
+                        "auto" is accepted but refuses until automatic placement
+                        ships. Unset runs here. See lifecycle hosted-ios.
   ios.simslimProfile    a SimSlim JSON profile under the app directory,
                         at most 64 KiB. Install the
                         external tool once with
@@ -7235,7 +7722,7 @@ ${ANDROID_AVD_CONFIG_HELP.map((line) => `                          ${line}`).joi
                         them from the environment or the machine layers.
 
 Each setting takes its documented type: string, array of strings, number,
-boolean, or object. ios.remote, android.remote, metro.tunnel, web.viewport,
+boolean, or object. android.remote, metro.tunnel, web.viewport,
 optimizations.android.compilerCache and optimizations.android.pch take only
 their listed choices. A value of the wrong
 type or outside those choices is refused by name on every command that resolves
@@ -7291,6 +7778,18 @@ 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.
 
+AUTOMATIC MAINTENANCE IS MACHINE-LEVEL
+Report-only in this release: it measures and plans, and deletes or stops nothing.
+STIM_HOME and CI make the mode off unless STIM_MAINTENANCE is set.
+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}`}
+    ${setting.description}`).join("\n")}
+
+Maintenance uses the sysctl pressure level on macOS, with no memory signal
+when sysctl fails. os.freemem() and maintenance.minAvailableMemoryGb apply
+only on other platforms.
+
 THE IOS SIMULATOR APP IS MACHINE-LEVEL
 Top-level \`iosSimulatorApp\` in ~/.stim/config.json selects the macOS app that
 displays Stim's owned local iOS simulator after boot. It is not a project
@@ -7386,6 +7885,17 @@ test suites and the end-to-end harness use one -- and a scoped config must not
 leave simulators on the machine it cannot account for. A redirected home that
 wants a pool says so with the variable.
 
+DESKTOP ACCESS TICKETS
+Stim Desktop's Add wizard sets STIM_ACCESS_TICKET for one \`doctor --fix\`
+run. Agents never set it, never run \`stim-server setup\`, never edit
+\`offload.*\` or \`hosting.*\` for the user, and never approve requests.
+Stim sends the ticket (43 base64url characters) only in build and device-host access
+requests and stores only its SHA-256 ticketHash. With --fix, a still-pending
+request is replaced when its ticketHash is missing or differs from the current
+ticket; matching hashes and approved credentials are preserved.
+Approved doctor entries under buildMachines and deviceHosts include host
+{ name, screenRecording, accessibility } when the worker reports it.
+
 HOSTING MACHINES ARE MACHINE-LEVEL
 \`hosting.machines\` names Macs that may host owned simulator sessions,
 by MagicDNS name with an optional serve port (default 7443). Name each node
@@ -7396,7 +7906,15 @@ and port once. This is separate from build offloading:
 
 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\`.
-Hosting grants include no read, control or build capability.
+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
+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
+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.
 $STIM_HOME/device-host-machines.json stores a private token and pinned tailnet
 node. Doctor never prints the token; it reports each machine under deviceHosts
 in JSON. Stim sends tokens only to the pinned node's own tailnet address,
@@ -7415,13 +7933,15 @@ Access (Accessibility on macOS 26 and earlier) for Stim Host, the app
 \`stim-server service install\` runs the server under.
 
 On a hosting Mac, \`hosting.agentDriver\` names the tool it starts so a
-client's coding agent can drive the macOS apps it hosts for that client.
-The default, \`none\`, starts nothing. \`agent-device\` starts its
-daemon only when that agent-device can lease a single macOS app (its
+client's coding agent can drive the macOS apps and iOS simulators it hosts for that client.
+The default, \`none\`, starts nothing. For macOS, \`agent-device\` starts its
+shared daemon only when that agent-device can lease a single app (its
 \`macos-app\` lease backend); otherwise agent control reports \`none\` with a
 notice, and no client is handed the Mac's desktop. STIM_AGENT_DEVICE_BIN in
 stim-server's environment names an agent-device binary to use instead of
-~/.local/bin/agent-device. \`doctor\` on that Mac notes a hosted macOS app that runs while
+~/.local/bin/agent-device. Hosted iOS uses one daemon per simulator, pinned by
+its UDID policy; both Macs need agent-device 0.21.20 or later. See guide lifecycle
+hosted-ios. \`doctor\` on that Mac notes an installed hosted app that runs while
 the setting is \`none\`.
 
 BUILD MACHINES ARE MACHINE-LEVEL
@@ -7436,6 +7956,9 @@ route (default 7443):
 \`doctor --fix\`, run in any app directory, asks each named Mac for build access and pins its tailnet
 node in $STIM_HOME/build-machines.json. A person approves the request on that
 Mac with \`stim-server devices grant <id> --build\`; doctor prints the id.
+A person can instead run \`stim-server setup\` on the worker with a node,
+ticket and expiry, under the approval rule above. Build never includes read
+or control.
 Stim connects to a named Mac only while its name still belongs to the pinned
 node and never sends the token to another node. \`doctor\` reports each
 machine's pairing state and, for an approved machine, asks it for one build
@@ -7470,7 +7993,8 @@ Prebuild and pod install still run on this Mac before a named offload. A refusal
 starts no local xcodebuild, Gradle or SwiftPM compile.
 Run stim doctor --fix to ask for build access if not paired. A person on the
 worker finds the id with stim-server devices and approves it with
-stim-server devices grant <id> --build. Check stim settings get offload.machines,
+stim-server devices grant <id> --build, or runs stim-server setup there with
+the client node, ticket and expiry. Check stim settings get offload.machines,
 or rerun with --build-machine auto or --build-machine local. Ctrl-C cancels
 the remote build without a local xcodebuild, Gradle or SwiftPM compile.
 
@@ -7499,14 +8023,16 @@ the ones it offloaded.
 counts as saturated, both here and on a build machine.
 
 STIM_OFFLOAD_MODE overrides it for one command. Device, Release and
-\`--remote\` builds, Android builds with the Apple Clang CAS compiler cache,
-and iOS/Android runs with the build cache off, always build here.
+\`--remote eas|proxy\` builds, Android builds with the Apple Clang CAS compiler cache,
+and iOS/Android runs with the build cache off, always build here. Hosted iOS
+Debug builds can use a separate --build-machine, targeting the hosting Mac's
+architecture and runtime.
 macOS uses matching Xcode and macOS SDK, with a per-client SwiftPM dependency
 cache on the worker. It skips JavaScript dependencies, prebuild and pods; see
 stim guide macos. macOS artifacts are not cached.
 An offloaded iOS/Android build first runs prebuild (and \`pod install\` for iOS) here,
 then asks every paired machine what it can build. It takes one whose Stim
-build and CPU match this Mac exactly, with enough disk, that does not decline,
+build matches this Mac and CPU matches the target simulator, with enough disk, that does not decline,
 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.
@@ -7575,12 +8101,16 @@ 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
 sessions to finish, restarts the job, and switches back when the new server
-does not answer within 90 seconds; \`stim-server service rollback\` returns
+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
 there can ask for the same update over its tailnet connection: an npm release
 always, and its own packed build only while \`server.acceptClientBuilds\` is
 true on that machine (default false).
-Installation alone does not prove readiness; check \`stim-server service status\`
+Replacing a loaded service waits up to 45 seconds for its existing listeners to
+release the port. Uninstall does not wait for the port. If stopping the old job
+or starting the new one fails, install restores the previous plist and attempts
+to restart a previously loaded LaunchAgent; if it cannot, it prints the
+launchctl bootout/bootstrap remedy. A running LaunchAgent does not prove readiness; check \`stim-server service status\`
 and its reported log. The server listens before it touches the Stim home; a
 read-only child process reads the Stim home, server and recording directories,
 and until it returns \`/health\` answers 503 with \`startup.state\` pending.
@@ -8081,6 +8611,9 @@ a new window is not captured.`
 
 If Stim is not installed globally, replace stim with npx stim.
 
+ios --remote <machine> shares hosting.machines and its separate device-host
+approval. Read guide lifecycle hosted-ios for simulator placement and Metro.
+
 Run from the directory containing Package.swift. This prototype builds one
 explicit executable product in Debug, creates an isolated development app,
 and launches it. It does not use package scripts, Metro, simulators, Xcode
@@ -8295,7 +8828,8 @@ ON ANOTHER MAC
 stim macos --remote <machine> builds the Debug app on this Mac and runs it on an
 approved hosting Mac over the tailnet, without SSH. The machine must be listed
 in hosting.machines and approved: stim doctor --fix asks it, a person on that
-Mac runs stim-server devices grant <id> --device-host, and stim doctor then
+Mac runs stim-server devices grant <id> --device-host or stim-server setup
+with that client node, ticket and expiry (guide settings), and stim doctor then
 records the approval. Stim connects only to the machine's pinned tailnet node.
 A refusal or an unreachable host fails the command; it never launches here
 instead.
@@ -8317,7 +8851,8 @@ valid NDJSON. The host's unified log is not collected: os.Logger output that is
 not written to stderr does not appear.
 
 Phones and Stim Desktop view and control the hosted app through this Mac's
-stim-server, which relays to the host. The phone sends clicks, scrolls,
+stim-server, which relays to the host. Hosted iOS simulator tiles use the same
+relay and show on <machine>; see guide lifecycle hosted-ios. The phone sends clicks, scrolls,
 text and keys; Stim Desktop's Control sends clicks, drags and typed text.
 
   stim macos --remote mini          # build here, deliver, launch on mini