stim 1.31.0 → 1.33.0

package/dist/{guide-Civo5-zV.mjs → guide-CmZB0GtP.mjs}

@@ -1,8 +1,8 @@
-import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-C6UTYW2K.mjs";
-import { i as findProjectRoot$1 } from "./project-DCLkDM8C.mjs";
-import { h as RECENT_LAUNCH_MS } from "./eas-session-ledger-aFBLTZr2.mjs";
-import { o as guideStatus, t as WATCHMAN_NESTED_WORKTREES } from "./doctor-watchman-DJY550yz.mjs";
-import "./status-watch-BwG4lJ1q.mjs";
+import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-B5IBDfTx.mjs";
+import { i as findProjectRoot$1 } from "./project-DWEXiBA9.mjs";
+import { h as RECENT_LAUNCH_MS } from "./eas-session-ledger-Bspy-VJQ.mjs";
+import { o as guideStatus, t as WATCHMAN_NESTED_WORKTREES } from "./doctor-watchman-CDhpC3Oh.mjs";
+import "./status-watch-D8s823CZ.mjs";
 import { SETTINGS, SETTINGS_SCHEMA_URL, TUTORIAL_VERSION } from "@stim-cli/core/state";
 import chalk from "chalk";
 //#region src/guide/agent.ts
@@ -220,6 +220,9 @@ RULES DURING THE LOOP
   survive the run. Trust the exact device, app, Metro, and launch facts in the
   final summary. Use the full reported device ID. Never assume a simulator
   named booted belongs to this workspace.
+- With no matching Android system image, android downloads one (about 2 GB)
+  with sdkmanager unless android.installImages is never. It never accepts SDK
+  licenses: give the user the refusal's \`sdkmanager --licenses\` command.
 - After each ios or android run, give the user one compact result: exact device,
   app id, launch state, cache result, total duration, and whether stim logs
   --errors passed. Include a remedy only when action remains. Do not repeat the
@@ -291,7 +294,8 @@ replacement runs while one is queued. See \`stim guide lifecycle concurrency\`.
 After maintenance.idleStopHours (default 6) with no Stim command, native run,
 Metro bundle or HMR request, agent-device command or live view, automatic
 maintenance stops the workspace as stim stop does. Device and app logs do not
-count. After a long pause, run stim ios or android again before driving the
+count. A device hosted on a remote Mac stops with it, and stim-server stops a hosted
+session whose client has been gone that long. After a long pause, run stim ios or android again before driving the
 app; see \`stim guide cleanup\`.
 
 Treat a refusal as an ownership or state mismatch: read its code and remedy.
@@ -1592,9 +1596,11 @@ RULES
                     it; command is the \`xcrun simctl runtime delete\`
                     line for a deletable runtime, else null. Stim never
                     runs it
-    systemImages  { package, directory, avdCount, command }  installed
-                    Android system images; avdCount is the AVDs whose
-                    image.sysdir.1 names it; command is the
+    systemImages  { package, directory, avdCount, stimInstalled,
+                    command }  installed Android system images; avdCount
+                    is the AVDs whose image.sysdir.1 names it;
+                    stimInstalled is true when this Stim home installed it
+                    (android.installImages); command is the
                     \`sdkmanager --uninstall\` line. Stim never runs it
     notices       why a listing is missing or partial, such as simctl
                     timing out or an AVD or system image folder Stim
@@ -1921,6 +1927,12 @@ RULES
               device screens for replay, from recording.enabled
   hidden      true when workspace.hidden is set; absent otherwise. The next
               command that uses the workspace clears it.
+  pathMissing true when the workspace folder no longer exists on a mounted
+              volume, such as after git worktree remove or rm -rf; absent
+              otherwise, and for a folder on a volume that is not mounted.
+              phase is then never warming or ready. status only reports it:
+              the entry stays registered until stim gc --delete or
+              stim worktree remove <path> removes it.
 
   Each environment also carries stage, where the workspace is as Stim
   Desktop and the phone app show it: { kind, since, platform, closedApps }.
@@ -2846,7 +2858,7 @@ HOSTED IOS METRO
   Macs; a running Metro or a pin on a port the host uses refuses the run before
   the build. metro.tunnel and metro.publicUrl are ignored. Supervisor restart
   reopens the recorded links; stop or a stopped hosted session closes them. A recorded
-  hosted session prevents Metro idle stop. Release runs skip the bridge.
+  hosted session prevents Metro idle stop; maintenance.idleStopHours still stops the workspace and its hosted session (guide cleanup). Release runs skip the bridge.
   Hosted Debug runs require a supervisor and a stim-server that support these
   links before reservation. --no-metro-check refuses; restart a missing or older supervisor
   with stim stop; stim start.
@@ -3875,7 +3887,9 @@ Branch on the code, never on the message.`,
   tailscale ping. Check stim-server and Tailscale there,
   then run stim doctor. Correct --device-type / --runtime for iOS or
   --system-image / --device-profile for Android when the offer names
