stim 1.8.0 → 1.9.0

package/README.md

@@ -8,8 +8,8 @@ keep native and JavaScript builds warm across worktrees.
 
 ## Install
 
-If you previously installed `stim-cli` globally, follow the
-[migration instructions](#migrating-from-stim-cli) first.
+Node 22.12.0 or later is required. If you previously installed `stim-cli`
+globally, follow the [migration instructions](#migrating-from-stim-cli) first.
 
 ```bash
 npm install --global stim
@@ -22,18 +22,6 @@ Run without a global install when needed:
 npx stim <command>
 ```
 
-Node 22.12.0 or later is required.
-
-Machine defaults in `~/.stim/config.json` can enable or disable native artifact
-caching, remote caches, Metro sharing, iOS compiler caching and prefix mapping,
-and Android ccache/CAS, PCH, Gradle caching, and target ABI narrowing. The
-top-level `iosSimulatorApp` setting selects Xcode's viewer or an installed
-Siniulator.
-`.stim.json` runtime overrides apply per app, beside its `package.json`; monorepo
-apps do not inherit the repository-root file. Worktree-copy rules stay at the
-repository root. Run `stim guide settings` for the
-`optimizations` schema; existing defaults remain unchanged.
-
 ## Normal workflow
 
 ```bash
@@ -44,115 +32,29 @@ stim logs --errors
 stim stop
 ```
 
-For `stim logs --errors`, a clean check requires exit code 0 and no matching
-errors in the captured logs. Exit code 0 alone means the query succeeded, even
-when it prints errors. A workspace that has never produced a log timeline
-refuses with `STIM_NO_PROJECT`; in a monorepo, the error names the nearest
-registered descendant app with logs when one exists.
-
-Use `stim start --reset-cache` to recover from stale Metro transforms or file-map
-state. It restarts only this app's verified owned Metro, keeping its port and
-devices, with Metro's own reset: every store in the app's Metro config is cleared,
-including this app's shared transform store, so other worktrees of the same app
-rebuild their transforms too. Other apps and native build caches are unchanged.
-
-Use `stim doctor --platform ios` or `stim doctor --platform android` when only
-one native platform is in scope; shared project checks still run. Doctor also
-prints the running CLI version and the `stim` installation resolved from PATH,
-and flags a resolved installation that is older than another available one.
-
-For parallel iOS work, SimSlim is recommended as an optional way to reduce
-simulator background services and memory use. Run `stim guide lifecycle simslim`
-to review the service tradeoffs and configure a profile. Doctor recommends the
-setup without installing or enabling it. When a simulator cannot start
-processes, Stim bounds the wait and reports observed host memory pressure when
-available; free memory before retrying. A timeout alone does not prove OOM.
-
-For stale Android CMake launcher findings, stop native builds and run
-`stim doctor --fix --platform android` in the affected checkout. It clears
-affected ignored, untracked generated `.cxx` configurations in the app and
-installed native modules, then reports remaining findings. The next build
-recreates that output; source files, custom launcher settings, and shared
-ccache entries are preserved. Its cache-lock check cannot detect uncached,
-release-swap fallback, or direct Gradle builds; stop all native builds first.
-
 Stim builds or restores the app, installs it, launches it, and checks launch
 readiness. Plain output streams progress and reports the complete result. Use
 `--json` when a script needs structured data.
 
-To use an existing EAS development build, run `stim ios --eas-profile ios-simulator`
-or `stim android --eas-profile development` with your project's profile name.
-The profile must be an internal development build. Add `--device` for a connected
-phone; iOS requires `ios.simulator: true` for a simulator and false for a phone.
-Stim downloads a matching native build and connects it to the workspace's Metro.
-EAS CLI manages the downloaded artifact cache. An iOS provisioning failure
-points to EAS device registration and rebuild commands.
-On a miss it stops and prints the EAS build command, which may incur charges;
-it never triggers the build automatically. See `stim guide lifecycle eas` for
-setup, environment handling, and cache behavior.
-
-Use `stim ios --scheme "App Staging"` when a project has several shared Xcode
-app schemes. Combine it with `--configuration Release` if needed. Without the
-flag, Stim keeps its automatic scheme selection. Explicit schemes use separate
-artifact caches and Xcode build directories; run `stim guide lifecycle builds`
-for provider behavior. This selects an Xcode scheme, not a URL scheme.
-
-Launch evidence does not prove that the UI is interactive. Apps can optionally
-[declare readiness with two debug log messages](https://stim.appandflow.com/docs/dev-server-and-logs#optional-app-declared-readiness),
-without a package or SDK. A captured pending message extends the default
-three-second stability window after bundle delivery to a bounded wait for ready.
-Managed Metro response capture distinguishes a finished build from a finished
-response; servers without capture use the build-complete marker. Run
-`stim guide lifecycle readiness` for implementation instructions; verify the
-expected screen separately.
-
-`stim reload [ios|android]` requests a JavaScript reload in the live app on this
-workspace's owned local device. Use it when an error screen remains after a fix,
-and on Android after a failed first bundle load. An iOS app whose first bundle
-failed never connects to Metro, so reload cannot reach it. It reloads
-JavaScript and never restarts the app. It is not part of the normal workflow
-and does not build, install, boot, or launch an app. The platform is optional
-when only one app is live.
-Success confirms that the request was sent; Stim does not observe completion.
-Verify the expected UI on the reported device and inspect `stim logs --errors`
-before claiming recovery.
-
-For an isolated branch, create the worktree with Git, then warm it:
-
-```bash
-git worktree add -b feature/settings ../feature-settings HEAD
-cd ../feature-settings
-stim worktree warm
-```
-
-If a harness already created the linked worktree, run only `stim worktree warm`
-there. Warm copies missing ignored state from the source checkout, including
-eligible `.env` and local configuration files. Existing entries are preserved;
-existing ignored directories such as `node_modules` are skipped whole.
-
-`stim worktree warm --refresh` brings the source checkout up to date first: it
-checks the upstream, fetches changes when needed, fast-forwards whatever branch is checked out there, and installs what
-the new commits moved before copying. It refuses a source checkout it cannot
-move (uncommitted tracked changes, a rebase or merge in progress, a detached
-HEAD, a diverged branch) and never switches branches. One lock per repository
-keeps a copy from reading a `node_modules` a refresh is rewriting; plain warms
-still run side by side. A plain warm also refuses (`STIM_DEPS_INCOMPLETE`) when the last
-install of the lockfile on disk did not finish, instead of copying a partial
-`node_modules`; `stim worktree warm --refresh` reinstalls it.
-
-Wait for warm to finish before editing, installing dependencies, starting
-Metro/builds, or running another warm in that worktree. Concurrent writes are
-unsafe: entries created after the initial check can be overwritten or removed.
-
-After the work is preserved, `stim worktree remove` removes any linked
-worktree, warmed or not. Git-created branches stay. See the
-[worktree guide](https://stim.appandflow.com/docs/worktrees) for exclusions
-and cleanup rules.
-
-## Reference
-
-The [documentation website](https://stim.appandflow.com/) explains the
-human workflow and all commands.
+## Documentation
+
+The [documentation website](https://stim.appandflow.com/) is the full
+reference:
+
+- [Getting started](https://stim.appandflow.com/docs/getting-started): terms,
+  the first run, parallel worktrees, and what to do when a run fails.
+- [Worktrees](https://stim.appandflow.com/docs/worktrees): `worktree warm`,
+  `--refresh`, `worktree remove`, and `gc --worktrees` to remove finished
+  worktrees in bulk.
+- [Build caches](https://stim.appandflow.com/docs/build-caches): what `gc`
+  reports and trims, including the build outputs of idle workspaces.
+- [Devices](https://stim.appandflow.com/docs/owned-devices): owned simulators
+  and emulators, physical devices, slots, and remote devices.
+- [EAS development builds](https://stim.appandflow.com/docs/eas-builds).
+- [Commands](https://stim.appandflow.com/docs/commands) and
+  [settings](https://stim.appandflow.com/docs/settings).
+- [Troubleshooting](https://stim.appandflow.com/docs/troubleshooting): every
+  refusal code and its remedy.
 
 The installed CLI contains version-matched operational guidance:
 
@@ -163,10 +65,6 @@ stim <command> --help
 stim guide
 ```
 
-Runtime state defaults to `~/.stim`. Set `STIM_HOME` to move it. Stim manages
-owned simulators and emulators, leases connected physical devices, and supports
-configured remote devices.
-
 ## Migrating from stim-cli
 
 Remove the old global package before installing `stim`, since both provide the
@@ -180,36 +78,6 @@ npm install --global stim
 Update programmatic imports from `stim-cli/cache-manifest` to
 `stim/cache-manifest`. The `@stim-cli/*` packages keep their names.
 
-MIT License.
-
-### Multiple devices in one workspace
-
-Use a stable slot name for each simulator, emulator, or physical device. Slots
-can use identical models and all share the workspace's Metro server and build
-cache. Omit `--slot` to reuse your existing default device.
-
-```sh
-stim ios --slot phone
-stim ios --slot tablet --device-type "iPad Pro 13-inch (M4)"
-stim ios --slot hardware --device <udid>
-stim logs --slot tablet --source device
-stim stop --slot tablet
-```
+## License
 
-`stim status` shows every slot. Plain `stim stop` stops the whole workspace;
-`--slot` preserves the shared server and other devices. `stim reload ios` or
-`stim reload android` can reload multiple connected devices. Read
-`stim guide lifecycle options` for launch verification and recycling behavior.
-
-### Named server ports
-
-Use `stim ports get web` to reserve a workspace port for a server Stim does not
-manage, then pass that number to the server, for example
-`pnpm exec vite --port "$(stim ports get web)" --strictPort`.
-`stim ports` lists named allocations and managed Metro. `stim ports stop web`
-stops the TCP listener and releases its port; `--dry-run` previews the action.
-`stim ports release web` releases without stopping. Omitting the label selects
-all named ports. These commands leave Metro alone, and `stim stop` leaves
-named ports alone. Worktree removal and `gc --delete` stop and release named
-ports for removed workspaces. Read `stim guide ports` for the reserved band,
-listener ownership, and allocation limits.
+MIT

package/dist/{android-BRgBYzU0.mjs → android-BPGizezh.mjs}

@@ -1,37 +1,38 @@
-import { t as getExecutor } from "./exec-B29XNuhP.mjs";
-import { B as validateDeviceSlot, C as withConfigLock, E as ownership_claim_exports, F as deviceSlotKey, I as deviceSlotPlatforms, P as deviceSlotFileKey, S as upsertProject, b as setDevice, f as getProject, g as loadConfig, l as getConcurrencyLimits, y as saveConfig } from "./config-B7iyKWkL.mjs";
-import { r as createNdjsonWriter } from "./ndjson-BZwI1NBv.mjs";
-import { _ as workspaceLogsDir, h as workspaceDir, o as writeWorkspaceState, r as readWorkspaceState, s as emulatorLogFile } from "./workspace-state-BT5E3SA2.mjs";
-import { T as removeTemporaryEntry, g as repoRoot, s as gitCommonDir, w as makeTemporaryDirectory } from "./worktree-FG_ZKKdb.mjs";
-import { a as findProjectRoot, c as projectShortcut, i as detectIsExpo, n as detectAndroidPackage, r as detectBundleId, t as appProjectProblem } from "./project-DDZWf_16.mjs";
-import { n as MODE_EXPO, p as writeWorkspaceLaunch, t as MODE_BARE } from "./state-DZobzxLW.mjs";
-import { r as waitForChild, t as createLineReader } from "./process-output-Dl5uKE03.mjs";
-import { a as resolveProjectMetro, i as pidExists, o as signalProcessTree } from "./metro-C7bcJ0uo.mjs";
-import { n as verifyCollectorOwnership, r as readCollectors } from "./ownership-Cp52QAK1.mjs";
-import { A as resolveSettings, B as artifactCachePolicy, D as remoteDeviceSettingError, E as remoteAndroidSetting, F as tunnelModeSetting, H as optimizationBuildProfile, I as unknownSettingKeys, N as settingShapeErrors, R as detectProviders, T as publicUrlSetting, U as resolveOptimizations, V as compilerCacheFallbackMessage, a as SETTING_SHAPE_REMEDY, d as cacheProviderSettingError, j as settingFile, k as resolveCacheProviderConfig, r as REMOTE_DEVICE_BACKENDS, s as androidAvdConfigSettingError, u as androidDataPartitionSizeGbSettingError, x as metroWarmupUrlSetting } from "./settings-BXXorVM2.mjs";
-import { B as waitForBoot, E as memoizeEmulatorProbe, F as resetAdoptedAvd, I as resolveOwnedAvdSerial, L as resolvePhysicalDevice, M as physicalDeviceModel, P as probeEmulatorSerial, S as listAdbDevices, _ as emulatorFailureRemedy, a as androidPoolNoCandidatesRefusal, g as emulatorDiskSpaceRemedy, i as androidPoolCandidates, n as androidDeviceAbi, o as androidSystemImageAbi, r as androidHome, s as androidToolCwd, t as androidBuildToolName, v as extractEmulatorFailure, w as listInstalledSystemImages, y as findBuildTool } from "./android-DWssqHQ8.mjs";
-import { _ as launchErrorPreview, c as launchErrorReport, g as stepTimer, h as stepClock, i as formatDuration, l as phaseLine, n as appReadinessMessage, p as shortHash } from "./command-output-B3ycpsYv.mjs";
-import { C as untrackedNativeFiles, D as readAssetManifest, E as compareAssetManifests, S as untrackedMissLine, T as captureAssetManifest, _ as providerUploadOutcome, b as storeBuild, c as buildCacheKey, d as filesystemBuildCapability, f as fingerprintDiffRecord, g as providerDownloadPath, h as prepareProviderDownloadDir, i as releaseBuildLock, l as describeFingerprintMiss, m as fingerprintProject, n as acquireBuildLock, o as takeoverLine, p as fingerprintDiffSuffix, s as waitForBuild, t as WAIT_CEILING_MS, v as refingerprintAfterMutation, w as assetDiffReason, x as storedAssetManifest, y as resolveBuild } from "./build-lock-CgtsB6TV.mjs";
-import { t as cleanLine } from "./server-expo-BVAA1OqJ.mjs";
-import { C as resolveRemote, S as resolveEasCliBin, _ as exitAfterFlush, f as RESOLVE_TIMEOUT_MS, g as easAuthNote, h as checkEasAuth, l as parkedMaxSetting, m as cacheLevel, p as UPLOAD_TIMEOUT_MS, v as isEasAuthFailureText, w as uploadRemote, y as loadProjectProvider } from "./teardown-BJqEzPo_.mjs";
-import { c as ensureWorkspaceStorageSafely, d as launchOutcomeRecord, f as noMetroMessage, g as warmMetro, i as detectEntryFile, m as resolveMetroWithRetry, n as pickDevClientScheme, o as needsPrebuild, p as noMetroRemedy, s as runPrebuild, t as devClientScheme, u as isPhysicalDeviceRequest, v as isEasBuildFailure, y as resolveEasDevelopmentBuild } from "./dev-client-BmT-ioFI.mjs";
-import { t as withWorkspaceProcessLock } from "./workspace-process-lock-BYfZz_S-.mjs";
-import { D as verifyAndroidReleaseLaunch, E as unverifiedLaunchLines, O as verifyLaunch, S as launchAndroidReleaseApp, _ as installConflictKind, c as RELEASE_VERIFY_WAIT_MS, d as androidDevClientUrl, g as installAndroidApp, h as deviceShellArg, i as LAUNCH_BUNDLING, l as VERIFY_TIMEOUT_MS, n as DEFAULT_METRO_PORT, o as LAUNCH_FATAL, s as LAUNCH_UNVERIFIED, t as ADB_INSTALL_TIMEOUT_MS, u as androidAppProcess, x as launchAndroidApp } from "./app-install-BDbsSgCl.mjs";
-import { a as lostLine, c as releaseLeaseOnSignal, i as leaseExpiryText, l as runLease, n as DEBUG_VERIFY_STEP_MS, o as lostRefusal, r as acquireRunLease, s as parseDeviceWait, t as selectFromPool, u as waitFlagConflict } from "./device-pool-BxRwdufO.mjs";
-import { r as releaseBuildSlot, t as acquireBuildSlot } from "./build-slots-C-oAHRT1.mjs";
-import { a as statsProjectKey, i as recordRunStats, n as readRunEstimates, t as createRunRecorder } from "./stats-BYcZ6n1h.mjs";
-import { i as ensureOwnedDevice, l as AvdBootError, o as unknownAndroidSystemImageRefusal, r as ensureBooted, t as checkDeviceCapacity, u as AvdRecoveryError } from "./device-BUoZyMoR.mjs";
-import { a as ensureMetroReachable, b as ownedSessionName, l as resolveRemoteContext, n as binOnPath, o as ensureRemoteBootOwned, s as remoteAndroidDeps } from "./device-remote-ByN8P6CB.mjs";
-import { a as buildAndroid, c as CCACHE_NOT_RUN, f as resolveCcache, l as CCACHE_UNAVAILABLE, n as resolveAndroidCas, o as productFlavorRefusal, p as formatDiagnostic, r as resolveAndroidCompilerCache, s as readProductFlavors, u as ccacheActivityLine } from "./android-cas-SWIjzeuL.mjs";
-import { d as startBuildHeartbeat, f as tailLines, n as HEARTBEAT_INTERVAL_MS } from "./xcode-B6YaWeg0.mjs";
-import { n as nativeRunCommand, t as launchSlotScope } from "./slot-launch-ZUUe0TQP.mjs";
+import { G as parseDeviceSlotOption, H as deviceSlotKey, J as validateDeviceSlot, S as setDevice, T as withConfigLock, U as deviceSlotPlatforms, V as deviceSlotFileKey, f as getProject, g as loadConfig, k as ownership_claim_exports, l as getConcurrencyLimits, w as upsertProject, x as saveConfig } from "./config-Cp9lM3wX.mjs";
+import { t as getExecutor } from "./exec-jIAlgilk.mjs";
+import { r as createNdjsonWriter } from "./ndjson-9uFNRwfe.mjs";
+import { _ as workspaceDir, b as workspaceLogsDir, c as writeWorkspaceState, i as recordWorkspaceUse, l as emulatorLogFile, r as readWorkspaceState } from "./workspace-state-DF2gCFhx.mjs";
+import { E as removeTemporaryEntry, T as makeTemporaryDirectory, _ as repoRoot, s as gitCommonDir } from "./worktree-R_cUlE7s.mjs";
+import { a as detectIsExpo, i as detectBundleId, l as projectShortcut, n as appProjectProblem, o as findProjectRoot, r as detectAndroidPackage } from "./project-DS112DYB.mjs";
+import { n as MODE_EXPO, p as writeWorkspaceLaunch, t as MODE_BARE } from "./state-NcJzMEBF.mjs";
+import { r as waitForChild, t as createLineReader } from "./process-output-Fpl8PYi8.mjs";
+import { a as pidExists, c as resolveProjectMetro, l as signalProcessTree } from "./metro-DrLHaMn2.mjs";
+import { n as verifyCollectorOwnership, r as readCollectors } from "./ownership-D15Op8vN.mjs";
+import { A as settingFile, E as remoteAndroidSetting, F as unknownSettingKeys, J as optimizationBuildProfile, K as artifactCachePolicy, L as REMOTE_DEVICE_BACKENDS, M as settingShapeErrors, O as resolveCacheProviderConfig, P as tunnelModeSetting, W as detectProviders, Y as resolveOptimizations, b as metroWarmupUrlSetting, i as SETTING_SHAPE_REMEDY, k as resolveSettings, l as androidDataPartitionSizeGbSettingError, o as androidAvdConfigSettingError, q as compilerCacheFallbackMessage, u as cacheProviderSettingError, w as publicUrlSetting } from "./settings-D030k0t4.mjs";
+import { C as listAdbDevices, D as memoizeEmulatorProbe, H as waitForBoot, I as probeEmulatorSerial, L as resetAdoptedAvd, P as physicalDeviceModel, R as resolveOwnedAvdSerial, T as listInstalledSystemImages, _ as emulatorDiskSpaceRemedy, a as androidPoolNoCandidatesRefusal, b as findBuildTool, i as androidPoolCandidates, n as androidDeviceAbi, o as androidSystemImageAbi, r as androidHome, s as androidToolCwd, t as androidBuildToolName, v as emulatorFailureRemedy, y as extractEmulatorFailure, z as resolvePhysicalDevice } from "./android-_y4Ohi5z.mjs";
+import { _ as stepTimer, c as launchErrorReport, f as refuseNoProject, g as stepClock, i as formatDuration, l as phaseLine, m as shortHash, n as appReadinessMessage, v as launchErrorPreview } from "./command-output-gByVmIjy.mjs";
+import { C as assetDiffReason, E as readAssetManifest, S as untrackedNativeFiles, T as compareAssetManifests, _ as refingerprintAfterMutation, a as waitForBuild, b as storedAssetManifest, c as describeFingerprintMiss, d as fingerprintDiffRecord, f as fingerprintDiffSuffix, g as providerUploadOutcome, h as providerDownloadPath, m as prepareProviderDownloadDir, o as waitForSharedBuild, p as fingerprintProject, r as releaseBuildLock, s as buildCacheKey, t as acquireBuildLock, u as filesystemBuildCapability, v as resolveBuild, w as captureAssetManifest, x as untrackedMissLine, y as storeBuild } from "./build-lock-DPXPLgTc.mjs";
+import { t as cleanLine } from "./server-expo-B_lctBR3.mjs";
+import { S as uploadRemote, _ as loadProjectProvider, b as resolveEasCliBin, d as UPLOAD_TIMEOUT_MS, f as cacheLevel, g as isEasAuthFailureText, h as exitAfterFlush, m as easAuthNote, o as parkedMaxSetting, p as checkEasAuth, u as RESOLVE_TIMEOUT_MS, x as resolveRemote } from "./sim-pool-KaIsp2Ft.mjs";
+import { C as isEasBuildFailure, _ as noMetroMessage, c as ensureBooted, d as AvdRecoveryError, g as launchOutcomeRecord, h as isPhysicalDeviceRequest, i as detectEntryFile, l as ensureOwnedDevice, n as pickDevClientScheme, o as needsPrebuild, p as ensureWorkspaceStorageSafely, s as runPrebuild, t as devClientScheme, u as AvdBootError, v as noMetroRemedy, w as resolveEasDevelopmentBuild, x as warmMetro, y as resolveMetroWithRetry } from "./dev-client-HyqISM0h.mjs";
+import { t as withWorkspaceProcessLock } from "./workspace-process-lock-DWaiRD0e.mjs";
+import { n as NO_BUILD_PROGRESS, s as startBuildProgress } from "./build-progress-CVqkfPC6.mjs";
+import { a as VERIFY_TIMEOUT_MS, d as verifyLaunch, i as RELEASE_VERIFY_WAIT_MS, l as unverifiedLaunchLines, n as LAUNCH_FATAL, r as LAUNCH_UNVERIFIED, t as LAUNCH_BUNDLING, u as verifyAndroidReleaseLaunch } from "./launch-verify-Q_OtW1Rf.mjs";
+import { _ as launchAndroidReleaseApp, d as deviceShellArg, f as installAndroidApp, g as launchAndroidApp, o as androidAppProcess, p as installConflictKind, r as DEFAULT_METRO_PORT, s as androidDevClientUrl, t as ADB_INSTALL_TIMEOUT_MS } from "./app-install-Uf3a83Tv.mjs";
+import { a as lostLine, c as releaseLeaseOnSignal, i as leaseExpiryText, l as runLease, n as DEBUG_VERIFY_STEP_MS, o as lostRefusal, r as acquireRunLease, s as parseDeviceWait, t as selectFromPool, u as waitFlagConflict } from "./device-pool-CnTAz8X1.mjs";
+import { d as startBuildHeartbeat, f as tailLines, g as acquireBuildSlot, n as HEARTBEAT_INTERVAL_MS, v as releaseBuildSlot } from "./xcode-BZqyxh3e.mjs";
+import { a as statsProjectKey, i as recordRunStats, n as readRunEstimates, t as createRunRecorder } from "./stats-DG9e66Rz.mjs";
+import { o as unknownAndroidSystemImageRefusal, r as checkDeviceCapacity } from "./simslim-B_LsGLuJ.mjs";
+import { a as ensureMetroReachable, b as ownedSessionName, l as resolveRemoteContext, n as binOnPath, o as ensureRemoteBootOwned, s as remoteAndroidDeps } from "./device-remote-AQ5rQPqr.mjs";
+import { a as buildAndroid, c as CCACHE_NOT_RUN, f as resolveCcache, l as CCACHE_UNAVAILABLE, n as resolveAndroidCas, o as productFlavorRefusal, p as formatDiagnostic, r as resolveAndroidCompilerCache, s as readProductFlavors, u as ccacheActivityLine } from "./android-cas-eiExNLf7.mjs";
+import { n as nativeRunCommand, t as launchSlotScope } from "./slot-launch-DU9A-gYw.mjs";
 import { t as spawnEntry } from "./spawn-entry-nCE6m770.mjs";
-import { a as printNativeCrashReport, r as captureNativeCrashes, t as errorDiagnostics } from "./error-diagnostics-D1Kaf-eT.mjs";
+import { a as printNativeCrashReport, r as captureNativeCrashes, t as errorDiagnostics } from "./error-diagnostics-Vfz83GCF.mjs";
 import { constants, copyFileSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync } from "node:fs";
 import { InvalidArgumentError } from "commander";
 import { basename, dirname, isAbsolute, join, relative } from "node:path";
-import { createWarnOnce, loadCacheProvider, resolveTieredBuild, storeTieredBuild } from "@stim-cli/cache";
 import chalk from "chalk";
+import { createWarnOnce, loadCacheProvider, resolveTieredBuild, storeTieredBuild } from "@stim-cli/cache";
 //#region src/engine/apk-swap.ts
 const ANDROID_BUNDLE_NAME = "index.android.bundle";
 const LAST_LINES = 5;
@@ -644,7 +645,7 @@ function fail$1(code, message, remedy, extra = {}) {
 	};
 }
 async function acquireAndroidArtifact({ root, buildLog, writer, settings, isExpo, device, physical, buildPlan, cacheProviderConfig, requestedBuildCache, easBuild, androidPackage: initialPackage, record, maxBuilds, progress }, { deviceAbi, fingerprint, untracked, resolveCached, storeCached, storedAssets, captureAssets, acquireLock, releaseLock, waitForBuild, loadProvider, easAuth, resolveRemoteBuild, uploadRemoteBuild, loadCacheProviderModule, acquireSlot, releaseSlot, needsPrebuildFor, prebuild, build, ccacheFor, swapApk, readState, now }) {
-	const { phase, out, estimates, stats } = progress;
+	const { phase, out, estimates, stats, step } = progress;
 	const { variant, release, profile: buildProfile, cas, cache: cachePolicy } = buildPlan;
 	const useBuildCache = cachePolicy.read;
 	let androidPackage = initialPackage;
@@ -715,6 +716,7 @@ async function acquireAndroidArtifact({ root, buildLog, writer, settings, isExpo
 			stats.setCacheKey(cacheKey);
 			return true;
 		}
+		step("cache-lookup");
 		const fingerprintTimer = stepTimer(now);
 		try {
 			const computed = await fingerprint(root, { platform: PLATFORM });
@@ -841,88 +843,37 @@ async function acquireAndroidArtifact({ root, buildLog, writer, settings, isExpo
 	if (!easBuild) await resolveRemoteArtifact();
 	let waitedForBuild = null;
 	let releasedWait = null;
-	async function waitForSharedBuild() {
-		if (!useBuildCache) return true;
-		const waitStarted = now();
-		let failedHolder;
-		while (!apkPath) {
-			let attempt = null;
-			try {
-				attempt = acquireLock({
-					platform: PLATFORM,
-					key: cacheKey,
-					root,
-					logFile: buildLog
-				});
-			} catch (err) {
-				const refusal = (0, ownership_claim_exports.claimFailure)(err, "stim android");
-				if (refusal) {
-					phaseFailure = fail$1(refusal.code, refusal.message, refusal.remedy, { lastBuildStatus: true });
-					return false;
-				}
-				phase("build", chalk.yellow(`could not take the build lock: ${err?.message || err}; building anyway`));
-			}
-			if (attempt?.acquired) {
-				buildLock = attempt;
-				const previous = attempt.tookOver ?? failedHolder;
-				if (previous) phase("build", chalk.yellow(takeoverLine(previous)));
-				break;
-			} else if (attempt?.held) {
-				releasedWait = null;
-				const holder = attempt.held;
-				const who = holder.projectRoot || "another workspace";
-				phase("build", `${who} is already building ${shortHash(hash)} (pid ${holder.pid})${holder.logFile ? ` -- tail ${holder.logFile}` : ""} -- stim guide lifecycle concurrency`);
-				let waited = null;
-				try {
-					const ceilingMs = WAIT_CEILING_MS - (now() - waitStarted);
-					if (ceilingMs <= 0) throw Object.assign(/* @__PURE__ */ new Error(`Waited ${formatDuration(now() - waitStarted)} for shared builds without an artifact; ${who} (pid ${holder.pid}) holds ${attempt.path}.`), {
-						code: "STIM_BUILD_WAIT_TIMEOUT",
-						lockPath: attempt.path
-					});
-					waited = await waitForBuild({
-						platform: PLATFORM,
-						key: cacheKey,
-						out,
-						ceilingMs
-					});
-				} catch (err) {
-					const refusal = (0, ownership_claim_exports.claimFailure)(err, "stim android");
-					if (refusal) {
-						phaseFailure = fail$1(refusal.code, refusal.message, refusal.remedy, { lastBuildStatus: true });
-						return false;
-					}
-					const wtErr = err;
-					if (wtErr?.code !== "STIM_BUILD_WAIT_TIMEOUT") throw err;
-					phaseFailure = fail$1("STIM_BUILD_WAIT_TIMEOUT", wtErr.message, `Check pid ${holder.pid}; if it is not really building, remove ${wtErr.lockPath} and run \`stim android\` again.`, { lastBuildStatus: true });
-					return false;
-				}
-				if (waited?.hit) {
-					apkPath = waited.hit ?? null;
-					record.cacheHit = "local";
-					waitedForBuild = {
-						pid: holder.pid,
-						ms: waited.waitedMs
-					};
-					phase("build", `waited ${formatDuration(waited.waitedMs)} for ${who}'s build -> installed from cache -- stim guide lifecycle concurrency`);
-				} else if (waited?.lockReleased) {
-					failedHolder = void 0;
-					releasedWait = {
-						facts: {
-							pid: holder.pid,
-							ms: waited.waitedMs
-						},
-						who
-					};
-					phase("build", `${who}'s build lock was released; rechecking this workspace before building`);
-				} else {
-					phase("build", chalk.yellow(`${who}'s build ended without an artifact (${waited?.builderFailed}); retrying the build lock`));
-					failedHolder = holder;
-				}
-			} else break;
+	if (!easBuild && useBuildCache && !apkPath) {
+		const shared = await waitForSharedBuild({
+			platform: PLATFORM,
+			key: cacheKey,
+			fingerprint: hash,
+			root,
+			logFile: buildLog,
+			command: "stim android",
+			acquire: acquireLock,
+			wait: waitForBuild,
+			now,
+			phase: (text) => {
+				step("wait");
+				phase("build", text);
+			},
+			warn: (text) => phase("build", chalk.yellow(text)),
+			out
+		});
+		if (shared.refusal) {
+			const { code, message, remedy } = shared.refusal;
+			phaseFailure = fail$1(code, message, remedy, { lastBuildStatus: true });
+			return refused();
+		}
+		buildLock = shared.lock;
+		releasedWait = shared.released;
+		if (shared.hit) {
+			apkPath = shared.hit.path;
+			record.cacheHit = "local";
+			waitedForBuild = shared.hit.waited;
 		}
-		return true;
 	}
-	if (!easBuild && !await waitForSharedBuild()) return refused();
 	let swapDir = null;
 	let swapFellBack = false;
 	const installableCachedApk = async (key, cachedPath) => {
@@ -976,6 +927,7 @@ async function acquireAndroidArtifact({ root, buildLog, writer, settings, isExpo
 				phase("build", chalk.yellow(`could not take a build slot: ${err?.message || err}; building anyway`));
 			}
 			if (needsPrebuildFor(root, "android", isExpo)) {
+				step("prebuild");
 				const pre = await prebuild(root, PLATFORM, writer, { isExpo });
 				if (pre.failed) {
 					phaseFailure = fail$1(pre.code, pre.reason, pre.remedy, {
@@ -1017,6 +969,7 @@ async function acquireAndroidArtifact({ root, buildLog, writer, settings, isExpo
 				}
 			}
 			if (!apkPath) {
+				step("compile");
 				phase("build", `compiling ${variant || "debug"} with Gradle`);
 				const built = await build({
 					root,
@@ -1508,7 +1461,7 @@ async function resolveInstallSerial({ root, slot, device, physical, remoteDevice
 	});
 	return resolved.serial;
 }
-async function finishAndroidRun({ lease, releaseLease, root, slot, json, metroCheck, useBuildCache, variant, release, isExpo, metroPort, logsDir, emuLog, device, physical, remoteDevice, bootPromise, resolveAvdSerial, waitForDeviceBoot, bootDuration, apkPath, androidPackage: initialPackage, swapDir, record, waitedForBuild, ccache, uploadPending, providerUpload, providerName, remote, abandonedRemote: remoteWasAbandoned, started, startedAt, writer, phase, fail, readApkPackage, install, launch, launchRelease, resolveDevClientScheme, verifyLaunched, verifyReleaseLaunched, spawn, kill, pidAlive, verifyCollector, writeLaunch, writeState, now, out, emit, recordRun }) {
+async function finishAndroidRun({ lease, releaseLease, root, slot, json, metroCheck, useBuildCache, variant, release, isExpo, metroPort, logsDir, emuLog, device, physical, remoteDevice, bootPromise, resolveAvdSerial, waitForDeviceBoot, bootDuration, apkPath, androidPackage: initialPackage, swapDir, record, waitedForBuild, ccache, uploadPending, providerUpload, providerName, remote, abandonedRemote: remoteWasAbandoned, started, startedAt, writer, phase, fail, readApkPackage, install, launch, launchRelease, resolveDevClientScheme, verifyLaunched, verifyReleaseLaunched, spawn, kill, pidAlive, verifyCollector, writeLaunch, writeState, now, out, emit, recordRun, enterPhase }) {
 	let androidPackage = initialPackage;
 	let leaseWarned = false;
 	const raiseLeaseFor = (boundMs, beforeInstall) => {
@@ -1524,6 +1477,7 @@ async function finishAndroidRun({ lease, releaseLease, root, slot, json, metroCh
 		}
 		return null;
 	};
+	enterPhase("install");
 	const booted = await bootPromise;
 	const runCommand = nativeRunCommand("android", slot, {
 		physical,
@@ -1613,6 +1567,7 @@ async function finishAndroidRun({ lease, releaseLease, root, slot, json, metroCh
 	if (!androidPackage) return fail(LAUNCH_FAILED, "Could not determine this app's Android package name, so there is nothing to launch.", "Set `expo.android.package` in app.json / app.config.js, or `namespace` in android/app/build.gradle.", { lastBuildStatus: true });
 	if (physical) raiseLeaseFor(0, false);
 	const scheme = release ? void 0 : resolveDevClientScheme(root, apkPath);
+	enterPhase("launch");
 	const launchTimer = stepTimer(now);
 	const launchedAt = now();
 	writer.write({
@@ -1858,8 +1813,6 @@ function resolveAndroidRunPlan({ settings, settingsContext, slot, easProfile, va
 	if (dataPartitionSizeError) return fail("STIM_BAD_ARG", dataPartitionSizeError, "Set android.dataPartitionSizeGb to a whole number of GiB from 6 through 16384.");
 	const avdConfigError = validateAvdConfig(settings, root);
 	if (avdConfigError) return fail("STIM_BAD_ARG", avdConfigError, "Use only documented android.avdConfig keys, or an android.avdConfigFile fragment contained by the app directory.");
-	const remoteSettingError = remoteDeviceSettingError(settings);
-	if (remoteSettingError) return fail("STIM_BAD_ARG", remoteSettingError, `Set ios.remote and android.remote to one of: ${REMOTE_DEVICE_BACKENDS.join(", ")}.`);
 	const systemImage = resolveSystemImage(systemImageFlag, settings);
 	const variant = easProfile !== void 0 ? "debug" : resolveVariant(variantFlag, settings);
 	const flavorRefusal = productFlavorRefusal({
@@ -1932,32 +1885,47 @@ function androidCommand(program) {
 	registerAndroid(program);
 }
 function registerAndroid(program) {
-	program.command("android").description("Build (or install from the shared cache), install and launch this workspace's Android app on its owned emulator, wired to the reserved Metro port. Never starts the bundler -- run `stim start` first.").option("--eas-profile <name>", "Download a matching EAS development build; on a miss, print the build command without running it").option("--slot <name>", "Reusable device slot within this workspace (default: default)", validateDeviceSlot).option("--json", "Emit the facts as a single JSON line on stdout; every other line goes to stderr").option("--no-metro-check", "Skip the reserved-port Metro health check (the app will load no bundle unless something else serves it)").option("--no-build-cache", "Build fresh, ignoring cached artifacts (local and the project's build-cache provider); the fresh build still replaces the cache entry").option("--variant <name>", "Gradle variant to assemble and install (e.g. productionDebug on a flavored project); overrides the android.variant setting. A variant ending in Release embeds the JS bundle and skips Metro entirely. Default: debug").option("--system-image <id>", "Android system image to create this workspace's owned AVD from, as the sdkmanager package id (e.g. \"system-images;android-36;google_apis;arm64-v8a\"). Overrides the android.systemImage setting for this invocation. An unknown id refuses with STIM_BAD_ARG and prints the installed images.").option("--device [serial]", "Install and launch on a connected physical device instead of this workspace's owned emulator. With no serial, the first connected device this workspace can lease is used. Stim never creates, boots, or deletes a physical device.").option("--remote <backend>", "Install and launch on a remote device with proxy or EAS. Builds are local unless --eas-profile selects an existing EAS build.", (value) => {
+	program.command("android").description("Build (or install from the shared cache), install and launch this workspace's Android app on its owned emulator, wired to the reserved Metro port. Never starts the bundler -- run `stim start` first.").option("--eas-profile <name>", "Download a matching EAS development build; on a miss, print the build command without running it").option("--slot <name>", "Reusable device slot within this workspace (default: default)", parseDeviceSlotOption).option("--json", "Emit the facts as a single JSON line on stdout; every other line goes to stderr").option("--no-metro-check", "Skip the reserved-port Metro health check (the app will load no bundle unless something else serves it)").option("--no-build-cache", "Build fresh, ignoring cached artifacts (local and the project's build-cache provider); the fresh build still replaces the cache entry").option("--variant <name>", "Gradle variant to assemble and install (e.g. productionDebug on a flavored project); overrides the android.variant setting. A variant ending in Release embeds the JS bundle and skips Metro entirely. Default: debug").option("--system-image <id>", "Android system image to create this workspace's owned AVD from, as the sdkmanager package id (e.g. \"system-images;android-36;google_apis;arm64-v8a\"). Overrides the android.systemImage setting for this invocation. An unknown id refuses with STIM_BAD_ARG and prints the installed images.").option("--device [serial]", "Install and launch on a connected physical device instead of this workspace's owned emulator. With no serial, the first connected device this workspace can lease is used. Stim never creates, boots, or deletes a physical device.").option("--remote <backend>", "Install and launch on a remote device with proxy or EAS. Builds are local unless --eas-profile selects an existing EAS build.", (value) => {
 		if (REMOTE_DEVICE_BACKENDS.includes(value)) return value;
 		throw new InvalidArgumentError(`expected one of: ${REMOTE_DEVICE_BACKENDS.join(", ")}`);
 	}).option("--wait <seconds>", "How long to wait for another workspace to release the device it leases, before refusing with STIM_DEVICE_BUSY (default 60, 0 refuses at once). Only with --device.").option("--no-wait", "Install on a device another workspace leases instead of waiting: this run takes no lease and, when both workspaces build the same app id, the install terminates the holder's running app. Only with --device.").action(async (opts) => {
 		const root = findProjectRoot(process.cwd());
 		if (!root) {
-			console.error(chalk.red("Not in a React Native project (no package.json found)."));
-			process.exit(1);
+			refuseNoProject({ json: Boolean(opts.json) });
 			return;
 		}
-		if (!(await withWorkspaceProcessLock(workspaceDir(root), "native-run", () => runAndroid({
-			root,
-			slot: opts.slot,
-			easProfile: opts.easProfile,
-			json: Boolean(opts.json),
-			metroCheck: opts.metroCheck !== false,
-			useBuildCache: opts.buildCache !== false,
-			variant: opts.variant ?? null,
-			systemImage: opts.systemImage ?? null,
-			remoteDevice: opts.remote ?? null,
-			device: opts.device ?? null,
-			wait: opts.wait,
-			waitConflict: waitFlagConflict(process.argv)
-		}), {
+		if (!(await withWorkspaceProcessLock(workspaceDir(root), "native-run", async (claim) => {
+			recordWorkspaceUse(root);
+			const progress = startBuildProgress({
+				root,
+				platform: "android",
+				slot: opts.slot ?? "default",
+				claim,
+				note: (line) => console.error(chalk.dim(line))
+			});
+			try {
+				return await runAndroid({
+					root,
+					slot: opts.slot,
+					easProfile: opts.easProfile,
+					json: Boolean(opts.json),
+					metroCheck: opts.metroCheck !== false,
+					useBuildCache: opts.buildCache !== false,
+					variant: opts.variant ?? null,
+					systemImage: opts.systemImage ?? null,
+					remoteDevice: opts.remote ?? null,
+					device: opts.device ?? null,
+					wait: opts.wait,
+					waitConflict: waitFlagConflict(process.argv),
+					progress
+				});
+			} finally {
+				progress.clear();
+			}
+		}, {
 			external: true,
-			waitMs: 18e5
+			waitMs: 18e5,
+			declareSpawns: true
 		})).ok) process.exit(1);
 	});
 }
@@ -2055,6 +2023,10 @@ function androidSlotOptions(options) {
 			...args,
 			slot
 		}),
+		ensureDeviceBooted: (args) => base.ensureDeviceBooted({
+			...args,
+			slot
+		}),
 		checkCapacity: (args) => base.checkCapacity({
 			...args,
 			slot
@@ -2095,6 +2067,7 @@ function avdSetupFailure(error, root, logFile) {
 }
 async function runAndroid(options = {}) {
 	let { root, json, commandRemoteBackend, resolveSettingsFor, resolveRemoteDeviceContext, makeRemoteDeviceDeps, resolveEasBin, ensureRemoteMetro, ensureRemoteOwned, detectRemoteProviders, metroCheck, useBuildCache: requestedBuildCache, easProfile, resolveEasBuild, variantFlag, systemImageFlag, deviceFlag, waitFlag, waitConflict, acquireLease, makeRunLease, selectPool, onLeaseSignal, listDevices, deviceModel, deviceAbi, isEmulatorDevice, readApkPackage, getLimits, checkCapacity, acquireSlot, releaseSlot, ensureDevice, listSystemImages, ensureDeviceBooted, resolveAvdSerial, waitForDeviceBoot, resolveMetro, prewarmMetro, resolveMetroRetrying, readState, pidAlive, verifyCollector, verifyLaunched, ensureStorage, fingerprint, untracked, resolveCached, storeCached, storedAssets, captureAssets, acquireLock, releaseLock, waitForBuild, loadProvider, easAuth, resolveRemoteBuild, uploadRemoteBuild, resolveCacheProvider, loadCacheProviderModule, needsPrebuildFor, prebuild, build, ccacheFor, install, launch, launchRelease, verifyReleaseLaunched, swapApk, resolveDevClientScheme, spawn, kill, createWriter, writeLaunch, writeState, recordStats, readEstimates, now, out, emit } = androidSlotOptions(options);
+	const progress = options.progress ?? NO_BUILD_PROGRESS;
 	const slot = validateDeviceSlot(options.slot);
 	const started = now();
 	const startedAt = new Date(started).toISOString();
@@ -2159,7 +2132,8 @@ async function runAndroid(options = {}) {
 		platform: PLATFORM,
 		write: recordStats,
 		now,
-		note: (line) => out(phaseLine("stats", chalk.dim(line)))
+		note: (line) => out(phaseLine("stats", chalk.dim(line))),
+		phases: () => progress.durations()
 	});
 	const recordRun = stats.record;
 	let ccacheActivity = CCACHE_NOT_RUN;
@@ -2300,7 +2274,6 @@ async function runAndroid(options = {}) {
 	if (remoteBackend) {
 		const resolved = await resolveRemoteDeviceContext({
 			root,
-			label,
 			platform: PLATFORM,
 			backend: remoteBackend,
 			easBin: resolveEasBin(root)?.file ?? null
@@ -2389,6 +2362,7 @@ async function runAndroid(options = {}) {
 		const boot = () => Promise.resolve(ensureDeviceBooted({
 			platform: PLATFORM,
 			device,
+			projectPath: root,
 			out,
 			logFile: emuLog
 		})).catch((e) => ({
@@ -2404,6 +2378,7 @@ async function runAndroid(options = {}) {
 			boot,
 			createdSessionId: remoteDevice.createdSessionId,
 			abandonCreatedSession: remoteDevice.abandonCreatedSession,
+			webPreviewUrl: remoteDevice.webPreviewUrl,
 			writeState,
 			register: registerProject
 		}) : boot()).then((result) => {
@@ -2457,7 +2432,8 @@ async function runAndroid(options = {}) {
 				phase,
 				out,
 				estimates,
-				stats
+				stats,
+				step: progress.step
 			}
 		}, {
 			deviceAbi,
@@ -2590,7 +2566,8 @@ async function runAndroid(options = {}) {
 				now,
 				out,
 				emit,
-				recordRun
+				recordRun,
+				enterPhase: progress.step
 			});
 		} finally {
 			releaseLease();

package/dist/{android-DeYdjjBP.mjs → android-DEgo4oCo.mjs}

@@ -1,5 +1,5 @@
-import { t as getExecutor } from "./exec-B29XNuhP.mjs";
-import { s as androidToolCwd } from "./android-DWssqHQ8.mjs";
+import { t as getExecutor } from "./exec-jIAlgilk.mjs";
+import { s as androidToolCwd } from "./android-_y4Ohi5z.mjs";
 //#region src/collector/android.ts
 const LEVEL_BY_LETTER = {
 	V: "debug",