stim 1.21.0 → 1.22.0

package/dist/gc-DnNDQyaP.mjs

@@ -0,0 +1,3 @@
+import { Ct as describeParkedSims, Dt as findOrphanedDevices, Ot as findStaleDeviceRecords, it as selectCaches, kt as findStaleProjectDevices, wt as describeUnverifiableDevices, xt as deleteParkedSims } from "./budget-Cvwn54qV.mjs";
+import { a as runGc, i as readGcReport, n as executeGc, o as withGcMaintenanceClaim, r as gcCommand, s as formatGcReport, t as collectGcReport } from "./gc-CXxN-4SE.mjs";
+export { collectGcReport, gcCommand as default, deleteParkedSims, describeParkedSims, describeUnverifiableDevices, executeGc, findOrphanedDevices, findStaleDeviceRecords, findStaleProjectDevices, formatGcReport, readGcReport, runGc, selectCaches, withGcMaintenanceClaim };

package/dist/{guide-Yqwt2bd6.mjs → guide-Br0LEfKy.mjs}

@@ -1,8 +1,8 @@
-import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-CsJDEXgK.mjs";
-import { i as findProjectRoot$1 } from "./project-BZNjmW_8.mjs";
-import { h as RECENT_LAUNCH_MS } from "./eas-session-ledger-op6A54yi.mjs";
-import { o as guideStatus, t as WATCHMAN_NESTED_WORKTREES } from "./doctor-watchman-Cv1F10Kj.mjs";
-import "./status-watch-GDCfqpTE.mjs";
+import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-C7O8A6ZI.mjs";
+import { i as findProjectRoot$1 } from "./project-wM_XFTvE.mjs";
+import { h as RECENT_LAUNCH_MS } from "./eas-session-ledger-DlY_serQ.mjs";
+import { o as guideStatus, t as WATCHMAN_NESTED_WORKTREES } from "./doctor-watchman-N2wDotwQ.mjs";
+import "./status-watch-Bg_u-pwR.mjs";
 import { SETTINGS, SETTINGS_SCHEMA_URL, TUTORIAL_VERSION } from "@stim-cli/core/state";
 import chalk from "chalk";
 //#region src/guide/agent.ts