-  an unavailable choice. A session that exists stays recorded even if delivery
+  an unavailable choice. A host that would install a missing Android image
+  but cannot (android.installImages never there, unaccepted licenses, no
+  cmdline-tools, low disk) declines with the command to run on that host. A session that exists stays recorded even if delivery
   fails: retry stim ios|android --remote <machine>, or run stim stop to reconcile it.
   An Expo dev client whose running or pinned Metro port is in use on the host
   refuses before the build: run stim stop, then stim ios --remote <machine>
@@ -4631,6 +4645,12 @@ so a Debug run on one is wired to a LAN origin instead of localhost.`,
   Mode off, over a cable or over Wi-Fi alike. Hardware is never created or
   booted, so there is nothing to retry into existence: fix the cable, the
   trust prompt, or Developer Mode.
+  On Android it also means no system image matched and Stim could not install
+  one: android.installImages is never, the SDK has no cmdline-tools/latest,
+  the SDK licenses are not accepted (Stim never accepts them; run the
+  \`sdkmanager --licenses\` line the remedy prints), the SDK volume has under
+  8 GB free, or sdkmanager failed. The remedy names the exact sdkmanager
+  command. Nothing was downloaded or created.
   Otherwise the owned simulator/emulator could not be created or could not
   reach a booted state. \`stim doctor\` checks the toolchain; \`stim status\` says what
   Stim thinks it owns. Re-running the command creates a fresh owned device
@@ -5673,6 +5693,40 @@ not on any remote"  (worktree remove)
 };
 //#endregion
 //#region src/guide/lifecycle.ts
+const HOSTED_RECORDING = (noun) => `\
+agent-device record start [path] --remote-config <file> records the ${noun};
+record stop downloads the video to path, or ./recording-<time>.mp4, on this
+machine. The host writes it only in a private directory for the session in its
+temporary directory and deletes the files after the download, on stim stop or session teardown and
+when its daemon restarts. One recording runs per session; a second start, a host output
+path, record inside batch and a record stop from another agent-device session
+are refused. The host stops a recording after 10 minutes; a record stop within
+the next 15 minutes downloads it. A finished recording over 512 MiB is deleted
+instead. A host whose Stim predates hosted recording refuses
+record as a command outside its allowed list.`;
+const HOSTED_COMMANDS = (noun) => `\
+Allowed commands: devices, open, close, snapshot, diff, wait, find, get, is,
+click, fill, press, type, focus, scroll, screenshot, longpress, swipe, gesture,
+back, home, orientation, fold, appstate, alert, batch, record start and stop,
+action-button, app-switcher, hardware-button, keyboard, apps, capabilities,
+events, network, react-native, telephony and trigger-app-event. Guarded: push
+takes <app id> <inline JSON object>, never a payload file; perf allows only
+frames and memory sample; artifacts lists this session's artifacts and takes no
+provider session; settings refuses permission accessibility, screen-recording
+and input-monitoring, which are permissions of the hosting Mac. Each command
+takes only the flags and input fields Stim lists for it, so a flag a newer
+agent-device adds is refused until Stim allows it. Host paths and launch inputs
+are refused: open refuses --metro-host, --metro-port, --bundle-url,
+--launch-url, --launch-args, --launch-console, --surface and --save-script.
+Stim's Metro bridge already points the app at this machine's Metro; a client
+address would let the hosted app reach any service the hosting Mac can.
+These are refused, each with its reason in the error: install, reinstall,
+install-from-source and uninstall (Stim installs the app and tracks it), boot,
+shutdown and close --shutdown (use stim stop), logs (use stim logs), trace,
+audio, doctor, prepare, replay, test, clipboard (a ${noun} can share the
+clipboard of the hosting Mac), hover, viewport, tv-remote and agent-device's
+client-side commands. Both machines need agent-device 0.21.30 or later; an
+older host reports driver: none.`;
 const lifecycle = {
 	summary: "The full worktree -> start -> ios/android -> logs -> teardown flow, with sections for builds, devices and flags",
 	preamble: () => `ENVIRONMENT LIFECYCLE
@@ -6191,6 +6245,13 @@ Unreadable android.host blocks only its slot; restore its recorded machine and
 session from the host before stopping that slot.
 
 --system-image and --device-profile select installed choices on the host.
