stim 1.28.0 → 1.30.0

package/dist/{gc-DM5oMm-J.mjs → gc-Co7PE36D.mjs}

@@ -1,23 +1,24 @@
 import { D as ownership_claim_exports, S as process_identity_exports, c as throwIfCancelled, l as WorkspaceProcessCleanupError, m as declareSpawnsOn, t as getExecutor, v as stopDeclaringSpawnsOn, x as withDrainingCancellation } from "./exec-aULwtNly.mjs";
-import { E as workspaceDir, u as workspaceLastUsed } from "./workspace-state-kIZrdlSg.mjs";
-import { F as isOnMountedVolume, G as projectDeviceSlots, I as listMountedVolumes, L as measuredDirectorySizeAsync, N as directorySizeAsync, O as withConfigLockAsync$1, P as formatBytes, R as volumeRootFor, S as removeProject, _ as loadConfig$1, d as getConfigDir, j as acquireAvdClaim } from "./config-Cn94Jc0g.mjs";
-import { d as quotedPath$1, h as shortUdid, o as formatLongDuration, u as plural } from "./command-output-C8R1KIvi.mjs";
+import { E as workspaceDir, u as workspaceLastUsed } from "./workspace-state-DGwkPXwq.mjs";
+import { F as isOnMountedVolume, G as projectDeviceSlots, I as listMountedVolumes, L as measuredDirectorySizeAsync, N as directorySizeAsync, O as withConfigLockAsync$1, P as formatBytes, R as volumeRootFor, S as removeProject, _ as loadConfig$1, d as getConfigDir, j as acquireAvdClaim } from "./config-AbUjIBOQ.mjs";
+import { d as quotedPath$1, h as shortUdid, o as formatLongDuration, u as plural } from "./command-output-BBW8eWPL.mjs";
 import { t as runOperationFile } from "./operation-exec-Dp4FuIGR.mjs";
-import { $t as TRASH_MANIFEST, Ft as matchWorktreeEntry, Wt as resolveSourceCheckoutAsync, Zt as TRASH_CLAIMS, en as deleteTrashEntry, jt as listWorktreesAsync } from "./settings-CY5JZlNN.mjs";
-import { i as findProjectRoot$1, v as detectIsExpo } from "./project-Sui52ywT.mjs";
-import { Ct as forgetCreatedDeviceAsync, F as listAvdsAsync, L as listOrphanedAvdDirectories, V as ownedAvdDirectory, ft as POOL_SETTING_REMEDY, h as avdNameAbsent, vt as parkedMaxSetting, wt as readCreatedDevices$1 } from "./android-CsPs-7Mg.mjs";
-import { $ as gradleVersionLines, $n as memoryCacheKind, B as includesArchives, Ct as describeError, En as runProcessOperation, F as gcOptionsOf, Ft as withEasProjectLock, G as planCacheEmptying, H as includesRecordings, J as selectsBeyondCaches, Jn as parseArchiveSelector, K as previewScopedEmptying, L as openGcLog, Q as deleteGradleVersions, St as deleteEasSessions, U as includesWorkspaceOutputs, V as includesParkedDevices, W as isWorkspacesScope, X as collectGradleVersions, Y as trimCaches, Zn as collectMemoryReport, _t as findStaleDeviceRecords, ar as scopedMemoryReport, at as DEVICE_LIST_TIMEOUT_MS, bt as withAndroidAvdSizes, ct as collectParkedSims, dt as deleteProjectDevices, er as memoryLines, et as gradleVersionsPending, fr as sizeCaches, gt as findOrphanedDevices, ht as eraseParkedDevices, ir as reclaimMemory, it as collectInventory, lt as deleteParkedAvds, mt as deviceSweepIsScoped, nr as memorySweepIsScoped, ot as collectDeviceLeases, pt as describeUnverifiableDevices, q as selectCaches, rr as memoryWorkPending, rt as getMachineCacheReport, sr as phase, st as collectParkedAvds, tr as memoryScope, tt as includesGradleVersions, ur as discoverCaches, ut as deleteParkedSims, vt as findStaleProjectDevices, wt as withRemoteSessionGcLocks, xt as collectEasSessionSweep, yt as unverifiedDeviceCommand, z as emptyCaches } from "./ccache-Bm_A1xX9.mjs";
-import { n as easMachineStateRoot$1, o as removeEasSessionClaimAsync, r as readEasSessionLedger$1 } from "./eas-session-ledger-CBFo_Uo1.mjs";
-import { At as mapLimited, Dt as createGcResults, Et as GC_OUTPUT, I as idleDeviceLines, M as collectIdleDevices, Mt as sizeConcurrency, N as collectIdleDevicesAsync, R as parseIdleDuration, a as collectOrphanedWorkspaces, b as workspaceInUseAsync, c as isInsideWorkspaces, f as rootPresence, g as ARTIFACT_DIRS, i as clearWorkspaceOutputs, jt as readConcurrency, kt as eachLimited, n as REBUILD_COST, o as collectWorkspaceOutputs, p as sizeText, r as WORKSPACE_OUTPUT_DIRS, s as deleteOrphanedWorkspaces, t as LIGHTEN_AFTER_MS, u as listWorkspaceDirs, v as withIdleWorkspace, wt as listBuildSlots, z as shutDownIdleDevices } from "./workspaces-CmOcceDN.mjs";
+import { $t as TRASH_MANIFEST, Ft as matchWorktreeEntry, Wt as resolveSourceCheckoutAsync, Zt as TRASH_CLAIMS, en as deleteTrashEntry, jt as listWorktreesAsync } from "./settings-D776ygML.mjs";
+import { i as findProjectRoot$1, v as detectIsExpo } from "./project-DPQjnpcI.mjs";
+import { Ct as forgetCreatedDeviceAsync, I as listAvdsAsync, R as listOrphanedAvdDirectories, V as ownedAvdDirectory, ft as POOL_SETTING_REMEDY, h as avdNameAbsent, vt as parkedMaxSetting, wt as readCreatedDevices$1 } from "./android-DdKG6lyD.mjs";
+import { $ as gradleVersionLines, $n as memoryCacheKind, B as includesArchives, Ct as describeError, En as runProcessOperation, F as gcOptionsOf, Ft as withEasProjectLock, G as planCacheEmptying, H as includesRecordings, J as selectsBeyondCaches, Jn as parseArchiveSelector, K as previewScopedEmptying, L as openGcLog, Q as deleteGradleVersions, St as deleteEasSessions, U as includesWorkspaceOutputs, V as includesParkedDevices, W as isWorkspacesScope, X as collectGradleVersions, Y as trimCaches, Zn as collectMemoryReport, _t as findStaleDeviceRecords, ar as scopedMemoryReport, at as DEVICE_LIST_TIMEOUT_MS, bt as withAndroidAvdSizes, ct as collectParkedSims, dt as deleteProjectDevices, er as memoryLines, et as gradleVersionsPending, fr as sizeCaches, gt as findOrphanedDevices, ht as eraseParkedDevices, ir as reclaimMemory, it as collectInventory, lt as deleteParkedAvds, mt as deviceSweepIsScoped, nr as memorySweepIsScoped, ot as collectDeviceLeases, pt as describeUnverifiableDevices, q as selectCaches, rr as memoryWorkPending, rt as getMachineCacheReport, sr as phase, st as collectParkedAvds, tr as memoryScope, tt as includesGradleVersions, ur as discoverCaches, ut as deleteParkedSims, vt as findStaleProjectDevices, wt as withRemoteSessionGcLocks, xt as collectEasSessionSweep, yt as unverifiedDeviceCommand, z as emptyCaches } from "./ccache-B8gY50-h.mjs";
+import { n as easMachineStateRoot$1, o as removeEasSessionClaimAsync, r as readEasSessionLedger$1 } from "./eas-session-ledger-CW3l-inB.mjs";
+import { At as mapLimited, Dt as createGcResults, Et as GC_OUTPUT, I as idleDeviceLines, M as collectIdleDevices, Mt as sizeConcurrency, N as collectIdleDevicesAsync, R as parseIdleDuration, a as collectOrphanedWorkspaces, b as workspaceInUseAsync, c as isInsideWorkspaces, f as rootPresence, g as ARTIFACT_DIRS, i as clearWorkspaceOutputs, jt as readConcurrency, kt as eachLimited, n as REBUILD_COST, o as collectWorkspaceOutputs, p as sizeText, r as WORKSPACE_OUTPUT_DIRS, s as deleteOrphanedWorkspaces, t as LIGHTEN_AFTER_MS, u as listWorkspaceDirs, v as withIdleWorkspace, wt as listBuildSlots, z as shutDownIdleDevices } from "./workspaces-7_RWoi6c.mjs";
 import { t as canonicalPath } from "./paths-BsJMoPP2.mjs";