@@ -418,7 +418,7 @@ FULL TOPIC LIST
 //#endregion
 //#region src/guide/api.ts
 var api_default = {
-	summary: "Typed lifecycle API: createStim, build, run, reload, stop, diagnostics, doctor, GC reports, settings, stats, logs, and cancellation",
+	summary: "Typed lifecycle API: createStim, build, run, reload, stop, warmWorktree, removeWorktree, diagnostics, doctor, GC, settings, stats, logs, and cancellation",
 	body: () => `PROGRAMMATIC API
 
 Install stim as a project dependency: npm install --save-dev stim.
@@ -445,6 +445,8 @@ STIM_HOME from env, else the default home. All operations run in the calling
 process against the client's home and project and call the same lifecycle
 operations as the CLI. None parses CLI arguments or changes the caller's
 cwd/environment.
+Custom Expo buildCacheProvider modules are not supported. Use EAS or a Stim
+cache provider.
 
 settings() returns the stim settings --json payload: every setting with its
 effective value, origin and per-layer values. An invalid environment override
@@ -461,6 +463,15 @@ Later registry changes do not redirect the write or its returned setting.
 Pending writes cancel. After commit, recording deletion finishes before the
 promise settles, including when cancellation arrives during cleanup.
 
+plan({ platform, slot?, signal? }) returns the configured ios/android/macos next-build
+report, matching --plan --json, without building, launching or taking a device.
+slot applies to ios/android. A predicted build refusal stays in the report;
+a failure to produce a report rejects with StimError. Fingerprinting uses the
+existing cancellable report helper. Native probes and cache downloads drain
+before the report settles. Plans use the report budgets below. Providers must settle on abort;
+cleanup exceeding 35 seconds refuses with STIM_CLAIM_UNAVAILABLE and retains
+the download directory rather than deleting files a provider may still write.
+
 doctor({ platform? }) and gc({ cache?, olderThan?, worktrees? }) read reports in
 process with a 60 second execution budget. They accept signal and attempt
 owned cleanup before rejecting. Deadline expiry rejects with
@@ -478,6 +489,57 @@ resources in place. Credential refresh waits asynchronously and checks
 cancellation before writing.
 On Windows, report probes require the built-in Windows PowerShell for process-tree containment.
 
+requestMachineAccess({ ticket?, signal? }) requests build and device-host access
+from configured remote machines without granting capabilities or repairing project
+state. It returns the iOS doctor report and records the completed project check
+after owned cleanup. A supplied ticket encodes 32 random bytes; omitting it
+generates or reuses a pending ticket instead of inheriting the process environment.
+A person approves each capability on the worker. Execution has a 120 second
+budget and cleanup uses the report's 35 second budget. Desktop requests access
+only through its matching-home bundled server's private desktop-machine-access
+subscription; cancellation waits for cleanup and reconnect never repeats it.
+
+warmWorktree({ signal?, beforeWarm? }) copies missing ignored state from the source
+checkout into the client's linked worktree in process. It returns { exitCode },
+0 or 1, without changing process.exitCode. Existing entries and tracked paths
+remain untouched. Copies share a source read claim and hold an exclusive target
+claim. beforeWarm(workspace) admits each canonical workspace in the resolved
+warming scope before registration or copying; throwing refuses warming.
+Progress uses onProgress. Cancellation drains the copy child before removing
+its partial entry or releasing claims. Unknown cleanup retains those claims
+and returns STIM_CLAIM_UNAVAILABLE with exact recovery paths. The execution
+budget is 90 minutes; cleanup still has the 35 second budget above. The API
+does not refresh the source or install dependencies; use CLI worktree warm
+--refresh for that.
+
+removeWorktree({ target?, force?, signal?, beforeRemove? }) runs the CLI's worktree removal
+safety checks and cleanup in process. target defaults to projectRoot; relative
+paths resolve against it. It returns { removed, exitCode } without changing
+process.exitCode. removed is true once a linked Git worktree is deleted, even
+if later branch cleanup fails. Source checkout environment cleanup can succeed
+with removed: false and exitCode: 0. force has the same destructive meaning as
+CLI --force. Cancellation stops pending work and waits for owned cleanup;
+completed actions remain applied. It uses the report budgets above.
+beforeRemove(workspace) runs for every canonical workspace in the resolved
+cleanup scope before effects, including registered descendants and pending
+branch cleanup. Throwing refuses the operation.
+
+gc() stays read-only. collectGarbage({ cache?, olderThan?, worktrees?, delete?,
+idleMs?, signal? }) runs the same GC selections and actions as the CLI, including
+an unscoped sweep. It returns { report, exitCode }; exitCode is 0 or 1 and does
+not change process.exitCode. delete: true enables deletion. idleMs reclaims
+owned devices idle for that many milliseconds, including without delete.
+The existing CLI rules for cache selection, workspace safety and scoped homes apply.
+
+A deletion or idle sweep takes this home's exclusive maintenance claim;
+concurrent maintenance rejects with STIM_CLAIM_REFUSED and names the held claim.
+Execution and cleanup use the report budgets above. Cancellation stops pending
+lock waits and further actions; completed actions remain applied. An archive
+whose history has started moving finishes publication before cancellation.
+Unresolved owned cleanup rejects with STIM_CLAIM_UNAVAILABLE and retains its
+actual ownership claims for recovery. Progress uses onProgress; GC does not
+replace the caller's console methods.
+
 doctor returns the doctor --json findings and metadata, with runningPath null
 because the caller imports the library rather than executing a Stim CLI. It
 never repairs the project. By default it does not record a check; record: true
@@ -510,11 +572,20 @@ Expo context uses a settle timer only while an error is pending. The separate
 agent-action cursor and active hosted log queries keep their current sampling.
 
 run takes platform plus its options:
-  ios:     configuration, scheme, deviceType, runtime
+  ios:     configuration, scheme, deviceType, runtime, simulatorApp
   android: variant, systemImage, deviceProfile
-  macos:   remoteBuild
+  macos:   remoteBuild, remote
   web:     headed (default false)
-iOS and Android also accept slot, metroCheck, buildCache, and remoteBuild.
+iOS and Android also accept slot, metroCheck, buildCache, remoteBuild, remote,
+device, wait and easProfile. device: true auto-selects a physical device; a
+string pins its UDID or serial. wait takes seconds as a string, such as '30'.
+wait: false refuses a full owned-device slot immediately; on a physical device
+it bypasses another workspace's lease and can replace its running app, as CLI
+--no-wait does. easProfile downloads an existing compatible development build;
+it never starts an EAS build. iOS simulatorApp selects the simulator viewer.
+remote selects the launch host using the CLI's existing placement and approval
+rules; remoteBuild independently selects where compilation runs. macOS requires
+a named hosting Mac; auto, eas and proxy are not supported there.
 All methods accept signal. run builds, installs and launches.
 Web requires a running server, just like stim web.
 
@@ -543,12 +614,33 @@ writes its own build-artifact-<platform>.ndjson. No distribution archive or web
 pipeline is inferred. Use @stim-cli/ci's buildCI to export a portable artifact and
 diagnostics for your CI provider.
 
+Unresolved native Metro cleanup keeps error.details.cause.retainedClaimRoots and
+STIM_CLAIM_UNAVAILABLE even after cancellation. Web cancellation stops pending
+browser-lock and verification waits. A new browser launch is accounted for and
+stopped before cancellation finishes, or refuses with retained ownership when
+cleanup cannot be confirmed.
+
 run returns { platform, facts }. iOS facts include udid; Android includes
 serial; both include bundleId, appPath, metroPort, cacheHit and launched.
 macOS facts include bundle, bundleId, executable, pid, build and launched.
+A hosted macOS result has a null local pid and preserves true or 'unverified'
+from the host's launch evidence.
 Web facts contain the owned browser's existing launch and page facts.
 Do not interpret 'bundling' or 'unverified' as proven application readiness.
 
+start({ remote?, resetCache?, waitSeconds?, signal?, beforeStart? }) starts or
+reuses the managed dev server, using the same settings and ownership rules as
+stim start. remote requests the configured public URL or tunnel. resetCache
+restarts the server with a cleared transform cache. waitSeconds is a positive
+whole number, defaulting to 60. The flat result is port, supervisorPid, mode,
+logsDir, agentDevice and alreadyRunning.
+beforeStart(workspace) runs once with the resolved app before usage recording
+or effects; throwing refuses startup. Cancellation stops pending probes and lock
+waits, then accounts for new children before returning. A verified supervisor
+handed off to the workspace may remain running. Unconfirmed cleanup refuses with
+STIM_CLAIM_UNAVAILABLE, taking precedence over cancellation or callback failure;
+follow its remedy before retrying. Startup never retries automatically.
+
 reload({ platform?, signal?, beforeReload? }) requests a JavaScript reload in
 the live iOS/Android app or reloads the owned Chrome page. It returns the flat
 stim reload --json facts: platform, deviceId, deviceName, appId, metroPort,
@@ -561,8 +653,11 @@ usage recording or dispatch; throwing refuses the action. Reload uses the
 STIM_REPORT_TIMEOUT and STIM_CLAIM_UNAVAILABLE. Cancellation stops pending
 probes and dispatch, but cannot retract a reload already sent. It never retries.
 
-stop({ slot? }) returns { ok, outcomes, summary }. It acts on the workspace,
-including resources from earlier runs. Use a dedicated workspace in CI.
+stop({ slot?, beforeStop? }) returns { ok, outcomes, summary }. It acts on the
+workspace, including resources from earlier runs. Use a dedicated workspace in CI.
+beforeStop(workspace) runs once with the resolved workspace before teardown;
+throwing refuses the operation.
+From a child directory, start and stop resolve the enclosing supported app.
 Cancellation drains the operation's owned work, a read kills its child
 processes, and both reject with STIM_CANCELLED. Cancelling stop while it waits
 for another native operation ends that wait. Once teardown starts, stop finishes
@@ -3045,6 +3140,8 @@ it retries and scans every 500 ms, with one recovery scan 500 ms after attachmen
 On Windows a moved log directory can require the ten-second repair scan.
 Expo context settling uses a timer only
 while an error is pending; otherwise idle files are not repeatedly scanned.
+Local agent actions also follow their state and claim directories, coalescing file
+changes instead of re-reading every 500 ms while idle.
 While following, hosted targets join and leave from local state notifications.
 Missed notifications are reconciled about every 10 seconds. Active hosts still
 serve bounded log queries.
@@ -4623,7 +4720,8 @@ captured"  (in metro.ndjson, bare RN)
   a changed pin while this workspace's dev server runs or its supervisor
   cannot be verified,
   \`--device\` with an empty
-  serial or UDID, \`--device\` together with \`--remote\`, \`ios --runtime\`
+  serial or UDID, \`--device\` together with \`--remote\` other than
+  \`local\`, \`ios --runtime\`
   on an eas/proxy run (\`--remote\` or ios.remote; that backend picks the
   iOS version), \`ios --device-type\` on the proxy backend or with an
   eas-cli older than 22.2.0 on the eas backend, \`android --system-image\` or
@@ -4693,15 +4791,17 @@ captured"  (in metro.ndjson, bare RN)
   STIM_WORKTREE_REMOVAL_IN_PROGRESS instead.`
 		},
 		STIM_REPORT_TIMEOUT: {
-			summary: "An in-process doctor or GC report exceeded its execution budget",
+			summary: "An in-process report or lifecycle operation exceeded its execution budget",
 			body: () => `STIM_REPORT_TIMEOUT
 
-The doctor() or gc() API read exceeded its 60 second execution budget. Stim
-attempts only that report's cleanup before rejecting, with a 35 second cleanup
-budget. Unfinished cleanup returns STIM_CLAIM_UNAVAILABLE instead.
+An API operation exceeded its execution budget: 90 minutes for warmWorktree(),
+60 seconds for doctor(), gc(), collectGarbage(), reload(), plan() and removeWorktree().
+Stim attempts only that operation's cleanup before rejecting, with a 35 second
+cleanup budget. Unfinished cleanup returns STIM_CLAIM_UNAVAILABLE instead.
 Other clients are unaffected. Retry after the machine is less busy, or narrow
-the report with doctor({ platform }) or gc({ cache }). No GC deletion or idle
-shutdown occurs through these report methods.
+the report with doctor({ platform }) or gc({ cache }). doctor() and gc() remain
+read-only. collectGarbage() can mutate resources; completed actions remain applied.
+Inspect what remains with gc() before retrying a mutation.
 `
 		},
 		STIM_CANCELLED: {
@@ -5222,6 +5322,16 @@ with eas or proxy starts it the way \`stim start --remote\` does. A named
 hosting Mac keeps Metro local through a private bridge; see hosted-ios. Step 2 remains useful to warm
 Metro while other work happens.
 
+Each time Stim boots an owned local simulator or emulator, it mutes it: iOS
+simulators to volume zero through Xcode's devicectl, and Android 15 and later
+emulators to media volume zero. A device that is already running keeps its
+volume. 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.
+
 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
 not part of the normal workflow. It is the explicit recovery path when Fast
@@ -5385,7 +5495,7 @@ WAITING FOR A CHANGE
   repositories, the exit of a recorded supervisor, Metro, build, browser or
   macOS app process (checked every 2 seconds), adb device arrivals and
   departures, and simulator boots, shutdowns, creations and deletions (from
-  CoreSimulator's device set, with a simctl check every 30 seconds), and
+  CoreSimulator's device set and metadata files, with a simctl check every 30 seconds), and
   recomputes every 30 seconds as a fallback. A log append updates the log-derived facts
   within about a second; device activity follows at most every 5 seconds. The
   first line does not wait for git: worktree git summaries can be null in it,
@@ -5522,8 +5632,17 @@ homes. External inputs, directory links, submodules and custom local.properties
 refuse; an SDK-only local.properties stays local. Only declared directories
 reported by AGP and previously produced by this worker remain warm, along with
 worker project .gradle/.kotlin state. Undeclared bytes are removed. Gradle owns
-incremental, task-cache and configuration-cache reuse; transfer digests never
-become reusable APK cache keys. Older hosts refuse before source upload.
+incremental, task-cache and configuration-cache reuse. A transferred
+android.artifactInputs declaration also lets the worker reuse verified APKs under
+its own complete inputs: worker toolchain, signing files and environment values,
+not the caller's. The returned fingerprint remains null; transfer digests never
+become reusable APK cache keys. Workers with native-gradle-peer-cache can offer a
+completed APK for declared source and resolved variant, ABI and build options,
+rechecking current private inputs against the saved receipt at offer and fetch.
+A hit skips source upload and compilation even while that worker is busy or
+this machine has room. A miss follows normal placement; older Gradle workers
+still build normally. Off mode, explicit local builds and disabled remote cache
+reads skip peer lookup. Hosts without native-gradle-build refuse before upload.
 
 outputs must list every build directory of this build's projects that the build
 creates: the root build directory and each module's, library modules included.
@@ -5598,9 +5717,10 @@ android.remote = auto places automatically; see hosted-ios for the shared
 policy. No flag or setting runs on this machine.
 
 A named Mac is strict: refusal, unreachable, declined or failed preparation
-returns STIM_HOSTING_REFUSED without fallback. --device, a different recorded
-machine, a running local owned emulator in the slot, and --no-metro-check for
-hosted Metro development apps refuse STIM_BAD_ARG. Run stim stop before switching placement.
+returns STIM_HOSTING_REFUSED without fallback. --device with --remote
+<machine>, a different recorded machine, a running local owned emulator in
+the slot, and --no-metro-check for hosted Metro development apps refuse
+STIM_BAD_ARG. Run stim stop before switching placement.
 Unreadable android.host blocks only its slot; restore its recorded machine and
 session from the host before stopping that slot.
 
@@ -5792,7 +5912,8 @@ A reserve refusal after a successful offer can race with another run. It fails
 with STIM_HOSTING_REFUSED naming the host and asking to retry. Stim does not
 try the next host or local placement after the build has targeted that host's
 architecture, and never falls back once a hosted session exists. A named machine remains strict. --device
-cannot combine with auto. eas/proxy and macOS placement are unchanged.
+cannot combine with --remote auto, and a --device run ignores ios.remote and
+android.remote. eas/proxy and macOS placement are unchanged.
 --simulator-app is honoured locally with auto and ignored with a note on a host.
 Placement measures budgets without reclaiming; only a new local run reclaims.
 Android --remote <machine> uses an owned emulator on that Mac; see hosted-android.
@@ -6776,8 +6897,8 @@ THE BUILD CACHE HAS THREE LEVELS
      @stim-cli/cache contract (see \`guide settings\`). Consulted only when
      level one misses, and its hit is stored into level one before install.
      The same contract serves the Metro transform cache.
-  3. On an EXPO project only, the provider the project ALREADY configured for
-     Expo (\`expo.buildCacheProvider\` -- "eas", or a module of its own).
+  3. On an EXPO project only, EAS when the project configures it through
+     Expo (\`expo.buildCacheProvider\` -- "eas").
      Consulted only when levels one and two miss, bounded so a slow or expired
      remote cannot stall the loop, and a hit is copied into level one on the
      way past so the next workspace on this machine gets it for free. After a
@@ -7288,6 +7409,8 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   install requires an exclusive claim. It releases shared before waiting for
   exclusive, then checks the checkout again before fetching or writing. Every
   copy holds shared, so no copy reads a node_modules a refresh is rewriting.
+  Each copy also holds an exclusive claim on its target, so concurrent warms
+  into the same linked worktree wait instead of racing destination checks.
   The lock is keyed on the repository root, so
   two apps of one monorepo share it. It is the same ownership claim the build
   locks take: the holder's process IDENTITY decides, so a holder that dies frees
@@ -7369,8 +7492,9 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   filled in. Warm does not copy tracked changes, switch branches, or build,
   and it installs dependencies only under \`--refresh\`, in the source checkout. stdout stays empty; stderr reports copied, kept,
   and failed entry counts. A copy failure exits 1 and reports incomplete;
-  files copied before a failure remain. Inspect the named failed entry
-  before retrying: a partially copied directory will be kept on the retry.
+  completed entries remain. After its child drains, warm removes its own
+  failed partial entry so a retry can copy it again. Unverifiable child cleanup
+  leaves that entry and its ownership claims in place with recovery instructions.
   A completed copy is not proof that dependencies match this branch. Follow
   any lockfile remedies before building, and install missing dependencies
   with the project's package manager when the source has none to copy.
@@ -7459,7 +7583,8 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
 			body: () => `  \`android --device [serial]\` installs and launches on a physical device
   connected to this machine instead of this workspace's owned emulator. With
   no serial it takes the first device it can lease (\`guide lifecycle lease\`).
-  It cannot be combined with --remote.
+  It ignores android.remote and cannot be combined with --remote other than
+  --remote local.
 
   A \`--device\` run LEASES the device from just after the build until it
   exits, so a second workspace cannot install over it mid-run
@@ -7475,7 +7600,8 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   \`android --device\` selects a connected phone: with no UDID it takes the
   first device it can lease (\`guide lifecycle lease\`), and an iPhone
   that is unpaired or has Developer Mode off is refused with the fix. It
-  cannot be combined with --remote, and it never creates, boots, or deletes
+  ignores ios.remote, cannot be combined with --remote other than --remote
+  local, and never creates, boots, or deletes
   hardware -- there is no capacity check, no simulator creation, no boot wait,
   and no owned-device registry entry. Like
   \`android --device\`, it leases the phone for the run
@@ -8643,6 +8769,12 @@ run drops the dead config ENTRIES those projects left behind and frees their
 Metro ports. \`stim gc --json\` prints the same report as one payload
 (\`guide facts gc\`); show the user its sections before \`gc --delete\`.
 
+Ctrl-C stops pending GC actions and drains verified owned children before exiting
+130. Completed actions remain applied. Unverifiable child cleanup keeps its
+ownership claims and prints STIM_CLAIM_UNAVAILABLE with a recovery remedy.
+With --json, cancellation prints one STIM_CANCELLED payload, or the cleanup
+refusal when cleanup cannot be verified.
+
 REMOTE EAS SESSIONS
   Plain \`stim gc\` is a dry run. \`gc --delete\` can stop active stim-* EAS
   sessions after workspace state is missing. The stop needs verified
@@ -9103,7 +9235,8 @@ KEYS STIM READS
                         remote.machines, with the same meaning as --remote.
                         "auto" places on an approved Mac when this machine is full or
                         busy. Unset runs here; "local" runs here even when a
-                        lower layer says otherwise. See lifecycle hosted-ios.
+                        lower layer says otherwise. A --device run ignores
+                        it. See lifecycle hosted-ios.
   ios.projectPath       directory under the app holding a bare React Native
                         app's Xcode project and Podfile; default "ios". "."
                         is the app directory itself (RNTester's layout).
@@ -9294,7 +9427,7 @@ ${ANDROID_AVD_CONFIG_HELP.map((line) => `                          ${line}`).joi
                         build. outputs names generated directories reported
                         by AGP; recorded outputs can survive worker sync.
                         Omitted optional inputs can change build results.
-                        Worker APKs remain uncached. See
+                        Worker APK caching also requires artifactInputs. See
                         \`stim guide lifecycle native-android\` for input,
                         privacy and worker requirements.
   android.keystore      the keystore a RE-PACKED release APK is signed with,
@@ -9321,7 +9454,8 @@ ${ANDROID_AVD_CONFIG_HELP.map((line) => `                          ${line}`).joi
                         remote.machines; "auto" places on an approved Mac when
                         this machine is full or busy. Unset runs here; "local"
                         runs here even when a lower layer says otherwise.
-                        See lifecycle hosted-android.
+                        A --device run ignores it. See lifecycle
+                        hosted-android.
   remote.easFallback    true lets "auto" (ios.remote, android.remote or
                         --remote auto) run the simulator or emulator on a
                         billed EAS Simulator when this machine is at its
@@ -9436,6 +9570,8 @@ ${ANDROID_AVD_CONFIG_HELP.map((line) => `                          ${line}`).joi
                         Debug by stim macos
   macos.infoPlist       development Info.plist relative to Package.swift,
                         without shared URL schemes or an update feed
+  macos.artifactInputs  complete pinned, repeatable inputs producing a relocatable
+                        app for completed build caching. See stim guide macos.
   macos.arguments       string array passed directly to the executable;
                         see stim guide macos for the prototype's limits
   macos.assetCatalog    optional .xcassets directory relative to Package.swift,
@@ -9899,6 +10035,12 @@ emulator debug build or a stim macos SwiftPM Debug build compiles:
   force  on a remote machine whenever one accepts it
   off    here when local remains enabled in the automatic build pool
 
+For React Native and Expo, among machines that can take a new build, a matching dependency installation
+ranks before load. The worker checks the requested project, lockfile and install
+arguments, and verifies that its modules and install marker remain present.
+Older workers' dependency hints and mere checkout or build-folder presence do
+not influence this ranking. Exact completed-artifact hits still come first.
+
 Load per core is the 5-minute load average divided by the CPU count; a machine's
 native builds are its Stim runs in prebuild, pods or compile on that machine, not
 the ones it offloaded.
@@ -9913,7 +10055,8 @@ Debug builds can use a separate --remote-build, targeting the hosting Mac's
 architecture and runtime.
 macOS uses matching Xcode and macOS SDK, with a per-client SwiftPM dependency
 cache on the worker. It skips JavaScript dependencies, prebuild and pods; see
-stim guide macos. macOS artifacts are not cached.
+stim guide macos. Completed caching requires macos.artifactInputs and a locally
+verified compile; remote output is not published under an unverified client key.
 An offloaded iOS/Android build first runs prebuild (and \`pod install\` for iOS) here,
 then asks every paired machine what it can build. It takes one whose Stim
 build matches this Mac and, for iOS and macOS, CPU matches the target simulator, with enough disk, that does not decline,
@@ -9926,7 +10069,17 @@ includes source, Xcode, SDK, architecture and target options. A hit skips sync
 and compilation even while the worker is busy or this machine has room. Missing or
 corrupt archives follow normal placement. Off mode and an explicit local build
 do not query peer caches. Older workers continue normal placement. This peer
-lookup covers native Xcode worker artifacts, not compiler or dependency caches.
+lookup also covers declared native Gradle worker APKs when the worker supports
+native-gradle-peer-cache. It rechecks current private inputs against the saved
+receipt at offer and fetch for the requested source, resolved variant, ABI and
+build options. Caller fingerprints stay null; worker keys stay worker-scoped.
+React Native and Expo development builds also query enabled paired workers
+with react-native-peer-cache after local and configured-provider misses. Their
+post-mutation fingerprint, native build choices and compatible toolchain must
+match. Completed archives survive worker checkout changes or removal; hits
+need no source upload or build slot. Disabled remote artifact reads skip this
+lookup. Release and physical-device builds keep their existing paths.
+SwiftPM, compiler and dependency caches use their existing paths.
 For iOS the machine's Xcode and simulator SDK must match, and it needs an
 iPhone simulator on the target runtime. Its project-selected CocoaPods must match too, unless
 the app's Gemfile.lock pins CocoaPods: both machines then run that version through
@@ -10135,6 +10288,8 @@ The example shows the defaults. Full setting names and behavior:
     Install @stim-cli/cache-s3 and select it through cache.provider for S3-compatible storage,
     including Cloudflare R2, or configure another provider through Expo.
     Stim does not run a hosted cache service; credentials use the AWS SDK chain.
+    S3 file uploads retry connection resets up to three PUT attempts, reopening
+    the completed file each time. Cancellation also stops the retry delays.
   optimizations.releaseBundleSwap
     false always builds Release from source, including the current JS;
     it never installs an old embedded bundle. Fresh artifacts can still store.
@@ -10598,24 +10753,65 @@ changing focus: it sets STIM_BACKGROUND_LAUNCH=1 in the app's environment, which
 Stim Desktop honors, including for reopen events from open -g. An app that
 activates itself at launch or on reopen still takes focus.
 Hosted launches (macos --remote) do not set it.
-macOS artifacts are not cached. This prototype has no --slot or reload command.
+This prototype has no --slot or reload command.
+Completed app caching is opt-in with macos.artifactInputs:
+
+  { "macos": { "artifactInputs": { "complete": true,
+      "ignored": [], "outputs": [], "localFiles": [], "environment": [] } } }
+
+complete declares pinned, repeatable build inputs and an app that runs after its
+original checkout and scratch directory are gone. Do not enable it for mutable
+dependencies, build-time network data, undeclared environment or local inputs,
+or code that needs its original absolute source paths (including #filePath).
+Stim hashes Git-visible repository source, Package.resolved even when ignored,
+the development plist, declared resources, Swift/Xcode/SDK identity and CPU
+architecture. ignored names exact Git-ignored repository-relative input files;
+outputs names generated repository-relative directories already ignored by Git.
+localFiles names exact additional private files, relative to the package or
+absolute; environment names additional build-time variables. Values and private
+file contents are hashed locally and are not included in the shared receipt.
+Symbolic links in source inventories are currently ineligible for caching.
+Without a valid declaration Stim compiles normally and keeps SwiftPM incremental
+reuse. optimizations.buildCache and optimizations.remoteBuildCache also apply.
+The completed bundle uses the ordinary shared build cache and an optional
+cache.provider's files capability, including S3. A hit avoids compiler slots and
+placement, then gets this workspace's identifier and name on a re-signed copy.
+Corrupt or incompatible entries fall back to compilation. Inputs changed during
+compilation prevent publication. Compiler and package scratch state is not shared.
+An enabled paired worker with swiftpm-peer-cache can retain a completed archive
+after verifying its actual source, private inputs and toolchain before and after
+compilation. After local/provider misses, an exact peer hit skips source upload
+and compiler admission, even while that worker is busy. Private values stay on
+the worker; its opaque identity is not used as this Mac's local cache key.
+Ignored bundle files must be declared in ignored or localFiles for peer reuse.
+The worker rechecks private inputs before offer and fetch; deleting its checkout
+does not discard an archive whose private inputs remain valid. Toolchain versions and command selection are
+checked from the package directory. After checkout removal, only verified direct
+Apple Swift, xcrun and xcodebuild selections can be reproduced; custom launchers
+require the checkout and otherwise miss safely. SWIFT_EXEC and SWIFT_EXEC_MANIFEST
+compiler overrides are resolved and versioned separately and require the checkout.
+The SDK selected by SDKROOT or SWIFTPM_SDKROOT_macosx is checked by real path and build version. Explicit local placement,
+remote build mode off, disabled pool members and remoteBuildCache
+false skip peer lookup. Older workers keep their normal compilation path.
 --plan validates the Swift Package directory, macos settings, development plist
-and declared resources without building, signing, staging, stopping or launching
+and declared resources without building, signing, stopping or launching
 an app, writing workspace state or claiming a build slot. It does not execute
 Package.swift, so it cannot validate the executable product or package dependencies.
 --remote-build is respected, including named-machine setup refusals; no worker
 is contacted and live worker availability is unknown. --remote is launch-only
 and refuses with --plan. The JSON plan has platform "macos", product and
-buildMachine; fingerprint, cacheKey, provider, prebuild, outcome and expectedMs
-are null, cacheHit and cacheSkipped are false, and basis is 0. SwiftPM decides
-incremental compile work when a build runs; the plan predicts no cache outcome
-or duration. Desktop checks automatically while build details are visible,
+buildMachine. An eligible cache identity supplies fingerprint and cacheKey;
+cacheHit reports a verified local completed artifact, checked in a disposable
+temporary copy. Providers and workers are not contacted. cacheSkipped is true
+when artifact caching is disabled or ineligible. provider, prebuild, outcome
+and expectedMs remain null, and basis is 0. SwiftPM decides incremental compile
+work when a build runs; the plan predicts no duration. Desktop checks automatically while build details are visible,
 reusing a completed build or check for 60 seconds and skipping running builds.
 A failed build records its error and compiler output without launching an app.
 While it runs, stim status --json reports it as environments[].build with
 platform "macos": phase prepare, compile, install, then launch, and during
 compile detail.unit "steps" with SwiftPM's [done / total] counts (fetching and
-planning are detail.step "configure"). It has no cache lookup, so outcome and
+planning are detail.step "configure"). outcome and
 plannedPhases are null; finished runs and their phase times are in
 environments[].builds.macos, where phases includes launch once the launch step finishes
 and compileSteps is SwiftPM's step total. An offloaded build reports the worker's

package/dist/{hosted-android-Bw-honsd.mjs → hosted-android-B-9f-jkd.mjs}

@@ -1,7 +1,7 @@
-import { en as throwIfCancelled } from "./settings-CsJDEXgK.mjs";
-import { c as call, l as connectHost } from "./hosted-client-DB_gBPfY.mjs";
-import { i as requestHostedMetro } from "./metro-gateway-BMJNlj3E.mjs";
-import { n as prepareHostedNative, r as stopHostedNative, t as placeHostedNative } from "./hosted-native-Ksyjgzq-.mjs";
+import { f as throwIfCancelled } from "./operation-exec-BW0em61G.mjs";
+import { c as call, l as connectHost } from "./hosted-client-DZAPrcro.mjs";
+import { i as requestHostedMetro } from "./metro-gateway-CKZqKqx7.mjs";
+import { n as prepareHostedNative, r as stopHostedNative, t as placeHostedNative } from "./hosted-native-BdzE668-.mjs";
 //#region src/device-host/hosted-android.ts
 async function prepareHostedAndroid(machine, selectors, recorded, mode) {
 	return await prepareHostedNative(machine, selectors, recorded, "android", false, mode);
@@ -13,8 +13,8 @@ async function placeHostedAndroid(target, options) {
 		reserved: (placement) => options.reserved(placement)
 	});
 }
-async function stopHostedAndroid(root, slot) {
-	await stopHostedNative(root, slot, "android");
+async function stopHostedAndroid(root, slot, signal) {
+	await stopHostedNative(root, slot, signal, "android");
 }
 async function reopenHostedAndroidMetro(root, placement, clientMetroPort, signal) {
 	const host = await connectHost(placement.machine, void 0, true, signal);

package/dist/{hosted-client-DB_gBPfY.mjs → hosted-client-DZAPrcro.mjs}

@@ -1,7 +1,7 @@
-import { it as resolveEndpoint } from "./config-CYcBF478.mjs";
-import { Qt as cancellableSleep, en as throwIfCancelled } from "./settings-CsJDEXgK.mjs";
-import { t as BuildConnection } from "./client-UXD70ZbM.mjs";
-import { u as configuredMachines } from "./selection-CSl9i5qU.mjs";
+import { rt as resolveEndpoint } from "./config-DlrsduwG.mjs";
+import { f as throwIfCancelled, u as cancellableSleep } from "./operation-exec-BW0em61G.mjs";
+import { t as BuildConnection } from "./client-OyRoEuSr.mjs";
+import { u as configuredMachines } from "./selection-DSMbWEX2.mjs";
 import { createHash } from "node:crypto";
 import { lstatSync, readFileSync, readdirSync, readlinkSync } from "node:fs";
 import { join } from "node:path";

package/dist/{hosted-ios-CUvOf4Vr.mjs → hosted-ios-CsCS21hn.mjs}

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

package/dist/{hosted-logs-DL_P5AdN.mjs → hosted-logs-FIRx9X2f.mjs}

@@ -1,10 +1,10 @@
-import { t as getExecutor } from "./exec-_UbtCQcG.mjs";
+import { t as getExecutor } from "./exec-DEoAhcze.mjs";
 import { d as workspaceDir, m as workspaceLogsDir$1 } from "./paths-DQtTgsBf.mjs";
-import { J as validateDeviceSlot, V as deviceSlotFileKey, tt as parseMachine$1 } from "./config-CYcBF478.mjs";
-import { l as phaseLine } from "./command-output-B1UrjZHL.mjs";
-import { n as macosDir } from "./state-XMziexv2.mjs";
+import { B as deviceSlotFileKey, et as parseMachine$1, q as validateDeviceSlot } from "./config-DlrsduwG.mjs";
+import { l as phaseLine } from "./command-output-gwpm28fu.mjs";
+import { n as macosDir } from "./state-08I3hw3_.mjs";
 import { r as createNdjsonWriter } from "./ndjson-CgE_o3Dl.mjs";
-import { c as call } from "./hosted-client-DB_gBPfY.mjs";
+import { c as call } from "./hosted-client-DZAPrcro.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";