+When no image on the host matches and the host's android.installImages is
+auto, the offer names the image to install; stim-server installs it with its
+own ANDROID_HOME and sdkmanager before it creates the AVD, the client prints
+\`image  installing <package> on <mac>\` and waits for it like any other
+preparation. A host set to never, or one with unaccepted SDK licenses, no
+cmdline-tools or under 8 GB free refuses with STIM_HOSTING_REFUSED naming
+the command to run on the host.
 The build targets the offered ABI and --remote-build independently selects a
 compatible build worker. Stim builds before reserving, records the session as
 soon as it exists, then delivers one App.apk. The emulator boots headless;
@@ -6218,7 +6279,7 @@ Status adds android.host { machine, session, selected, agent, device: { name,
 systemImage, api }, state } per slot. The public name is the profile and API
 level, never the host serial or AVD name. ready, stopped and unverified are
 session probe states; a conflicting local emulator remains visible with a
-warning. A recorded placement keeps the workspace in use and blocks idle stop.
+warning. A recorded placement keeps the workspace in use and blocks the supervisor's idle stop and device reclaim; maintenance.idleStopHours still stops it once the host confirms the session (guide cleanup, IDLE STOP).
 
 stop and worktree remove wait for device-host.stop, park the host's eligible owned
 emulator within pool.androidParkedMax (delete otherwise), close the Metro links and clear placement. stop --json reports
@@ -6233,13 +6294,18 @@ arrive through local Metro.
 AGENT CONTROL
 
 Set hosting.agentDriver to agent-device on the hosting Mac. Both machines need
-agent-device 0.21.22 or later. The host advertises hosted-android-agent and
+agent-device 0.21.30 or later. The host advertises hosted-android-agent and
 starts one loopback daemon per installed Android session. Its policy allows
 only the exact ledger-owned emulator serial and denies device shutdown.
 The host verifies the policy digest and android-instance backend before granting
 control. An older host, missing binary or unsupported policy reports driver: none;
 the host's notice explains unavailable control.
 
+On a local: machine, daemonBaseUrl is http://127.0.0.1:<port> of this
+workspace's Metro supervisor, which carries each request to the host over its
+own authenticated device-host connection (host feature hosted-agent-link). It
+works for Debug runs while stim start runs; Release runs report driver: none.
+
 android.host.agent in stim status --json provides driver, remoteConfig and
 command, never its token. Each slot has a separate 0600 file under the workspace
 state directory at hosted-android/<slot>/agent-device-remote.json. Use that file:
@@ -6253,14 +6319,13 @@ The command shape is agent-device <command> --remote-config <file>. Open leases
 the emulator automatically with android-instance, the proxy provider and this
 session's tenant. devices is permitted for the client's open flow; inventory
 contains only this emulator. Never use its serial with a local agent-device.
-Allowed commands are 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. Stim installs; install, reinstall,
-uninstall, boot, shutdown, close --shutdown, record, logs, uploads and device-wide
-actions are refused. Other serials in commands, flags, inputs, nested batches or
-lease requests are refused. Ambient client paths and owner fields are stripped;
-the host pins platform, serial, tenant, runId, clientId, deviceKey and backend.
-Host paths and launch inputs are refused. Screenshots use only remote artifacts.
+${HOSTED_COMMANDS("emulator")}
+Uploads and other serials in commands, flags, inputs, nested batches or lease
+requests are refused. Ambient client paths and owner fields are stripped; the
+host pins platform, serial, tenant, runId, clientId, deviceKey and backend.
+Screenshots use only remote artifacts.
+
+${HOSTED_RECORDING("emulator")}
 
 Stop closes the matching agent-device connection and removes the slot file only
 once the host confirms stop or revocation. Reinstall, stop, revocation and server
@@ -6530,7 +6595,7 @@ 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 machines need
-agent-device 0.21.20 or later (the policy and remote-config contract). The host
+agent-device 0.21.30 or later (the policy, command list 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
@@ -6540,6 +6605,11 @@ 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.
 
+On a local: machine, daemonBaseUrl is http://127.0.0.1:<port> of this
+workspace's Metro supervisor, which carries each request to the host over its
+own authenticated device-host connection (host feature hosted-agent-link). It
+works for Debug runs while stim start runs; Release runs report driver: none.
+
 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:
@@ -6559,23 +6629,22 @@ 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;
+${HOSTED_COMMANDS("simulator")}
+These inspect, interact with or record 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,
+erase and uploads are refused. 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.
+hints are refused and only reporting/artifact metadata passes through.
+
+${HOSTED_RECORDING("simulator")}
 
 If hosting.agentDriver is none, the driver cannot enforce its policy, or the
 host does not advertise hosted-ios-agent, agent reports
@@ -6915,6 +6984,16 @@ result as proof instead of requiring an unrelated screenshot.`
   is never touched: \`Reclaimed the environment; the working tree stays (it
   is the source checkout).\`
 
+  A worktree deleted outside Stim stays registered. Pass its path to
+  \`worktree remove\`: when the folder is gone from a mounted volume, the
+  command drops the record of that path and of the projects registered under
+  it, with the same \`device\`, \`lease\` and \`workspace\` lines, ending with
+  \`Reclaimed the environment of the deleted folder (its folder is already
+  gone).\` A path on a volume that is not mounted, or one that cannot be
+  resolved, is kept and refused with the reason, since the folder may come
+  back. A missing path with no registered project says \`No such worktree\`.
+  \`stim status\` reports such a workspace as pathMissing.
+
   \`gc\` names each slow step on stderr as it starts, in every mode; its
   report stays on stdout, and with \`--json\` stdout carries only the payload:
 
@@ -7174,8 +7253,9 @@ PREDICTING THE NEXT BUILD (--plan)
   not answer, ios.remote or android.remote set to eas or proxy, or auto that
   would use an EAS Simulator now (remote.easFallback), refuses with
   STIM_BAD_ARG. Without --eas-profile an Android plan also
-  refuses the experimental compiler CAS with STIM_BAD_ARG, and refuses with
-  STIM_NO_DEVICE when no system image is installed.
+  refuses the experimental compiler CAS with STIM_BAD_ARG. With no system
+  image installed it keys on the image a run would install, and refuses with
+  STIM_NO_DEVICE when android.installImages is never.
 
 IOS SCHEME SELECTION
   Pass \`stim ios --scheme "App Staging"\` to select an exact shared Xcode
@@ -8209,7 +8289,14 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   A name that is not INSTALLED on this machine refuses with STIM_BAD_ARG
   before anything is created, and the message lists the installed names, so a
   wrong guess is one command, not a created simulator. A blank value is the
-  same refusal.
+  same refusal. The exception is an Android system image for this machine's
+  ABI while android.installImages is auto (the default): \`stim android\`
+  installs it with sdkmanager, printing an \`image\` line, then creates the
+  AVD from it. The same applies when no image is installed at all, with
+  system-images;android-36;google_apis;<host ABI>. See \`stim guide settings\`
+  for the license, disk and locking rules. \`stim doctor\` reports a missing
+  image as a note (android-system-image), and \`stim doctor --fix --platform
+  android\` installs it right away.
 
   What counts as installed for \`--device-type\` is what an installed RUNTIME
   can create, not what \`xcrun simctl list devicetypes\` prints: that table
@@ -8849,7 +8936,7 @@ status's maintenance block and the maintenance log.
 
 IDLE STOP: the idle check, and gc --delete unless maintenance.mode is off (its
 dry run lists them in the maintenance plan), stop a workspace whose dev server
-runs or whose owned simulator or emulator is booted once it has had no real
+runs, whose owned simulator or emulator is booted, or whose device is hosted on a remote Mac once it has had no real
 activity for maintenance.idleStopHours (default 6; 0 never; machine or project
 layers; STIM_MAINTENANCE_IDLE_STOP_HOURS overrides; fractions work). Six hours
 outlasts a lunch break, a meeting or an agent's pause between tasks, and still
@@ -8864,7 +8951,7 @@ only stays connected does not either. The stop is stim stop's: the dev
 server stops, the owned devices shut down through centralized teardown
 (never deleted), and the port is released; device leases stay. A build, a
 held native-run or metro-start lock, a build lock or slot, a running macOS
-app, a hosted or remote session, an unexpired device lease, a managed tunnel
+app, a remote (EAS) session, an unexpired device lease, a managed tunnel
 or remote lock, a running owned Chrome, a device driver other than
 agent-device, a live agent-device claim with no session activity to judge,
 device activity, an emulator list or an emulator's AVD name that cannot be read keeps
@@ -8877,7 +8964,21 @@ after stim stop, and the supervisor_stopped line in metro.ndjson names
 automatic maintenance and the idle time as the requester. The next start, ios or android starts it
 again. An owned emulator the activity check missed keeps the workspace while
 adb lists it, and so does any emulator adb lists without an AVD name, such as
-a stale offline entry that adb kill-server clears. A dev server that may still run after its supervisor
+a stale offline entry that adb kill-server clears. A workspace whose iOS, Android or macOS device is hosted on a remote Mac is
+stopped the same way once the host confirms the session is ready; stim stop's
+hosted path ends the session and the host parks or tears down the device. A host
+that does not answer, a session it cannot confirm (unknown, as after a worker
+crash) and a placement that cannot be read keep the workspace, and a live view of
+the hosted device is not seen here. On the host, stim-server stops a ready session
+whose client has had no connection, live stream or Metro link and sent no
+agent-device request for the host's own machine maintenance.idleStopHours (default 6; 0
+never; STIM_MAINTENANCE_IDLE_STOP_HOURS overrides), only while its maintenance.mode is on;
+a project value or maintenance.keep on the client does not reach it. Server downtime is not
+counted. It uses the stop a person uses, never touches a session whose journal state is
+preparing, stopping or unknown, or one with a native operation or a claim it cannot prove free
+(a session a crashed server left ready counts once its claim is proven free),
+and writes the reason to the server log and the session's idleStop journal field.
+The count is per client, not per session. A dev server that may still run after its supervisor
 exited is kept until stim stop ends it. So is a dev server whose requests Stim
 does not record: an Expo project before SDK 54, which cannot load Stim's Metro config
 adapter, or a dev server an older Stim started, until stim stop and stim start
@@ -9577,6 +9678,13 @@ ORPHANED WORKSPACE DIRECTORIES
   it. A directory with a missing or unparseable workspace.json, or a root on
   an unmounted volume, is reported under Skipped and never deleted.
 
+DELETED WORKTREES STILL REGISTERED
+  A worktree deleted outside Stim keeps its registry entry; \`stim status\`
+  marks it pathMissing. \`gc --delete\` prunes every such entry whose folder is
+  gone from a mounted volume. \`stim worktree remove <path>\` prunes one entry,
+  and the projects registered under that path, the same way. Both keep an
+  entry whose volume is not mounted, since the folder may come back.
+
 TMPDIR LEFTOVERS
   \`gc\` without --cache reports recognized entries directly in the user's TMPDIR
   under "TMPDIR leftovers", with their count, size and a remedy: Stim temp
@@ -10309,9 +10417,30 @@ KEYS STIM READS
                         from. Readable from the machine layer too, so one
                         machine can default every workspace to an image; a
                         project layer still wins. The \`--system-image\` flag
-                        overrides this per invocation, and an id this SDK has
-                        not installed is STIM_BAD_ARG with the installed ids
-                        printed, naming the layer the value came from.
+                        overrides this per invocation. An id this SDK has not
+                        installed is installed first (android.installImages);
+                        with installImages never, or an id for another ABI,
+                        it is STIM_BAD_ARG with the installed ids printed,
+                        naming the layer the value came from.
+  android.installImages auto (default) or never. With auto, when no installed
+                        system image matches the request, \`stim android\`
+                        installs the one android.systemImage or
+                        \`--system-image\` names, else
+                        system-images;android-36;google_apis;<host ABI>, with
+                        the SDK's own \`sdkmanager --install\` before it
+                        creates the owned AVD; a slot whose owned AVD
+                        finished a boot keeps it and installs nothing. It
+                        installs only images for
+                        this machine's ABI, never accepts an SDK license (an
+                        unaccepted one refuses and names \`sdkmanager
+                        --licenses\`), needs 8 GB free on the SDK volume and
+                        cmdline-tools/latest, and runs one install per SDK
+                        root and Stim home; a second run waits for it. never
+                        refuses with the \`sdkmanager --install\` line instead.
+                        For a hosted run the host's machine value decides,
+                        and stim-server installs into its own ANDROID_HOME.
+                        \`stim gc\` marks the images Stim installed
+                        (stimInstalled).
   android.deviceProfile e.g. "pixel_fold" -- the avdmanager hardware profile a
                         new owned AVD is created with, spelled exactly as
                         \`avdmanager list device -c\` prints it. Defaults to
@@ -10744,7 +10873,8 @@ STIM_HOME and CI make the mode off unless STIM_MAINTENANCE is set.
 maintenance.keep is a project setting: pin a workspace so a pass never clears
 its build outputs or removes its worktree.
 maintenance.idleStopHours takes machine or project layers, so one workspace can
-stop sooner, later or never.
+stop sooner, later or never. On a hosting Mac stim-server reads its machine value
+to stop a hosted session whose client has been gone that long.
 See \`guide cleanup\` for checks, plans and log paths.
 
 ${SETTINGS.filter((setting) => setting.key.startsWith("maintenance.") || /^caches\..*MaxGb$/.test(setting.key)).map((setting) => `  ${setting.key}  ${setting.env ?? "project setting"}  ${setting.default === void 0 ? "unset" : `default ${setting.default}`}