-import { N as listBuildLocks, k as removeExpiredLease } from "./activity-DRMg4_mD.mjs";
-import { d as listAllIosSims, f as listAllIosSimsAsync } from "./ios-B1DYuOjh.mjs";
-import { r as readCollectors } from "./ownership-DJCq48IJ.mjs";
-import { A as deleteSelectedArchives, O as describeDereferenced, j as sweepArchiveStaging, k as reclaimProject } from "./worktree-2dk5edza.mjs";
-import { p as writeCacheFile } from "./warm-progress-B0Vpuvpl.mjs";
-import { a as restoreProblem, o as workspaceKeys } from "./lightened-DFAJgfIk.mjs";
-import { C as worktreeRemovalReason, S as worktreePullRequestNote, _ as ownedDeviceUsage, a as previewMaintenance, b as collectWorktreeSweep, c as deleteTempLeftovers, d as appRoots, f as artifactWorktrees, h as finishedWorkspaces, l as tempLeftoverLines, m as collectArtifactsAsync, o as triggeringRoot, p as clearArtifact, s as collectTempLeftovers, t as deleteIdleWorkspaceDevices, u as tempLeftoverSection, v as maintenancePinned, x as removeWorktrees, y as candidateRootsAsync } from "./act-8iswyfRa.mjs";
-import { i as getSwiftpmCacheUsage, n as swiftpmCacheLines, r as getAgentDeviceUsage, t as agentDeviceLines } from "./agent-device-usage-output-tE90fDdo.mjs";
+import { N as listBuildLocks, k as removeExpiredLease } from "./activity-BTaUf0tc.mjs";
+import { d as listAllIosSims, f as listAllIosSimsAsync } from "./ios-CXnoVO_z.mjs";
+import { t as resolveMaintenanceSettings } from "./settings-D9LtQaUw.mjs";
+import { r as readCollectors } from "./ownership-Dtz9G5Gl.mjs";
+import { A as deleteSelectedArchives, O as describeDereferenced, j as sweepArchiveStaging, k as reclaimProject } from "./worktree-qKJ3x07S.mjs";
+import { p as writeCacheFile } from "./warm-progress-DQ2wQZKp.mjs";
+import { a as restoreProblem, o as workspaceKeys } from "./lightened-23pqe7LS.mjs";
+import { C as candidateRootsAsync, D as worktreeRemovalReason, E as worktreePullRequestNote, S as maintenancePinned, T as removeWorktrees, _ as finishedWorkspaces, a as previewMaintenance, b as cachedDeviceActivity, c as deleteTempLeftovers, d as appRoots, f as artifactWorktrees, g as stopIdleWorkspace, h as planIdleStop, l as tempLeftoverLines, m as collectArtifactsAsync, o as triggeringRoot, p as clearArtifact, s as collectTempLeftovers, t as deleteIdleWorkspaceDevices, u as tempLeftoverSection, w as collectWorktreeSweep, x as cachedDeviceActivityAsync, y as ownedDeviceUsage } from "./act-BaKjDWGw.mjs";
+import { i as getSwiftpmCacheUsage, n as swiftpmCacheLines, r as getAgentDeviceUsage, t as agentDeviceLines } from "./agent-device-usage-output-DYBpO17K.mjs";
 import { claimRemoveCommand, isClaimRefusal, isClaimUnavailable, readClaimSet, releaseClaim, tryAcquireClaim } from "@stim-cli/core/ownership-claim";
 import { existsSync, lstatSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
@@ -2192,6 +2193,65 @@ async function deleteParkedHostedDevices(devices, { listAvds: list, operation }
 	return failures;
 }
 //#endregion
+//#region src/commands/gc/idle-workspaces.ts
+/**
+* Stops each workspace idle past its maintenance.idleStopHours, as automatic maintenance does, unless
+* maintenance.mode is off, so the dry run's maintenance plan lists every stop; returns failures.
+*/
+async function stopIdleWorkspaces(output, operation) {
+	const env = operation?.env ?? process.env;
+	if (resolveMaintenanceSettings(void 0, env).mode === "off") return 0;
+	const devices = () => {
+		const now = Date.now();
+		return operation ? cachedDeviceActivityAsync(now, env, operation.signal, operation) : cachedDeviceActivity(now);
+	};
+	const protectedRoot = triggeringRoot(operation);
+	let plan;
+	try {
+		plan = await planIdleStop({
+			protectedRoot,
+			now: Date.now(),
+			env,
+			devices: devices(),
+			operation
+		});
+	} catch (error) {
+		if (error instanceof WorkspaceProcessCleanupError || error instanceof Error && "reportCleanup" in error) throw error;
+		operation?.signal.throwIfAborted();
+		output.log(chalk.red(`Could not plan idle workspace stops: ${error instanceof Error ? error.message : String(error)}`));
+		return 1;
+	}
+	let failures = 0;
+	for (const action of plan.actions) {
+		operation?.signal.throwIfAborted();
+		let outcome;
+		try {
+			outcome = await stopIdleWorkspace(action, {
+				protectedRoot,
+				devices,
+				operation,
+				by: "stim gc --delete"
+			});
+		} catch (error) {
+			if (error instanceof WorkspaceProcessCleanupError || error instanceof Error && "reportCleanup" in error) throw error;
+			operation?.signal.throwIfAborted();
+			outcome = {
+				status: "failed",
+				bytes: 0,
+				detail: error instanceof Error ? error.message : String(error)
+			};
+		}
+		output.record("devServer", outcome.status, action.target, { detail: outcome.status === "done" ? action.reason : outcome.detail });
+		if (outcome.status === "done") output.log(chalk.green(`Stopped the idle workspace ${action.target}: ${action.reason}`));
+		else if (outcome.status === "kept") output.log(chalk.dim(`Kept the workspace ${action.target}: ${outcome.detail}`));
+		else {
+			failures++;
+			output.log(chalk.red(`Could not stop the idle workspace ${action.target}: ${outcome.detail}`));
+		}
+	}
+	return failures;
+}
+//#endregion
 //#region src/commands/gc.ts
 function readGcReport(options = {}, deps = {}) {
 	return sweep({
@@ -3009,6 +3069,8 @@ async function runGcCore(opts, deps, execution, reportOnly = false) {
 	}
 	let deleteFailures = idleFailures;
 	throwIfCancelled(signal, "GC");
+	if (cache === null) deleteFailures += await stopIdleWorkspaces(output, deps.operation);
+	throwIfCancelled(signal, "GC");
 	deleteFailures += await deleteArchives(report.archives, output, signal);
 	throwIfCancelled(signal, "GC");
 	deleteFailures += report.workspaceOutputs ? (await clearWorkspaceOutputs(report.workspaceOutputs, {
@@ -3143,7 +3205,7 @@ async function runGcCore(opts, deps, execution, reportOnly = false) {
 	return payload(deleteFailures);
 }
 function gcCommand(program) {
-	program.command("gc").description("Report what Stim has left behind: dead project entries, orphaned workspace directories, clean Stim-managed linked worktrees whose branch is merged or whose pull request was merged or closed, orphaned owned devices and EAS sessions, records of devices that no longer exist, build locks whose builder is gone, expired physical-device leases, the shared build caches, the build outputs and logs of each workspace, the memory of watchman and of the Gradle and Kotlin daemons, and recognized leftovers in TMPDIR. Reports by default; pass --delete to act.").option("--worktrees", "also remove clean, idle Stim-managed linked worktrees, not only merged ones: with --delete run `stim worktree remove` (never --force) on each; idle means unused for --older-than days, 7 without it").option("--delete", "actually prune the reported entries, reap the reported devices, lighten every workspace that is not building and ran no ios, android or macos command in the last 15 minutes by clearing its build outputs, a running dev server or booted device included, and trim its Metro, client and device logs to their newest 8 MiB").option("--older-than <days>", "also reap owned devices whose workspace has not been used this long, trim shared cache entries nothing has used in that time and device recordings made before it, and clear workspace build outputs only for workspaces idle this long and parked devices only once parked this long", (v) => {
+	program.command("gc").description("Report what Stim has left behind: dead project entries, orphaned workspace directories, clean Stim-managed linked worktrees whose branch is merged or whose pull request was merged or closed, orphaned owned devices and EAS sessions, records of devices that no longer exist, build locks whose builder is gone, expired physical-device leases, the shared build caches, the build outputs and logs of each workspace, the memory of watchman and of the Gradle and Kotlin daemons, and recognized leftovers in TMPDIR. Reports by default; pass --delete to act.").option("--worktrees", "also remove clean, idle Stim-managed linked worktrees, not only merged ones: with --delete run `stim worktree remove` (never --force) on each; idle means unused for --older-than days, 7 without it").option("--delete", "actually prune the reported entries, reap the reported devices, lighten every workspace that is not building and ran no ios, android or macos command in the last 15 minutes by clearing its build outputs, a running dev server or booted device included, trim its Metro, client and device logs to their newest 8 MiB, and, unless maintenance.mode is off, stop each workspace idle past maintenance.idleStopHours as stim stop does").option("--older-than <days>", "also reap owned devices whose workspace has not been used this long, trim shared cache entries nothing has used in that time and device recordings made before it, and clear workspace build outputs only for workspaces idle this long and parked devices only once parked this long", (v) => {
 		const n = parseInt(v, 10);
 		if (!Number.isFinite(n) || String(n) !== String(v).trim()) throw new InvalidArgumentError("must be a whole number of days, e.g. --older-than 30");
 		return n;

package/dist/{guide-C4I46XAk.mjs → guide-DkepBgHT.mjs}

@@ -1,8 +1,8 @@
-import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-CY5JZlNN.mjs";
-import { i as findProjectRoot$1 } from "./project-Sui52ywT.mjs";
-import { h as RECENT_LAUNCH_MS } from "./eas-session-ledger-CBFo_Uo1.mjs";
-import { o as guideStatus, t as WATCHMAN_NESTED_WORKTREES } from "./doctor-watchman-BTW82PDC.mjs";
-import "./status-watch-BmsPqYSU.mjs";
+import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-D776ygML.mjs";
+import { i as findProjectRoot$1 } from "./project-DPQjnpcI.mjs";
+import { h as RECENT_LAUNCH_MS } from "./eas-session-ledger-CW3l-inB.mjs";
+import { o as guideStatus, t as WATCHMAN_NESTED_WORKTREES } from "./doctor-watchman-D1IyMle9.mjs";
+import "./status-watch-CnSyXUmj.mjs";
 import { SETTINGS, SETTINGS_SCHEMA_URL, TUTORIAL_VERSION } from "@stim-cli/core/state";
 import chalk from "chalk";
 //#region src/guide/agent.ts
@@ -288,6 +288,12 @@ activity prevent reclaim. The supervisor's own idle shutdown default is 30m.
 Read the holder names in progress and build.waitingFor in status; do not start
 replacement runs while one is queued. See \`stim guide lifecycle concurrency\`.
 
+After maintenance.idleStopHours (default 6) with no Stim command, native run,
+Metro bundle or HMR request, agent-device command or live view, automatic
+maintenance stops the workspace as stim stop does. Device and app logs do not
+count. After a long pause, run stim ios or android again before driving the
+app; see \`stim guide cleanup\`.
+
 Treat a refusal as an ownership or state mismatch: read its code and remedy.
 Never reach for --force first.
 Stim leaves externally started Metro servers alone. Stop them with their original
@@ -412,6 +418,7 @@ FULL TOPIC LIST
   stim guide lifecycle budget     # disk and memory budgets, automatic reclaim
   stim guide lifecycle options    # every flag, Android variants, --device-type, --system-image, --device-profile
   stim guide lifecycle devices    # ios --device and android --device on a physical phone
+  stim guide lifecycle tools      # device location|permission|push|network on the owned simulator or emulator
   stim guide lifecycle release    # Release configurations and ...Release variants
   stim guide api                  # typed run, stop, diagnostics and cancellation from the main package
   stim guide facts                # the --json payloads
@@ -697,7 +704,7 @@ Do not point independent Stim homes at a concurrently writable shared cache.
 //#endregion
 //#region src/guide/facts.ts
 const facts = {
-	summary: "The --json payloads: `start`, `ios`, `android`, `web`, `ios|android --plan`, `reload`, `stop`, `status`, `doctor`, `device lock`/`unlock`, `gc`, and the error contract",
+	summary: "The --json payloads: `start`, `ios`, `android`, `web`, `ios|android --plan`, `reload`, `stop`, `status`, `doctor`, `device lock`/`unlock`, `device location|permission|push|network`, `gc`, and the error contract",
 	preamble: () => `SLOTS
 Named ios/android runs add slot to their JSON facts. Default-run fields remain
 compatible. status adds a slots array per environment with each named slot's
@@ -707,7 +714,7 @@ Named collector, lease-holder, and launch keys use platform:slot internally.
 FACTS CONTRACT
 
 \`start\`, \`ios\`, \`android\`, \`web\`, \`reload\`, \`stop\`, \`status\`, \`stats\`, \`doctor\`,
-\`gc\`, and \`device lock\`/\`device unlock\` each print exactly ONE line of JSON on
+\`gc\`, \`device lock\`/\`device unlock\`, and \`device location|permission|push|network\` each print exactly ONE line of JSON on
 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.
@@ -1236,9 +1243,10 @@ leased until <time>" for each one.`,
                   null when off; plan lists what the next start, ios or
                   android would reclaim, in the \`reclaimed\` shape without
                   freedMb, and is empty while under budget
-  deviceHosts     one { machine, state, dnsName?, deviceId?, requestedAt?, expiresAt?,
-                  host? } per remote.machines entry. state is "approved",
-                  "pending", "not-asked", "revoked", "lapsed", "key-changed", "outdated",
+  deviceHosts     one { machine, state, dnsName?, fingerprint?, deviceId?, requestedAt?,
+                  expiresAt?, host? } per remote.machines entry. state is "approved",
+                  "pending", "not-asked", "revoked", "lapsed", "key-changed",
+                  "key-unconfirmed", "outdated",
                   "not-on-tailnet", "tailscale-off", "unreachable", "invalid",
                   "credentials-unavailable" or "busy". Setup tickets stay private.
                   Only --fix asks for access or forgets removed names. A
@@ -1254,7 +1262,12 @@ leased until <time>" for each one.`,
                   expires, absent for a Stim Desktop ticket; "lapsed" is a
                   pending request whose expiry passed. --fix asks again.
                   "key-changed" means the worker did not prove the
-                  stim-server key pinned at approval. "outdated" means its
+                  stim-server key pinned at approval. "key-unconfirmed" is a
+                  local: machine that approved this one but whose key no
+                  person confirmed, so nothing pinned it; fingerprint is the
+                  key's fingerprint to compare with the one stim-server setup
+                  printed there, and only stim doctor --fix in a terminal asks.
+                  A local: entry has no dnsName. "outdated" means its
                   stim-server speaks protocol 1; the finding names the
                   stim-server service update command to run there.
   toolchain       { entries, projectNode } on macOS, else null. entries is one { name, value,
@@ -1267,11 +1280,12 @@ leased until <time>" for each one.`,
                   pins Node (bin, version and match are null when no install
                   fits the pin; match is "exact", or "major" for the newest
                   install of the pinned major not older than the pin), else null
-  remoteMachines  one { machine, state, diagnosis?, dnsName?, deviceId?, requestedAt?,
-                  expiresAt?, offloadable?, reasons?, problems?, capacity?, host? } per
+  remoteMachines  one { machine, state, diagnosis?, dnsName?, fingerprint?, deviceId?,
+                  requestedAt?, expiresAt?, offloadable?, reasons?, problems?, capacity?, host? } per
                   remote.machines entry, for its build approval; state is "approved", "pending", "not-asked",
                   "revoked" (revoked or denied), "lapsed" (the request lapsed
-                  before approval), "key-changed", "outdated",
+                  before approval), "key-changed", "key-unconfirmed" (as in
+                  deviceHosts), "outdated",
                   "not-on-tailnet", "tailscale-off", "unreachable" or
                   "invalid". diagnosis is { layer, code, title, message, remedy }
                   for the first layer that stopped this machine, present for
@@ -1286,6 +1300,11 @@ leased until <time>" for each one.`,
                   nothing behind the route), server-not-ready (503: running but
                   not serving; its message gives the cause the server reports),
                   server-no-answer (silent route while tailscale ping reaches the Mac), server-outdated and connect-failed (none of the above).
+                  A local: machine never reads Tailscale and reports
+                  lan-not-listening (nothing accepts connections on its
+                  stim-server port), lan-no-answer (no reply: the network, or
+                  the macOS firewall on that machine), server-not-ready or
+                  connect-failed.
                   Tailscale's own "offline" flag lags a reachable peer, so an
                   answer from the machine outranks it. host has the same shape and presence rule as in
                   deviceHosts, as do expiresAt (a pending request's lapse
@@ -2041,7 +2060,7 @@ RULES
   Each booted simulator and detected emulator in environments (and in
   slots) carries activity; a shut-down or physical device has none:
 
-  activity  { state, driver?, lastActivityAt?, recent?, basis }
+  activity  { state, driver?, lastActivityAt?, recent?, basis, unknown? }
 
   state            "driven"   a live claim or driver holds the device now
                    "active"   no driver, but activity in the last 10 minutes
@@ -2064,6 +2083,8 @@ RULES
                    workspace-use, supervisor-start, page-log or viewer, each
                    rounded down to the minute. viewer is now while a
                    stim-server client streams the device's frames
+  unknown          for "driven" only: the checks that could not be read, in
+                   basis's vocabulary; absent when every check was read
   basis            the evidence behind state, strongest first:
                    agent-device-claim, agent-device-lease  agent-device state,
                      read only; live only when every recorded process is alive
@@ -2445,8 +2466,8 @@ RULES
   minutes. It caches them in $STIM_HOME/agent-sessions.json, which one-shot
   status reads and ignores once it is 2 minutes old. Both sources are other
   tools' internal files; a missing or changed one only drops its sessions.
-  \`start\`, \`ios\`, \`android\`, \`web\`, \`reload\` and \`worktree warm\`
-  also record the CLAUDE_CODE_SESSION_ID or CODEX_THREAD_ID of the shell
+  \`start\`, \`ios\`, \`android\`, \`web\`, \`reload\`, \`logs\` and
+  \`worktree warm\` also record the CLAUDE_CODE_SESSION_ID or CODEX_THREAD_ID of the shell
   that ran them, so that session is listed for 30 minutes after the command
   even when status cannot see it, and for as long as it runs.
 
@@ -2990,8 +3011,8 @@ WHAT THE SUPERVISOR IS
   (default 60; 0 never stops) with no bundle request, no client log record
   (in-app console logs; for Expo or metro.command, any stdout line of the
   dev server) and no Stim
-  command in the workspace (start, ios, android, reload, worktree warm). It
-  checks once a minute. It keeps running while a bundle response is in
+  command in the workspace (start, ios, android, reload, logs, worktree
+  warm). It checks once a minute. It keeps running while a bundle response is in
   flight, while a build in the workspace is in progress, while a stim ios,
   android or stop run holds the workspace's native-run lock, while the
   workspace holds an unexpired device lease (\`stim device lock\` or a
@@ -3024,8 +3045,9 @@ WHAT THE SUPERVISOR IS
   own stops show only in the log).
     requested      a Stim command stopped it and says which: stim stop,
                    stim worktree remove, stim gc --delete, stim start
-                   --reset-cache, or budget reclaim (with the workspace whose
-                   ios, android or start run reclaimed it)
+                   --reset-cache, budget reclaim (with the workspace whose
+                   ios, android or start run reclaimed it), or automatic
+                   maintenance with its idle reason (guide cleanup, IDLE STOP)
     signal         a SIGTERM or SIGINT with no Stim stop request recorded,
                    so it likely came from outside Stim (level warn)
     server-exited  the dev server exited on its own (level error). Expo CLI
@@ -3627,7 +3649,9 @@ WHAT WRITES WHAT
                        and, on Expo, one per dev-client manifest
                        request (manifest_request_started, _finished,
                        _failed: debug level, with platform and requestId;
-                       launch verification reads them as progress)
+                       launch verification reads them as progress), and
+                       an hmr_update debug record, at most once a minute,
+                       when Metro pushes a Fast Refresh change to the app
   client.ndjson        in-app console logs and redboxes -- BARE PROJECTS ONLY.
                        In expo-child and command-child mode everything the
                        dev server prints lands in metro.ndjson with raw: true,
@@ -4620,7 +4644,11 @@ so a Debug run on one is wired to a LAN origin instead of localhost.`,
   then until SpringBoard has finished starting, which \`simctl launch\` needs.
   Booted alone does not end that wait. The failure names the udid and the wait.
   After boot, a process-spawn probe must finish within 30 seconds before
-  installation. If it fails, the refusal includes observed host memory pressure
+  installation. A probe that times out while the simulator still reports Booted
+  is retried for about three minutes, since a loaded host can leave a booted
+  simulator unresponsive for a while; a timeout on a simulator that no longer
+  reports Booted, and any other probe failure, refuse at once. If it
+  fails, the refusal includes observed host memory pressure
   when available. Free memory before retrying under pressure; see
   \`stim guide lifecycle simslim\`. Booted alone does not prove readiness.
   The same probe lists the simulator's launchd jobs and requires a running
@@ -4692,6 +4720,35 @@ so a Debug run on one is wired to a LAN origin instead of localhost.`,
   no token left in its \`state.json\` (its workspace directory was recreated).
   The remedy for that last one is \`stim device unlock\`, which releases by
   holder rather than by token.`
+		},
+		STIM_DEVICE_TOOL_TARGET: {
+			summary: "a device tool found no owned, running simulator or emulator in that slot to act on",
+			body: () => `STIM_DEVICE_TOOL_TARGET
+  \`stim device location|permission|push|network\` act only on this workspace's
+  own local simulator or emulator in the slot. The message says which check
+  failed: the slot's device is hosted on another Mac, the workspace runs an
+  EAS Simulator session, the slot has no owned device (a physical device
+  reached with \`--device\` is never one), the recorded simulator is gone or not
+  owned by this Stim home, or it is not booted or running. Permission and push
+  also refuse when no app is recorded for the device. Run the platform command
+  the remedy names (\`stim ios\` or \`stim android\`, with \`--slot\` for a named
+  slot) and retry. No tool runs before this refusal.`
+		},
+		STIM_DEVICE_TOOL_UNSUPPORTED: {
+			summary: "that device tool has no equivalent on that platform",
+			body: () => `STIM_DEVICE_TOOL_UNSUPPORTED
+  The platform lacks the action: Android cannot clear a simulated location
+  (\`adb emu geo fix\` only sets one), iOS has no network switch, and Android
+  has no simulated push. The remedy names the nearest thing.`
+		},
+		STIM_DEVICE_TOOL_FAILED: {
+			summary: "simctl or adb failed, or the device did not report the change afterwards",
+			body: () => `STIM_DEVICE_TOOL_FAILED
+  The tool call exited non-zero or timed out, with its output in the message, or
+  the read-back after an Android permission or network change did not show the
+  requested state. For a permission, the app must declare the permission in its
+  manifest; when it declares none of the service's permissions the call refuses
+  with this code. Check the device with \`stim status\` and retry.`
 		},
 		STIM_DEVICE_WIRELESS_FAILED: {
 			summary: "an iPhone paired over Wi-Fi timed out or dropped during install or launch; use the cable",
@@ -5711,8 +5768,11 @@ SpringBoard is back; an already slim simulator is not touched. Turn sound on
 for one device with Sound (iOS) or Media sound (Android) in its Stim Desktop
 options; the choice lasts until that device next boots. Android 14 and older images have no shell command that can
 set media volume, so startup warns, as it does whenever a mute is not
-confirmed. Host volume, Android alarm and ringtone volumes, hosted devices and
-physical devices are unchanged.
+confirmed. A hosted simulator or emulator on a named Mac is muted the same way
+after the host boots or adopts it (best effort; a failed mute is not reported
+to the client), and Stim Desktop's Sound options do not reach
+it. Host volume, Android alarm and ringtone volumes and physical devices are
+unchanged.
 
 Repeat step 3 whenever a NATIVE input changes. A JS-only edit needs nothing --
 that is what Fast Refresh over the running dev server is for. \`stim reload\` is
@@ -7904,7 +7964,7 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
 
   Warm registers the app it prepares, so \`stim status\` lists the workspace
   with phase "warming" while it runs and "ready" once it succeeds, until the
-  first start, ios, android, web or reload there or for 2 hours
+  first start, ios, android, web, reload or logs there or for 2 hours
   (\`guide facts status\`). In a monorepo worktree root, that app is the one
   the source checkout has registered.
 
@@ -8430,6 +8490,60 @@ THE POOL: WHICH DEVICE AN ID-LESS \`--device\` PICKS
   The chosen device is on the phase line and in \`--json\` (\`udid\` or
   \`serial\`, plus \`deviceName\`), so an agent can hand the same id to its
   device tool.`
+		},
+		tools: {
+			summary: "device location, permission, push and network: change the owned simulator or emulator and read it back",
+			body: () => `  \`stim device location|permission|push|network\` change the workspace's own
+  simulator or emulator. Each takes the platform first, like \`device lock\`,
+  and \`--slot <name>\` and \`--json\`:
+
+    stim device location <ios|android> --set <lat,lng>   # --set 45.5,-73.6
+    stim device location ios --clear
+    stim device permission <ios|android> <grant|revoke|reset> <service>
+    stim device push ios --payload '<json with an "aps" key>'
+    stim device network android <on|off>
+
+  THE TARGET is the slot's owned, booted simulator or emulator, resolved the
+  way \`reload\` resolves it: the project record says \`owned\`, the ledger
+  agrees, and the serial belongs to the recorded AVD. A hosted device, an EAS
+  Simulator session, a physical device (\`--device\`), a device Stim does not
+  own, and a device that is not running refuse with STIM_DEVICE_TOOL_TARGET and
+  run no tool. An action the platform lacks (Android \`--clear\`, iOS network,
+  Android push) refuses with STIM_DEVICE_TOOL_UNSUPPORTED. A tool call that
+  fails, or a device that disagrees with the change afterwards, is
+  STIM_DEVICE_TOOL_FAILED. A bad value is STIM_BAD_ARG.
+
+  \`--set\` takes latitude and longitude as ONE value so a negative latitude is
+  not read as a flag. Android's \`adb emu geo fix\` takes longitude first; Stim
+  swaps them. The emulator has no way to clear a location.
+
+  \`permission\` acts on the app of the slot's last launch, else the project's
+  bundle id or Android package. iOS services are simctl's own: all, calendar,
+  contacts, contacts-limited, location, location-always, media-library,
+  microphone, motion, photos, photos-add, reminders, siri. iOS notifications
+  and camera are not simctl services. Android services are calendar, camera,
+  contacts, location, microphone, motion, notifications, photos; one service is
+  one or two \`pm\` permissions. A permission the app did not declare is
+  listed in \`skipped\` and the call succeeds when the app declares at least one;
+  an app that declares none is STIM_DEVICE_TOOL_FAILED.
+  \`push\` needs the app to hold notification permission on the simulator, which
+  \`simctl privacy\` cannot grant: without it simctl answers "Source is not
+  authorized" and the call is STIM_DEVICE_TOOL_FAILED; open the app and accept
+  its prompt.
+  Android \`reset\` revokes the permission and clears its user-set flags so
+  the app asks again. A grant needs one of the
+  service's permissions to read back granted; a revoke or reset needs all of
+  them not granted, and a reset also no USER_SET or USER_FIXED flag. Changing a
+  permission can terminate the running app on both platforms.
+
+  \`--json\` prints ONE line: { platform, slot, deviceId, deviceName, tool,
+  action, ..., readBack }. \`readBack\` is read from the device after the change:
+  Android permissions are { permissions: [{ name, granted }] } from
+  \`dumpsys package\`, and Android network is { wifi, data } from \`settings get
+  global wifi_on|mobile_data\`. \`readBack\` is null where the platform has no
+  read: iOS location, permission and push, and Android location. Then the exit
+  status of simctl or adb is the only confirmation; Stim never echoes the
+  request as a read-back.`
 		},
 		release: {
 			summary: "Release configurations and ...Release variants: Metro skipped, process-proven launch, the JS swap",
@@ -8689,6 +8803,52 @@ supervisor's idle rules and records (guide lifecycle budget). While the level is
 check also names abnormally large processes (guide lifecycle simslim) in
 status's maintenance block and the maintenance log.
 
+IDLE STOP: the idle check, and gc --delete unless maintenance.mode is off (its
+dry run lists them in the maintenance plan), stop a workspace whose dev server
+runs or whose owned simulator or emulator is booted once it has had no real
+activity for maintenance.idleStopHours (default 6; 0 never; machine or project
+layers; STIM_MAINTENANCE_IDLE_STOP_HOURS overrides; fractions work). Six hours
+outlasts a lunch break, a meeting or an agent's pause between tasks, and still
+frees the memory overnight. Real activity is the newest of: a Stim command in
+the workspace (start, ios, android, macos, web, reload, logs, worktree warm),
+the end of its last native build, the start, progress or end of a Metro
+bundle or manifest request, or an HMR update, in metro.ndjson, an agent-device command in the workspace's
+agent-device sessions, and an open stim-server live view of its device.
+Device and system log lines, in-app console logs, dev server output,
+collector writes and maintenance's own records never count, and an app that
+only stays connected does not either. The stop is stim stop's: the dev
+server stops, the owned devices shut down through centralized teardown
+(never deleted), and the port is released; device leases stay. A build, a
+held native-run or metro-start lock, a build lock or slot, a running macOS
+app, a hosted or remote session, an unexpired device lease, a managed tunnel
+or remote lock, a running owned Chrome, a device driver other than
+agent-device, a live agent-device claim with no session activity to judge,
+device activity, an emulator list or an emulator's AVD name that cannot be read keeps
+the workspace;
+the check decides again under the native-run and metro-start locks. Each stop
+is a maintenance_action line naming the idle time (gc --delete records itself
+as the requester), each workspace kept past the window a maintenance_skip line
+with the reason. The port is released, so status shows the workspace idle as
+after stim stop, and the supervisor_stopped line in metro.ndjson names
+automatic maintenance and the idle time as the requester. The next start, ios or android starts it
+again. An owned emulator the activity check missed keeps the workspace while
+adb lists it, and so does any emulator adb lists without an AVD name, such as
+a stale offline entry that adb kill-server clears. A dev server that may still run after its supervisor
+exited is kept until stim stop ends it. So is a dev server whose requests Stim
+does not record: an Expo project before SDK 54, which cannot load Stim's Metro config
+adapter, or a dev server an older Stim started, until stim stop and stim start
+restart it. Unlike the other actions, it can stop the workspace whose dev server
+supervisor or status --watch timer started the pass; a pass a command starts,
+gc --delete included, never stops the command's own workspace.
+A dev server run through metro.command is kept: Stim sees none of its
+bundle or HMR requests. A Metro log that cannot be read, or that rotated
+within the window, and agent-device sessions, a state.json or a stim-server
+viewer record that cannot be read or verified keep the workspace too. A STIM_HOME-scoped home never
+idle-stops, because its devices are machine-wide. maintenance.keep does not keep a workspace from idle
+stop, which deletes nothing; set maintenance.idleStopHours 0 at workspace
+scope instead.
+  stim settings set maintenance.idleStopHours 1 --scope machine
+
 In on mode a pass runs, cheapest to rebuild first:
   1. orphaned workspace directories whose project is gone, and registered
      caches whose directory no longer exists
@@ -8733,7 +8893,8 @@ live build lock, or in a Metro store with a running or unverifiable dev
 server. Anything the pass cannot verify is kept. A device is deleted only when
 its workspace is idle: no dev server, native run, build, lease, managed lock,
 driven or busy device, and no recorded use within the window. Below disk
-pressure level 3 a pass never stops a dev server or watchman; removing a
+pressure level 3 a pass stops a dev server only by IDLE STOP above and never
+stops watchman; removing a
 finished worktree or orphaned directory does tear down that workspace's own
 dev server, owned devices and Chrome profile, as gc --delete does. ccache evicts by itself under
 caches.ccacheMaxGb.
@@ -9792,8 +9953,8 @@ WORKSPACE BUILD OUTPUTS
   1 keeps its own rules. A running, building, unverified or hosted macOS app
   keeps its workspace untouched.
     stim gc --delete --cache workspaces --older-than 7
-  Last use is the newest of the lastUsedAt that start, ios, android, reload
-  and worktree warm record in state.json, lastBuild.startedAt,
+  Last use is the newest of the lastUsedAt that start, ios, android, reload,
+  logs and worktree warm record in state.json, lastBuild.startedAt,
   supervisor.startedAt and the mtimes under logs/, so a dev server that keeps
   logging keeps its workspace in use.
   A workspace with none of those was last used when its workspace.json was
@@ -10060,7 +10221,7 @@ KEYS STIM READS
                         restores stock services when Stim applied the profile. Absolute paths, root or
                         symlink escapes, and missing files are refused before
                         simulator creation. Remote and unowned simulators are
-                        never changed.
+                        never slimmed.
   ios.signingIdentity   e.g. "Apple Development: Jane (TEAMID5678)" -- the
                         keychain identity to re-seal a \`--device\` build with,
                         overriding the one Stim derives from the artifact's own
@@ -10529,6 +10690,8 @@ floors below; report measures and plans and deletes nothing; off disables it.
 STIM_HOME and CI make the mode off unless STIM_MAINTENANCE is set.
 maintenance.keep is a project setting: pin a workspace so a pass never clears
 its build outputs or removes its worktree.
+maintenance.idleStopHours takes machine or project layers, so one workspace can
+stop sooner, later or never.
 See \`guide cleanup\` for checks, plans and log paths.
 
 ${SETTINGS.filter((setting) => setting.key.startsWith("maintenance.") || /^caches\..*MaxGb$/.test(setting.key)).map((setting) => `  ${setting.key}  ${setting.env ?? "project setting"}  ${setting.default === void 0 ? "unset" : `default ${setting.default}`}
@@ -10697,6 +10860,38 @@ machine a \`priority\` in its JSON:
 A host reports its own load limit in its device offer; a stim-server older than
 that does not, and this machine's \`server.maxLoadPerCore\` stands in for it.
 
+REMOTE MACHINES ON THE LOCAL NETWORK
+A machine on the same local network, without Tailscale, is named
+\`local:<host>\`: its private IPv4 address or host name, with an optional
+stim-server port (default 7787). On the worker, a person first chooses where
+stim-server listens with the machine setting \`server.lanAddresses\`, a list of
+network interface names or private IPv4 addresses. It defaults to [], which
+listens on no local network address; wildcard, loopback, public and IPv6
+addresses are refused, and the running server applies a change within seconds.
+An interface name follows the interface onto whatever private network it
+joins, so name the address on a machine that moves between networks, and an
+interface only on a worker that stays put. Then the person runs the setup
+command \`stim doctor --fix\` prints here:
+
+  stim settings set server.lanAddresses '["10.0.0.92"]'     # on the worker
+  stim settings set remote.machines '["local:10.0.0.92"]'   # on this machine
+  stim doctor --fix
+
+Every connection runs Stim's Noise handshake, so plain WebSocket carries it
+without TLS, and the address never identifies anyone. Nothing on a local network
+vouches for the worker's key, so \`stim-server setup\` prints the worker's server
+key fingerprint and \`stim doctor --fix\`, run by a person in a terminal, shows
+the fingerprint the worker answered with and pins the key only after they
+confirm it matches. Until then the entry reports key-unconfirmed and is not
+used. Agents never answer that question. The printed setup command carries the
+ticket, which is a credential: whoever spends it first, after setup stores it,
+gets the approval, and on a local network that takes only the ticket and a
+route to the worker, not tailnet membership. Agents show it only to the user.
+Offloaded builds and hosted Debug and
+Release runs work there; agent control of hosted apps needs a tailnet machine.
+\`stim-server pair\` puts \`ws://<address>:<port>\` in the phone pairing code
+when Tailscale is not running and \`server.lanAddresses\` is set.
+
 Automatic membership is separate from approval. In Desktop Settings > Remote
 Machines, use Builds enabled and Simulators enabled for this machine or a
 configured remote. The equivalent machine settings list the excluded members;
@@ -10827,6 +11022,13 @@ answer, an incompatible Stim build, CPU, Xcode, simulator SDK or CocoaPods, no
 Bundler for an app whose Gemfile.lock pins CocoaPods, no iPhone simulator on
 the runtime \`stim ios\` builds for here, low disk, or busy. With Package.swift
 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.
 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
@@ -11135,7 +11337,7 @@ scope, so it needs no --scope. Run it from the workspace:
 
 \`stim status --json\` then reports hidden: true on that environment, and
 clients that read it list the workspace under Hidden. The next start, ios,
-android, web, macos, reload or worktree warm in the workspace clears it, so
+android, web, macos, reload, logs or worktree warm in the workspace clears it, so
 a workspace in use is never hidden. \`worktree remove\` drops it with the
 workspace.
 
@@ -12082,11 +12284,10 @@ script such as mini-desktop.sh use these instead:
   quit                       stim stop (verified stop; the host frees the slot
                              and removes the app's defaults)
   clean                      stim worktree remove
-  3 concurrent slots         concurrency.maxDevices on the host; one bundle id
+  3 concurrent slots         concurrency.maxDevices on the host, counted apart
+                             from simulators and emulators; one bundle id
                              slot per session
 
-The host's own owned devices count toward concurrency.maxDevices.
-
 The agent-device rows work once the host's agent field names agent-device.
 
 On macOS 27, agent-device screenshot of a hosted app can return an image of the

package/dist/{hosted-android-DlaKLbW0.mjs → hosted-android-Du7NxufJ.mjs}

@@ -1,7 +1,7 @@
 import { c as throwIfCancelled } from "./exec-aULwtNly.mjs";
-import { c as call, l as connectHost } from "./hosted-client-DDRm9hPJ.mjs";
-import { i as requestHostedMetro } from "./metro-request-DXyKjVDF.mjs";
-import { a as stopHostedNative, i as prepareHostedNative, r as placeHostedNative } from "./hosted-native-CDe33CSr.mjs";
+import { c as call, l as connectHost } from "./hosted-client-Cect92SZ.mjs";
+import { i as requestHostedMetro } from "./metro-request-BtF7ox53.mjs";
+import { a as stopHostedNative, i as prepareHostedNative, r as placeHostedNative } from "./hosted-native-DmdLSmvu.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-DDRm9hPJ.mjs → hosted-client-Cect92SZ.mjs}

@@ -1,7 +1,7 @@
 import { c as throwIfCancelled, o as cancellableSleep } from "./exec-aULwtNly.mjs";
-import { Y as diagnoseConnectFailure, ot as resolveEndpoint } from "./config-Cn94Jc0g.mjs";
-import { t as BuildConnection } from "./client-YxCer6ab.mjs";
-import { g as configuredMachines } from "./selection-CXgM_VK_.mjs";
+import { Y as diagnoseConnectFailure, st as resolveEndpoint } from "./config-AbUjIBOQ.mjs";
+import { t as BuildConnection } from "./client-DrHykA24.mjs";
+import { g as configuredMachines } from "./selection-PCMT97XD.mjs";
 import { createHash } from "node:crypto";
 import { lstatSync, readFileSync, readdirSync, readlinkSync } from "node:fs";
 import { join } from "node:path";