@@ -10941,7 +11071,10 @@ ticket, which is a credential: whoever spends it first, after setup stores it,
 gets the approval, and on a local network that takes only the ticket and a
 route to the worker, not tailnet membership. Agents show it only to the user.
 Offloaded builds and hosted Debug and
-Release runs work there; agent control of hosted apps needs a tailnet machine.
+Release runs work there. Agent control of hosted iOS and Android Debug runs
+goes through a loopback port of this workspace's Metro supervisor, which
+carries it over its own authenticated connection; Release runs and hosted macOS
+apps there report agent control as none.
 \`stim-server pair\` puts \`ws://<address>:<port>\` in the phone pairing code
 when Tailscale is not running and \`server.lanAddresses\` is set.
 
@@ -11047,9 +11180,8 @@ shared daemon only when that agent-device can lease a single app (its
 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. Hosted iOS uses one daemon per simulator, pinned by
-its UDID policy; both machines need agent-device 0.21.20 or later. Hosted Android
-uses one daemon per emulator, pinned by its serial policy, with agent-device
-0.21.22 or later on both machines. See guide lifecycle
+its UDID policy. Hosted Android uses one daemon per emulator, pinned by its
+serial policy. Both machines need agent-device 0.21.30 or later. See guide lifecycle
 hosted-ios. \`doctor\` on that Mac notes an installed hosted app that runs while
 the setting is \`none\`.
 
@@ -11078,10 +11210,15 @@ and no platform selection on a Mac, it also checks the macOS Xcode and SDK.
 A client with no Xcode and no simulator SDK, such as Linux or Windows, has no
 Xcode to match: the Mac's own Xcode, simulator SDK and CocoaPods are the
 build's toolchain, the client leaves pod install to it, and \`stim ios --remote
-<mac> --remote-build <mac>\` runs the app on that Mac's hosted simulator. If
-that pod install changes Podfile.lock or the Xcode project, the build fails
-with fingerprint-mismatch; run pod install once on a Mac and commit the
-result. A client with an Xcode still needs the same one.
+<mac> --remote-build <mac>\` runs the app on that Mac's hosted simulator. When
+that pod install, or a file it generates there, changes only fingerprint
+sources in the iOS project, the Mac builds and stores the app under its own
+fingerprint after pod install, and the client stores it under that key. The
+client's own fingerprint does not compute that key, so each run builds on the
+Mac again; a stale Podfile.lock is worth regenerating on a Mac and committing.
+Any other difference, such as the app config, fails with fingerprint-mismatch.
+A client with an Xcode still needs the same one, and there a worker pod install
+that changes the fingerprint fails with fingerprint-mismatch.
 Two machines build for each other when their Stim releases share a build
 compatibility version, which changes only when what a worker builds, how it
 builds, or the build messages change; their Stim builds can differ. A
@@ -11257,7 +11394,10 @@ 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
+one JDK). A client with no JDK sends no major, so the worker's default JDK is
+the build's JDK and doctor notes it; with no Android SDK either, \`stim android
+--remote <machine> --remote-build <machine>\` runs the app on that machine's
+hosted emulator. 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. A
 package the SDK lacks is a note, not a blocker, when its offer reports the SDK
@@ -12233,6 +12373,10 @@ backend. Reserved names are case-insensitive and trimmed; they refuse with
 STIM_BAD_ARG before state access or a connection. The device pool switches
 (remote.devicePoolDisabled) also apply to automatic macOS placement.
 
+A hosted app is not kept forever: the idle workspace stop ends its hosted session
+after maintenance.idleStopHours without activity, and stim-server stops a session
+whose client has been gone that long (guide cleanup, IDLE STOP).
+
 Logs: the host records the hosted app's stdout, stderr and exit like a local run.
 stim logs, including --errors, --json and --follow, asks the host over the same
 approved connection, copies the records it has not copied yet into the

package/dist/{hosted-android-CH1Sm4wo.mjs → hosted-android-ByG-ICuh.mjs}

@@ -1,7 +1,7 @@
-import { c as throwIfCancelled } from "./exec-aULwtNly.mjs";
-import { c as call, l as connectHost } from "./hosted-client-5ur3YpxY.mjs";
-import { i as requestHostedMetro } from "./metro-request-RDhyx85c.mjs";
-import { a as stopHostedNative, i as prepareHostedNative, r as placeHostedNative } from "./hosted-native-kaR4nUHk.mjs";
+import { d as throwIfCancelled } from "./exec-CGuDzt40.mjs";
+import { l as call, u as connectHost } from "./hosted-client-D19Lv0tg.mjs";
+import { a as requestHostedMetro } from "./metro-request-2LmFpC1z.mjs";
+import { a as stopHostedNative, i as prepareHostedNative, r as placeHostedNative } from "./hosted-native-BzXIy97W.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-5ur3YpxY.mjs → hosted-client-D19Lv0tg.mjs}

@@ -1,7 +1,7 @@
-import { c as throwIfCancelled, o as cancellableSleep } from "./exec-aULwtNly.mjs";
-import { X as diagnoseConnectFailure, ct as resolveEndpoint } from "./config-D5qNWJEP.mjs";
-import { t as BuildConnection } from "./client-DhJOvSvh.mjs";
-import { g as configuredMachines } from "./selection-C95m--1_.mjs";
+import { d as throwIfCancelled, l as cancellableSleep } from "./exec-CGuDzt40.mjs";
+import { K as resolveEndpoint, P as diagnoseConnectFailure } from "./config-BW0fAtoK.mjs";
+import { t as BuildConnection } from "./client-0_Mnfz0a.mjs";
+import { g as configuredMachines } from "./selection-xS50Mt0V.mjs";
 import { createHash } from "node:crypto";
 import { lstatSync, readFileSync, readdirSync, readlinkSync } from "node:fs";
 import { join } from "node:path";
@@ -14,6 +14,7 @@ const HOSTED_REQUEST_MARGIN_MS = 5e3;
 const workerBoundMs = (deadlineMs) => deadlineMs + hostedWorkerSettleMs();
 const SESSION_TIMEOUT_MS = hostedWorkerSettleMs() + workerBoundMs(DEVICE_HOST_LIMITS.logsMs) + 2 * workerBoundMs(DEVICE_HOST_LIMITS.stopMs) + HOSTED_POLL_MARGIN_MS;
 const PREPARE_TIMEOUT_MS = workerBoundMs(DEVICE_HOST_LIMITS.prepareMs) + HOSTED_POLL_MARGIN_MS;
+const IMAGE_INSTALL_TIMEOUT_MS = workerBoundMs(DEVICE_HOST_LIMITS.imageInstallMs);
 const INSTALL_TIMEOUT_MS = workerBoundMs(DEVICE_HOST_LIMITS.prepareMs) + HOSTED_POLL_MARGIN_MS;
 const OFFER_TIMEOUT_MS = workerBoundMs(DEVICE_HOST_LIMITS.offerMs) + HOSTED_REQUEST_MARGIN_MS;
 const RESERVE_TIMEOUT_MS = HOSTED_PARKED_CANDIDATES * (workerBoundMs(DEVICE_HOST_LIMITS.offerMs) + workerBoundMs(DEVICE_HOST_LIMITS.stopMs)) + workerBoundMs(DEVICE_HOST_LIMITS.offerMs) + HOSTED_REQUEST_MARGIN_MS;
@@ -277,4 +278,4 @@ async function upload(host, ids, missing, content) {
 	if (failure) throw failure;
 }
 //#endregion
-export { stoppedSession as _, SESSION_TIMEOUT_MS as a, call as c, hostConnector as d, hostedSession as f, sha256 as g, settle as h, RESERVE_TIMEOUT_MS as i, connectHost as l, requireHostedAppMode as m, OFFER_TIMEOUT_MS as n, attach as o, probeHostedSession as p, PREPARE_TIMEOUT_MS as r, bundleManifest as s, INSTALL_TIMEOUT_MS as t, heldNoLonger as u, unknownSession as v, upload as y };
+export { sha256 as _, RESERVE_TIMEOUT_MS as a, upload as b, bundleManifest as c, heldNoLonger as d, hostConnector as f, settle as g, requireHostedAppMode as h, PREPARE_TIMEOUT_MS as i, call as l, probeHostedSession as m, INSTALL_TIMEOUT_MS as n, SESSION_TIMEOUT_MS as o, hostedSession as p, OFFER_TIMEOUT_MS as r, attach as s, IMAGE_INSTALL_TIMEOUT_MS as t, connectHost as u, stoppedSession as v, unknownSession as y };

package/dist/{hosted-logs-BYg4yeti.mjs → hosted-logs-D7anR6Dk.mjs}

@@ -1,11 +1,11 @@
-import { t as getExecutor } from "./exec-aULwtNly.mjs";
-import { E as workspaceDir, k as workspaceLogsDir$1 } from "./workspace-state-3bF4TB8P.mjs";
-import { J as validateDeviceSlot, V as deviceSlotFileKey, at as parseMachine$1 } from "./config-D5qNWJEP.mjs";
-import { l as phaseLine } from "./command-output-VrXd6qPX.mjs";
-import { n as macosDir } from "./state-CiflgxTP.mjs";
-import { n as androidLogGroups, r as isAndroidCrashText } from "./android-BeeC15Ve.mjs";
+import { t as getExecutor } from "./exec-CGuDzt40.mjs";
+import { E as workspaceDir, k as workspaceLogsDir$1 } from "./workspace-state-BdZ-QgmB.mjs";
+import { l as phaseLine } from "./command-output-DWI9tGPU.mjs";
+import { U as parseMachine$1, _t as validateDeviceSlot, ut as deviceSlotFileKey } from "./config-BW0fAtoK.mjs";
+import { n as macosDir } from "./state-DSOUqO-o.mjs";
+import { n as androidLogGroups, r as isAndroidCrashText } from "./android-B2DSKg-A.mjs";
 import { c as readNdjsonGenerations$1, i as createNdjsonWriter } from "./ndjson-CrjIsGzw.mjs";
-import { c as call } from "./hosted-client-5ur3YpxY.mjs";
+import { l as call } from "./hosted-client-D19Lv0tg.mjs";
 import { mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { LOG_ROTATE_BYTES, ambientWrite, withDirLockAsync } from "@stim-cli/core";
@@ -46,10 +46,16 @@ async function removeAgentAccess(file, keep) {
 		if (path !== keep) rmSync(path, { force: true });
 	}
 }
-async function agentAccess(file, credential, grant, note, platform = "macos") {
+/**
+* Writes the remote config that lets agent-device drive a hosted app and says how to use it. A tailnet machine is
+* reached at its `tailscale serve` route. A local network machine is reached only through `relay`, the loopback port
+* of this workspace's supervisor relay, or not at all when `relay` is the reason there is none.
+*/
+async function agentAccess(file, credential, grant, note, platform = "macos", relay = `Agent control of apps hosted on ${credential.machine} over the local network is relayed only for hosted iOS and Android Debug runs.`) {
 	const machine = parseMachine$1(credential.machine);
-	if (machine?.transport === "local") {
-		if (grant !== void 0) note(`Agent control of apps hosted on ${credential.machine} needs a tailnet machine; the local network does not carry it.`);
+	const local = machine?.transport === "local";
+	if (local && typeof relay === "string") {
+		if (grant !== void 0) note(relay);
 		await removeAgentAccess(file);
 		return {
 			driver: "none",
@@ -65,7 +71,7 @@ async function agentAccess(file, credential, grant, note, platform = "macos") {
 	const target = client ? join(dirname(file), client.configFile) : file;
 	const access = client && issued ? client.access({
 		grant: issued,
-		baseUrl: `https://${credential.address}${port === 443 ? "" : `:${port}`}${issued.path}`,
+		baseUrl: local ? `http://127.0.0.1:${relay}${issued.path}` : `https://${credential.address}${port === 443 ? "" : `:${port}`}${issued.path}`,
 		file: target,
 		platform
 	}) : null;

package/dist/{hosted-logs-sync-BPe8xnMu.mjs → hosted-logs-sync-D182b1eJ.mjs}

@@ -1,8 +1,8 @@
-import { n as pullHostedNativeLogs, r as readHostedNativeLogs, t as pullHostedMacosLogs } from "./hosted-logs-BYg4yeti.mjs";
-import { l as phaseLine } from "./command-output-VrXd6qPX.mjs";
-import { l as connectHost } from "./hosted-client-5ur3YpxY.mjs";
-import { n as readHostedIos, t as readHostedAndroid } from "./ios-state-BEIJRJ7P.mjs";
-import "./hosted-macos-BagT0Gn3.mjs";
+import { l as phaseLine } from "./command-output-DWI9tGPU.mjs";
+import { n as pullHostedNativeLogs, r as readHostedNativeLogs, t as pullHostedMacosLogs } from "./hosted-logs-D7anR6Dk.mjs";
+import { u as connectHost } from "./hosted-client-D19Lv0tg.mjs";
+import { n as readHostedIos, t as readHostedAndroid } from "./ios-state-CWsBysyN.mjs";
+import "./hosted-macos-D0DDQxvl.mjs";
 import { watch } from "node:fs";
 import { dirname, relative, resolve, sep } from "node:path";
 import { ambientWrite, configDir } from "@stim-cli/core";

package/dist/{hosted-macos-BagT0Gn3.mjs → hosted-macos-D0DDQxvl.mjs}

@@ -1,9 +1,9 @@
-import { o as cancellableSleep } from "./exec-aULwtNly.mjs";
-import { a as agentAccess, i as closeAgentConnection, o as removeAgentAccess, t as pullHostedMacosLogs } from "./hosted-logs-BYg4yeti.mjs";
-import { l as phaseLine } from "./command-output-VrXd6qPX.mjs";
-import { n as macosDir } from "./state-CiflgxTP.mjs";
-import { st as runCancellationSignal } from "./toolchain-CGdgD4x4.mjs";
-import { _ as stoppedSession, a as SESSION_TIMEOUT_MS, c as call, f as hostedSession, g as sha256, h as settle, i as RESERVE_TIMEOUT_MS, l as connectHost, o as attach, r as PREPARE_TIMEOUT_MS, s as bundleManifest, t as INSTALL_TIMEOUT_MS, u as heldNoLonger, v as unknownSession, y as upload } from "./hosted-client-5ur3YpxY.mjs";
+import { l as cancellableSleep } from "./exec-CGuDzt40.mjs";
+import { l as phaseLine } from "./command-output-DWI9tGPU.mjs";
+import { a as agentAccess, i as closeAgentConnection, o as removeAgentAccess, t as pullHostedMacosLogs } from "./hosted-logs-D7anR6Dk.mjs";
+import { n as macosDir } from "./state-DSOUqO-o.mjs";
+import { st as runCancellationSignal } from "./toolchain-s5ZmG42Z.mjs";
+import { _ as sha256, a as RESERVE_TIMEOUT_MS, b as upload, c as bundleManifest, d as heldNoLonger, g as settle, i as PREPARE_TIMEOUT_MS, l as call, n as INSTALL_TIMEOUT_MS, o as SESSION_TIMEOUT_MS, p as hostedSession, s as attach, u as connectHost, v as stoppedSession, y as unknownSession } from "./hosted-client-D19Lv0tg.mjs";
 import { randomUUID } from "node:crypto";
 import { join } from "node:path";
 import { ambientContext, ambientWrite } from "@stim-cli/core";