stim 1.10.1 → 1.11.0

package/dist/{guide-DwmaD_Wa.mjs → guide-NDvTmMi-.mjs}

@@ -1,5 +1,5 @@
 import { o as findProjectRoot } from "./project-BXZzOABt.mjs";
-import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-DOugPlPz.mjs";
+import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-B5oFZEri.mjs";
 import { t as guideStatus } from "./guide-status-CWvti2Lg.mjs";
 import { SETTINGS_SCHEMA_URL } from "@stim-cli/core/state";
 import chalk from "chalk";
@@ -92,6 +92,10 @@ presence of eas.json does not select EAS or authorize building.
 Physical --device targets are supported. Follow EAS device-registration and
 rebuild remedies only when the session authorizes those account changes.
 
+To learn whether the next build is a cache hit and how long it should take,
+without building, run stim ios --plan (or stim android --plan); see stim guide
+lifecycle builds.
+
 Read stim guide lifecycle concurrency when a build waits on another workspace
 or a build call times out. A native build can outlive a shell timeout; if the
 tool call timed out, retry the same command and follow its printed remedy if
@@ -228,7 +232,9 @@ Ask the user before these actions:
 - stop when the workspace owns an EAS session, because it irreversibly ends
   that remote session. For a local device, stop shuts it down but does not
   delete it. An explicit stop shuts down a Stim-owned simulator even when
-  another process uses it. It never shuts down an unowned simulator.
+  another process uses it. It never shuts down an unowned simulator. It also
+  cancels an ios or android run still building for the device it stops
+  (guide lifecycle).
 
 LEAVE THE MACHINE CLEAN
 
@@ -299,7 +305,7 @@ FULL TOPIC LIST
   stim guide lifecycle builds     # build optimizations, optional cache warm-up, fingerprints
   stim guide lifecycle concurrency # shared builds, wait timeouts, capacity limits
   stim guide lifecycle budget     # disk and memory budgets, automatic reclaim
-  stim guide lifecycle options    # every flag, Android variants, --device-type, --system-image
+  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 release    # Release configurations and ...Release variants
   stim guide facts                # the --json payloads
@@ -312,7 +318,7 @@ FULL TOPIC LIST
   stim guide settings             # configuration files and supported keys`
 	},
 	facts: {
-		summary: "The --json payloads: `start`, `ios`, `android`, `reload`, `stop`, `status`, `doctor`, `device lock`/`unlock`, `gc`, and the error contract",
+		summary: "The --json payloads: `start`, `ios`, `android`, `ios|android --plan`, `reload`, `stop`, `status`, `doctor`, `device lock`/`unlock`, `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
@@ -331,12 +337,38 @@ status's unprovisionedWorktrees lists the linked worktrees with no Stim
 environment in every repository with a registered environment, plus the
 repository status runs from. A worktree counts as having an
 environment when one is registered at it or inside it. Each entry is
-{ path, branch, repository }; repository is the main checkout, or the git
-directory of a bare repository. status reads git's own worktree records and
-never opens the worktree directories, so a worktree under a macOS-protected
-folder such as ~/Documents is listed without a privacy prompt.
+{ path, branch, repository, git }; repository is the main checkout, or the git
+directory of a bare repository. status lists worktrees from git's own worktree
+records, and on macOS runs no git in a worktree with no environment under a
+protected folder such as ~/Documents, so listing it raises no privacy prompt.
 \`worktree warm\` does not create an environment; \`start\`, \`ios\`,
-\`android\` and \`doctor\` register it.
+\`android\` and \`doctor\` register it. An environment's worktree is the
+linked worktree it is registered at or inside.
+
+Each worktree entry, in unprovisionedWorktrees and in an environment's
+worktree, carries git:
+
+  git          { changed, untracked, upstream, ahead, behind, mergedInto }, or
+               null when git fails or does not answer within 3 s, or the
+               worktree has no environment and sits in ~/Desktop, ~/Documents,
+               ~/Downloads, iCloud Drive, ~/Library/CloudStorage or /Volumes,
+               which status does not open on macOS
+  changed      tracked paths with staged or unstaged changes, conflicts included
+  untracked    untracked entries as git status lists them; a new directory
+               counts once
+  upstream     the branch's upstream, such as "origin/feat/x", or null
+  ahead        commits on HEAD and not on upstream; null with no upstream, or
+  behind       when the upstream branch no longer exists
+  mergedInto   "origin/<default>" when gc would call the branch merged, judged
+               from local refs without fetching, else null
+
+status runs \`git status --porcelain=v2 --branch\` in every worktree in
+parallel, and caches the merge verdict by HEAD and default-branch commit
+under $STIM_HOME/git-merge. One call starts no new merge check 250 ms after
+its first; later calls judge the rest, and until then a verdict for the same
+HEAD at an older default-branch commit stands in. \`status --watch\` reuses a worktree's git read
+for 5 s. Plain status prints "git: 2 changed, 1 untracked, ahead 3" under
+each environment, and the same after each worktree with no environment.
 
 status's remoteDevices lists each environment's recorded EAS Simulator
 session. The session is billable while it runs, and it makes the environment
@@ -518,6 +550,10 @@ per session, with the preview URL.`,
                   android.systemImage setting reports it too, not only a
                   \`--system-image\` run. Null on \`--device\` and on an
                   emulator Stim does not own
+  deviceProfile   the avdmanager hardware profile of the owned AVD
+                  ("pixel_6", "pixel_fold"), read from its config.ini
+                  hw.device.name. Null where systemImage is null, and on an
+                  AVD of the old generic profile, which has no hw.device.name
   fingerprint / cacheKey / cacheHit / cacheSkipped / waitedForBuild /
   appPath / installSkipped / launched
                   as above -- cacheKey keys on the VARIANT here
@@ -640,6 +676,19 @@ ON FAILURE
   \`reclaimed\` is present the same way as on success when the run reclaimed
   before failing, including a STIM_LOW_DISK refusal.
 
+  An \`ios\` or \`android\` run that \`stim stop\` or Ctrl-C interrupted
+  reports STIM_CANCELLED and exits 130. A
+  run that exits on the interrupt at once (a second SIGINT, a physical-device
+  lease, Ctrl-C with no build tool running) exits 130 with no payload.
+
+  \`stop --json\` prints { root, ok, supervisor, collectors, metro, device,
+  port, metroTunnel, releasedLeases }. When it cannot end the \`ios\` or
+  \`android\` run holding the workspace, it prints the error contract with
+  root and ok: false instead, plus device.remote when it ended a recorded EAS
+  session first, and exits 1:
+
+    { "root": "...", "ok": false, "code": "STIM_STOP_BLOCKED", "message": "...", "remedy": "..." }
+
   Branch on \`code\`, never on the message text. \`guide errors\` enumerates
   every code.
 
@@ -796,7 +845,7 @@ RULES
     parkedSimulators        { udid, name, model, runtime, parkedAt, bytes,
                               listed }  with --older-than, only those parked
                               at least that long
-    parkedEmulators         { name, systemImage, parkedAt, bytes, listed }
+    parkedEmulators         { name, systemImage, deviceProfile, parkedAt, bytes, listed }
                               likewise
     orphanedDevices         { kind, id, name, bytes, directory }
     unverifiedDevices       { kind, id, name, command }  stim-* devices Stim
@@ -857,7 +906,7 @@ RULES
   - --cache together with --worktrees or --idle`
 			},
 			status: {
-				summary: "the status payload's build and device activity fields: a running build, its estimate, and who drives each device",
+				summary: "the status payload's build and device activity fields: a running build, its estimate, each platform's last build, and who drives each device",
 				body: () => `  stim status --json
 
   Each booted simulator and detected emulator in environments (and in
@@ -926,8 +975,65 @@ RULES
 
     build: ios compile, 1m10s elapsed -- about 3 min left (median of 4 cold runs)
 
+  An environment with a recorded run also carries lastBuilds, each
+  platform's most recent ios or android run, finished or failed:
+
+  lastBuilds   { ios?, android? }, each { platform, status, cacheHit,
+               cacheSkipped, durationMs, fingerprint, startedAt, finishedAt,
+               errorCode?, missReason? }
+
+  status       "ok" or "failed"
+  cacheHit     "local" or "remote" for an app from that cache tier; false
+               for an ok run that compiled, or a failed run that had none
+  durationMs   the run's wall time; finishedAt is startedAt plus it. Both
+               are null when the record carries no duration.
+  fingerprint  the key's fingerprint after any prebuild or pod install
+  missReason   only on a run that did not install a cached app (it
+               compiled, or failed before finding one): { kind, summary, changes,
+               changeCount, baseline, rekeyedBy }. kind is "changed",
+               "no-baseline", "same-sources", "cache-skipped" or
+               "fingerprint-error"; summary names the cause, such as
+               "native dependency added: expo-clipboard". changes holds up to
+               20 { source, change, category } of changeCount changed sources;
+               baseline is { fingerprint, from: "workspace" | "project" }, the
+               cached build compared with; rekeyedBy lists "prebuild" or
+               "pod install" when those steps moved the key.
+
+  Plain status prints "last build: ios local cache in 12s, android compiled
+  in 7m02s". To predict the next run instead, see \`guide facts plan\`.
+
   There is no completion fraction: a compile's log volume depends on what
   is already built, so it does not measure progress.`
+			},
+			plan: {
+				summary: "the ios and android --plan payload: fingerprint, cacheHit, prebuild, expectedMs and basis",
+				body: () => `  stim ios --plan --json            # or: stim android --plan --json
+
+  { platform, slot?, fingerprint, cacheKey, cacheHit, provider,
+    cacheSkipped, prebuild, outcome, expectedMs, basis, refusal? }
+
+  fingerprint   the fingerprint the run would look up first; with
+                --eas-profile, the one EAS CLI computes
+  cacheKey      the key under that fingerprint; null for an EAS miss
+  cacheHit      "local", "remote", or false for a miss
+  provider      the remote tier that answered, "eas" with --eas-profile,
+                otherwise null
+  cacheSkipped  true when cache reads are off (--no-build-cache or config)
+  prebuild      on a miss, the run's decision for the native dir: "none",
+                "generate", "regenerate" or "refuse"; null on a hit
+  outcome       "hit" or "cold"; null when the run would refuse
+  expectedMs    the median wall time of this project's last successful runs
+                with that outcome on that platform, or null with none
+  basis         how many runs expectedMs comes from (at most 10)
+  refusal       { code, message, remedy } when the run would refuse:
+                STIM_PREBUILD_FAILED for a tracked native dir the fingerprint
+                leaves out, STIM_EAS_BUILD_MISSING for an EAS miss
+
+  A plan that would refuse still exits 0: the payload is the answer. A plan
+  that cannot be computed prints the error contract and exits 1, for example
+  STIM_NO_FINGERPRINT, STIM_EAS_UNAVAILABLE, or STIM_BAD_ARG for a flag that
+  picks a device. When and why a plan and the run can differ: \`guide
+  lifecycle builds\`.`
 			},
 			stats: {
 				summary: "the stats payload, what counts as a run, hit, miss and failed, timeSavedMs, the heartbeat estimate",
@@ -1051,9 +1157,12 @@ REMOTE DEVICE BACKENDS
   AGENT_DEVICE_DAEMON_AUTH_TOKEN. Stim creates no remote session for it.
 
   The EAS backend needs eas-cli 21.6.0 or later and an account with EAS
-  Simulator access. An EAS session is billable. EAS does not inherit the proxy
-  credentials. Always tear the session down: \`stop\`, \`worktree remove\`,
-  and \`gc --delete\` can end sessions that Stim proves it owns.
+  Simulator access. An EAS session is billable. Stim prepares the app before
+  it creates or reconnects the session, so a failed build starts no session
+  and the install follows the connection directly. EAS does not inherit the
+  proxy credentials. Always tear the session down: \`stop\`,
+  \`worktree remove\`, and \`gc --delete\` can end sessions that Stim proves
+  it owns.
   \`stim status\` lists each recorded session with its preview URL (see
   \`guide facts\`).
 
@@ -1252,8 +1361,8 @@ usually untagged: use an unfiltered workspace query to inspect those errors.
 
 FLAGS
   --slot <name>   only this slot's records (default includes untagged records)
-  --source <s...>  metro, client, device, build (one or more), or all. An
-                   unknown value is REJECTED rather than quietly matching
+  --source <s...>  metro, client, device, build, agent (one or more), or all.
+                   An unknown value is REJECTED rather than quietly matching
                    nothing.
   --level <l>      minimum level: debug, info, warn, error, fatal
   --since <d>      only records newer than this: 30s, 5m, 2h
@@ -1344,7 +1453,7 @@ FLAGS
 
 THE RECORD
   { ts, src, level, msg } always. ts is epoch milliseconds; src is one of
-  metro / client / device / build; level is one of the five above.
+  metro / client / device / build / agent; level is one of the five above.
   Optional fields:
     event    the producer's own event name (bundle_build_done, client_log, ...)
     stack    frames of { file, line, column, fn }, passed through as reported
@@ -1493,6 +1602,21 @@ WHAT WRITES WHAT
   archive rather than a stream. Streaming with full fidelity needs
   libimobiledevice or pymobiledevice3, which are third-party installs Stim
   does not require. See appandflow/stim#179.
+  agent                no file. Each query reads agent-device's session
+                       records (~/.agent-device/sessions, or
+                       AGENT_DEVICE_STATE_DIR) for this workspace's owned
+                       simulators and emulators, read-only. An action is
+                       info (msg is agent-device's summary, e.g. "Tapped
+                       (201, 731)"; event agent_action with command, session,
+                       deviceId and details); a failed command is error
+                       (event agent_failed). A plain query includes them;
+                       --errors only with --source agent or all. iOS sessions
+                       match a simulator through their runner.log, Android
+                       sessions only while agent-device's claim on the
+                       emulator is live (released claims drop their
+                       actions from later queries). A session in an
+                       unrecognized format yields one warn record
+                       (agent_format_unknown) instead of its actions.
   build-ios.ndjson     the xcodebuild / gradle transcript at level debug, the
   build-android.ndjson extracted diagnostics at level error, and the launch as
                        a marker record. One RUN's worth: each build starts the
@@ -2122,7 +2246,12 @@ so a Debug run on one is wired to a LAN origin instead of localhost.`,
   The project already owns a simulator of a different model, and Stim will
   not silently boot a different one. Reap it (\`worktree remove\`, or
   \`gc --delete\`) and run \`stim ios\` again to create the requested model.
-  That loses the old sim's app state.`
+  That loses the old sim's app state.
+
+"this project's emulator uses device profile X, but Y was requested"
+  The Android counterpart, from \`--device-profile\` or android.deviceProfile.
+  Reap the AVD the same way, or pass \`--slot <name>\` to create the requested
+  profile beside it.`
 			},
 			STIM_DEVICE_BUSY: {
 				summary: "another workspace holds the lease on that phone and the wait ran out",
@@ -2434,14 +2563,16 @@ captured"  (in metro.ndjson, bare RN)
   nearest registered descendant app with logs when one exists), an
   android/app/build.gradle that declares product flavors with
   no variant selected (the refusal names the debug variants), or a
-  \`--device-type\`, \`--runtime\` or \`--system-image\` name that is BLANK or
-  is not installed on this machine. For the unknown-name case the installed
-  names are printed in the message -- the versions \`xcrun simctl list
-  runtimes\` reports, the models those runtimes can actually CREATE (not the
-  whole \`simctl list devicetypes\` table, which also names watchOS, tvOS and
-  visionOS models no iOS runtime offers), or the system images the SDK has --
-  so the remedy is to re-run with one of them. An ios.deviceType, ios.runtime
-  or android.systemImage setting is checked the same way, and the check applies
+  \`--device-type\`, \`--runtime\`, \`--system-image\` or \`--device-profile\`
+  name that is BLANK or is not installed on this machine. For the
+  unknown-name case the installed names are printed in the message -- the
+  versions \`xcrun simctl list runtimes\` reports, the models those runtimes
+  can actually CREATE (not the whole \`simctl list devicetypes\` table, which
+  also names watchOS, tvOS and visionOS models no iOS runtime offers), the
+  system images the SDK has, or the hardware profiles \`avdmanager list device
+  -c\` offers -- so the remedy is to re-run with one of them. An
+  ios.deviceType, ios.runtime, android.systemImage or android.deviceProfile
+  setting is checked the same way, and the check applies
   even when this workspace ALREADY owns a device, so a name that could never
   create anything is caught rather than left to a later run.
   \`gc --json --cache <name>\` refuses with STIM_BAD_ARG when no shared cache
@@ -2455,7 +2586,8 @@ captured"  (in metro.ndjson, bare RN)
   reporting that nothing was running.
   These errors are caught before the port is reserved and before any build or
   device work, so nothing was started. The one listing they need
-  (\`simctl list runtimes\`, the SDK's system-images directory) runs only when
+  (\`simctl list runtimes\`, the SDK's system-images directory, \`avdmanager
+  list device -c\`) runs only when
   a name was actually given, and a listing that fails is reported as
   STIM_NO_DEVICE naming the tool, never as a crash.`
 			},
@@ -2471,6 +2603,41 @@ captured"  (in metro.ndjson, bare RN)
   \`workspace removal\` -- both are \`stim worktree remove\`). Let it finish,
   then run the command again. \`start --remote\` reports this same case as
   STIM_WORKTREE_REMOVAL_IN_PROGRESS instead.`
+			},
+			STIM_CANCELLED: {
+				summary: "an ios or android run was interrupted by `stim stop` or Ctrl-C before it finished",
+				body: () => `STIM_CANCELLED  (ios, android; exit 130)
+  "The ios run was cancelled by \`stim stop\` (pid <n>) before it finished."
+  The run received SIGINT: from \`stim stop\`, which interrupts a build it
+  leaves with nothing to deploy to, or from Ctrl-C. It forwarded the interrupt
+  to the build tool it was running (xcodebuild, Gradle, pod install, expo
+  prebuild) and failed through its own cleanup; the next line names the step it
+  stopped at. An interrupted build stores no artifact, so the next run looks
+  up the cache as usual. Stopped between build tools, a run that \`stop\`
+  cancelled starts no further build tool and stops before it installs. A
+  second SIGINT exits at once, and so does a run that holds a physical-device
+  lease; those exits print no payload. Run the same command again when you want the
+  app on a device.`
+			},
+			STIM_STOP_BLOCKED: {
+				summary: "`stop` could not interrupt the ios or android run holding this workspace; names its pid and claim",
+				body: () => `STIM_STOP_BLOCKED  (stop)
+  \`stop\` found a live \`ios\` or \`android\` run holding this workspace's
+  native-run claim and could not end it:
+  - "... did not exit within 60s of SIGINT": the run was interrupted but is
+    still running. Wait for it, or end it with the \`kill <pid>\` the remedy
+    prints, then run \`stim stop\` again.
+  - "... pid <n> is no longer that run; the build tool it started (pid <m>)
+    still holds the claim": the run itself died and its build tool keeps the
+    claim. Stim signals only a claim owner whose recorded identity it can
+    prove, so it leaves the tool alone. Wait for pid <m> to exit or end it.
+    On Windows this is the usual outcome of an interrupt: Node cannot deliver
+    a catchable SIGINT to another process there, so the run ends at once and
+    its Gradle build keeps the claim until it exits.
+  A recorded EAS session is ended before this refusal: ending a billable
+  session never waits on a build. The JSON payload carries the session
+  outcome under device.remote. Devices, collectors and the dev server are left
+  as they were.`
 			},
 			STIM_LOCK_TIMEOUT: {
 				summary: "a lock held past the wait; workspace-process and short directory locks",
@@ -2944,6 +3111,10 @@ ANDROID EMULATOR RESTARTS
   started is alive. Stim keeps waiting on the same emulator; it never
   launches a duplicate. See \`stim guide errors STIM_NO_DEVICE\` for the
   wait windows, diagnostics, and recovery steps.
+  On macOS, top-level androidEmulatorApp "stim-desktop" in the machine config
+  boots owned emulators without a window and shows them in Stim Desktop; see
+  guide settings. An emulator that is already running keeps its current
+  display until it next boots.
 
 DESTRUCTIVE COMMANDS -- ask the user first
   gc --delete             deletes orphaned devices Stim created, tens of GB
@@ -2961,6 +3132,24 @@ one answers from the project. A dev server whose supervisor died is stopped
 only when its recorded process identity still matches. There is no
 \`--delete\` flag on \`stop\`.
 
+STOP DURING A BUILD
+  \`ios\`, \`android\` and \`stop\` take turns on the workspace's
+  native-run lock. A command that has to wait says so on stderr at once and
+  every 30 seconds:
+    lock        waiting for \`stim ios\` (pid 41233, running for 12m04s) in this workspace to finish
+  \`stop\` does not wait out a build it leaves with nothing to deploy to: a
+  plain \`stop\`, \`stop --slot <name>\` for the slot the build targets, or
+  for the workspace's only device. It sends that run SIGINT, only after
+  proving the run's recorded process identity, and waits up to 60 seconds for
+  it to exit. The run stops its build tool, stores nothing from the
+  interrupted build, and exits 130 with STIM_CANCELLED. A run that does not
+  exit in time, or whose build tool outlived it, is refused with
+  STIM_STOP_BLOCKED naming its pid and claim. \`stop --slot <name>\` while the
+  build targets another slot that stays leaves the build running and stops
+  the slot without the lock. A plain \`stop\` ends a recorded EAS session as
+  soon as it sees the lock held: ending a billable session never waits on a
+  build.
+
 CAPACITY
   A booted iOS sim is roughly 1-2 GB of RAM, an Android emulator 2-3 GB. On a
   16 GB machine plan for 2-3 live environments. Nothing enforces this;
@@ -3430,7 +3619,7 @@ result as proof instead of requiring an unrelated screenshot.`
   The wipe resets apps, accounts, device settings and the shared storage
   inside the data partition; the AVD's creation settings and any separate
   SD card image remain. Status lists parked Android emulators; GC
-  reports their system image, age and disk size.
+  reports their system image, hardware profile, age and disk size.
 `
 			},
 			builds: {
@@ -3448,6 +3637,42 @@ result as proof instead of requiring an unrelated screenshot.`
 
   Follow the normal ownership and consent rules in guide agent.
 
+PREDICTING THE NEXT BUILD (--plan)
+  \`stim ios --plan\` and \`stim android --plan\` answer "will the next run
+  be a cache hit, and how long will it take?" without building, booting,
+  installing, or starting Metro. They take no workspace lock and write no
+  Stim state, cache entry or statistic, so they run beside a build.
+
+    stim ios --plan
+      plan        ios 1b625d.. -> local cache hit
+      expect      ~2.7s (median of 1 hit run)
+
+  A plan resolves the fingerprint and cache key the way the run would, with
+  the same --slot, --scheme, --configuration, --variant, --device-type,
+  --runtime, --system-image, --device-profile, --eas-profile and
+  --no-build-cache, then looks
+  in the build's order: the local cache, the cache.provider setting's
+  provider, then the app config's build cache provider. A provider has no
+  lookup that skips the download, so a remote check downloads the artifact:
+  the cache.provider tier into a temporary directory the plan removes, the
+  app config's provider wherever it keeps its downloads, as during a run.
+  On a miss it adds the prebuild decision the run would make (generate,
+  regenerate, none, or refuse with STIM_PREBUILD_FAILED). With --eas-profile it asks EAS for a matching
+  build (config, fingerprint:generate, build:list) and downloads nothing.
+  expectedMs is the median of this project's recorded runs with that outcome;
+  the payload is in \`guide facts plan\`.
+
+  A plan is a prediction for the moment it runs. Three things can still
+  change the run: another workspace can store the key first; a prebuild or
+  pod install can move the fingerprint, and the run then looks up the new
+  key once; and a Release hit that fails its JS swap builds fresh.
+  An Android plan reads the ABI from the emulator the slot records, or from
+  the system image a new one would use. A plan refuses --device, --remote,
+  --wait, --no-wait, --no-metro-check and --simulator-app with STIM_BAD_ARG.
+  Without --eas-profile it also refuses the android.remote setting and the
+  experimental compiler CAS with STIM_BAD_ARG, and refuses with
+  STIM_NO_DEVICE when no system image is installed.
+
 IOS SCHEME SELECTION
   Pass \`stim ios --scheme "App Staging"\` to select an exact shared Xcode
   app scheme. Unknown names refuse with the available choices. This is the
@@ -3659,10 +3884,18 @@ THE BUILD CACHE HAS THREE LEVELS
   trims, and clears local caches only: the provider contract has no delete
   operation, so no local command can remove data a team or CI system shares.
 
-  A MISS explains itself when it can. When this workspace's previous build
-  stored its fingerprint sources beside the cache entry, the fingerprint line
-  gains " -- N sources changed: <up to three paths>", and the full list
-  (capped at 20 names) lands in the build log as a fingerprint_diff record.
+  A MISS EXPLAINS ITSELF. Each local cache entry keeps the per-source hashes
+  of its fingerprint (hashes only, pruned with the entry). Before compiling,
+  Stim compares the sources it is about to store with a baseline: the entry
+  this workspace's last build of the same platform used, else the newest one
+  another worktree of the same project used. It prints one line:
+
+    cache       miss: native dependency added: expo-clipboard (+2 more)
+
+  records the reason as lastBuilds.<platform>.missReason in status --json
+  (see \`guide facts status\`), and writes the changed sources (capped at 20
+  names) to the build log as a fingerprint_diff record. With no baseline the
+  line says there was nothing to compare with.
 
   THE KEY CAN MOVE MID-RUN, and the run says so in two facts rather than two
   explanations. \`expo prebuild\` and \`pod install\` rewrite fingerprinted
@@ -3896,8 +4129,8 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
 				summary: "every flag per command, Android variants and flavors, the per-run simulator model, runtime and system image",
 				body: () => `THE OPTION SURFACE, IN FULL
   start           --json --wait <seconds> --remote --reset-cache
-  ios             --slot <name> --json --no-metro-check --no-build-cache --scheme <name> --configuration <name> --device-type <name> --runtime <version> --simulator-app <xcode|siniulator|stim-desktop> --device [udid] --wait <seconds> --no-wait --remote <proxy|eas>
-  android         --slot <name> --json --no-metro-check --no-build-cache --variant <name> --system-image <id> --device [serial] --wait <seconds> --no-wait --remote <proxy|eas>
+  ios             --slot <name> --json --plan --no-metro-check --no-build-cache --scheme <name> --configuration <name> --device-type <name> --runtime <version> --simulator-app <xcode|siniulator|stim-desktop> --device [udid] --wait <seconds> --no-wait --remote <proxy|eas>
+  android         --slot <name> --json --plan --no-metro-check --no-build-cache --variant <name> --system-image <id> --device-profile <id> --device [serial] --wait <seconds> --no-wait --remote <proxy|eas>
   reload          [ios|android] --json
   device          lock <ios|android> [id] --slot <name> --for <duration> --wait <seconds> --json;
                   unlock [ios|android] --slot <name> --json
@@ -3927,13 +4160,20 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
     stim stop --slot tablet
 
   All slots share this workspace's Metro server and build cache. Native CLI
-  runs serialize workspace mutations; a waiting run can wait up to 30 minutes.
+  runs serialize workspace mutations; a waiting run can wait up to 30 minutes
+  and prints what it waits for. \`stop --slot\` interrupts a build only for
+  its own slot or when it stops the workspace's only device (see STOP DURING
+  A BUILD).
   Named slots support local devices; remote sessions use the default slot.
   Names use 1-64 letters, digits, underscores or hyphens, starting with a letter
   or digit. Reserved object-property names are refused.
 
   stop --slot shuts down that slot's owned devices and releases its leases,
-  retaining Metro and sibling slots. Plain stop handles the whole workspace.
+  retaining Metro and sibling slots. stop --slot default targets only the
+  workspace's default device, the same one ios/android address with no
+  --slot and status reports with no [slot] label; it never touches a remote
+  session even though remote sessions use the default slot. Plain stop
+  handles the whole workspace.
   status reports named devices under slots and counts their memory. Device
   caps count every slot. Recycling uses the same model/runtime-matched pool
   for every slot, with one shared cap per platform and oldest-first eviction.
@@ -4094,8 +4334,11 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   says "happens on iPad on iOS 26.5" gets reproduced without writing a
   \`.stim.json\`. \`android --system-image <id>\` is the Android half, taking
   the sdkmanager package id
-  ("system-images;android-36;google_apis;arm64-v8a"). Each overrides its
-  setting (ios.deviceType, ios.runtime, android.systemImage) for that one
+  ("system-images;android-36;google_apis;arm64-v8a"), and
+  \`android --device-profile <id>\` picks the Android hardware profile, as
+  \`avdmanager list device -c\` spells it: "pixel_tablet" for a tablet,
+  "pixel_fold" for a foldable. Each overrides its setting (ios.deviceType,
+  ios.runtime, android.systemImage, android.deviceProfile) for that one
   invocation, exactly as \`--configuration\` overrides ios.configuration.
 
   A name that is not INSTALLED on this machine refuses with STIM_BAD_ARG
@@ -4117,11 +4360,13 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
   ALREADY owns a simulator and \`--device-type\` names a different model,
   Stim refuses rather than silently booting the wrong one: reap the current
   sim with \`stim worktree remove\` (or \`stim gc --delete\`), then run
-  \`stim ios\` again to create the requested one. \`--runtime\` and
-  \`--system-image\` apply at creation only, so an existing device keeps the
-  version it was made with. The --json payload reports what was actually
-  used: \`deviceType\` and \`runtime\` on iOS, \`systemImage\` on Android,
-  read from the device itself, so a settings-driven run reports them too.`
+  \`stim ios\` again to create the requested one. \`--device-profile\` does
+  the same for an AVD of another profile. To keep both devices, give the new
+  one its own \`--slot\`. \`--runtime\` and \`--system-image\` apply at
+  creation only, so an existing device keeps the version it was made with.
+  The --json payload reports what was actually used: \`deviceType\` and
+  \`runtime\` on iOS, \`systemImage\` and \`deviceProfile\` on Android, read
+  from the device itself, so a settings-driven run reports them too.`
 			},
 			devices: {
 				summary: "ios --device and android --device on a phone: what the run skips, signing, the LAN wiring, the collector",
@@ -4318,6 +4563,12 @@ HOLDING A DEVICE ACROSS RUNS
   With no id, \`lock\` and a \`--device\` run pick from the POOL of connected
   devices, so two phones on one machine no longer refuse.
 
+  An id may also name this workspace's own Stim-owned simulator (UDID) or
+  running emulator (\`emulator-NNNN\`), in any slot; \`--slot\`, if given,
+  must match it. Status then reports the device \`driven by stim device
+  lock\`, so other agents leave it alone. A workspace holds one lease per
+  platform and slot, so this refuses while the slot leases a phone.
+
 THE POOL: WHICH DEVICE AN ID-LESS \`--device\` PICKS
   Candidates are the connected devices the resolver already accepts: on iOS,
   paired, with Developer Mode on, over a cable or Wi-Fi; on Android, every
@@ -4968,7 +5219,8 @@ Resolution order, first match wins:
   1. workspace       ~/.stim/config.json, under this project's entry
   2. repo            ~/.stim/config.json, under this repo's git common dir
   3. committed       .stim.json beside the app's package.json
-  4. machine         ~/.stim/config.json, top-level optimizations only
+  4. machine         ~/.stim/config.json, top-level optimizations and
+                     android.deviceProfile only
   5. Stim default
 An environment override, where a setting has one, wins over every layer.
 
@@ -5061,9 +5313,27 @@ KEYS STIM READS
                         from. The \`--system-image\` flag overrides this per
                         invocation, and an id this SDK has not installed is
                         STIM_BAD_ARG with the installed ids printed.
-                        New AVDs use the Pixel 6 hardware profile (1080x2400,
-                        420 dpi). Existing AVDs keep their display settings;
-                        parked AVDs from the old generic profile are not adopted.
+  android.deviceProfile e.g. "pixel_fold" -- the avdmanager hardware profile a
+                        new owned AVD is created with, spelled exactly as
+                        \`avdmanager list device -c\` prints it. Defaults to
+                        pixel_6 (1080x2400, 420 dpi); "pixel_tablet" and
+                        "pixel_fold" give a tablet and a foldable, and
+                        avdmanager writes the foldable's hinge and posture
+                        keys from its profile. Readable from the machine
+                        layer too, so one machine can default every workspace
+                        to a tablet. A set profile counts as a request: each
+                        run then checks it with avdmanager (about 2s), and a
+                        workspace that already owns an AVD of another profile
+                        refuses until that AVD is reaped. The \`--device-profile\` flag overrides it
+                        per invocation, and an id avdmanager does not offer is
+                        STIM_BAD_ARG with the offered ids printed; that check
+                        runs avdmanager only when a profile is given. A
+                        parked AVD is adopted only by a request for its own
+                        profile. When this workspace already owns an AVD of
+                        another profile, a requested profile refuses rather
+                        than booting it; reap the AVD to create the new one.
+                        Existing AVDs keep their display settings; parked AVDs
+                        from the old generic profile are not adopted.
   android.dataPartitionSizeGb
                         whole GiB for a newly created owned AVD's data
                         partition. Defaults to 8; accepts 6 through 16384.
@@ -5093,7 +5363,9 @@ ${ANDROID_AVD_CONFIG_HELP.map((line) => `                          ${line}`).joi
                         On displayless Linux, Stim launches with
                         -gpu swiftshader_indirect -noaudio; those arguments
                         override hw.gpu.enabled, hw.gpu.mode, hw.audioInput,
-                        and hw.audioOutput for that headless launch.
+                        and hw.audioOutput for that headless launch. With
+                        androidEmulatorApp "stim-desktop" on macOS, -gpu host
+                        overrides hw.gpu.mode the same way.
   android.variant       e.g. "productionDebug" -- the gradle variant to
                         assemble and install on a project with product
                         flavors. A repo like tlon-mobile with
@@ -5296,6 +5568,22 @@ window shuts down that simulator. Enable "Leave simulator running after window
 is closed" in Siniulator Settings if Stim should keep it running. See \`guide lifecycle simslim\` for
 window behavior.
 
+THE ANDROID EMULATOR APP IS MACHINE-LEVEL
+Top-level \`androidEmulatorApp\` in ~/.stim/config.json selects how an owned
+Android emulator that Stim boots on macOS is displayed. Unset or
+\`"emulator"\` opens the emulator's own window. To boot it headlessly and show
+it in Stim Desktop instead:
+
+  { "androidEmulatorApp": "stim-desktop" }
+
+Stim then starts the emulator with \`-no-window -gpu host\` and opens
+\`stim-desktop://open?serial=<serial>\` in the background. Stim Desktop reads
+frames and sends input over the emulator's gRPC endpoint. The setting applies
+only when Stim boots the emulator: one that is already running keeps its
+current display until it next boots, and physical devices are unaffected.
+An invalid value refuses before boot. On Linux and Windows the setting has
+no effect.
+
 THE DEVICE POOL BOUNDS ARE MACHINE-LEVEL TOO
 \`pool.iosParkedMax\` caps how many parked simulators \`worktree remove\` may
 leave behind for a later workspace to adopt. It is machine-level for the same

package/dist/{idle--jn7pBNe.mjs → idle-NETbeNiQ.mjs}

@@ -1,9 +1,10 @@
 import { H as projectDeviceSlots } from "./config-BEq0Qw_a.mjs";
 import { m as readWorkspaceState } from "./metro-BWLOJ_Wr.mjs";
 import { o as formatLongDuration } from "./command-output-D5z2_bcF.mjs";
-import { c as createActivityReader, l as idleForMs, o as parseActiveBuild, r as activeBuildState, t as ACTIVE_BUILD_KEY } from "./build-progress-BXx-ZBe4.mjs";
-import { N as ownedAvdSerialResolver } from "./android-787HhP5w.mjs";
-import { d as teardownOwnedAvd, f as teardownOwnedIosSim } from "./ownership-BfPNRf3-.mjs";
+import { n as createActivityReader, r as idleForMs } from "./activity-BtG4Va9l.mjs";
+import { I as ownedAvdSerialResolver } from "./android-C4zG2Tuc.mjs";
+import { d as teardownOwnedAvd, f as teardownOwnedIosSim } from "./ownership-BiojdtAp.mjs";
+import { r as activeBuildState, s as parseActiveBuild, t as ACTIVE_BUILD_KEY } from "./build-progress-CDwogz6R.mjs";
 import chalk from "chalk";
 //#region src/commands/gc/idle.ts
 function findOwnedDeviceActivity({ config, sims, androidSerial, readActivity, deadProjects = [] }) {

package/dist/{in-use-CNIWU-r-.mjs → in-use-DVhlSoyn.mjs}

@@ -1,10 +1,10 @@
 import { f as getProject, k as ownership_claim_exports, u as getConfigDir } from "./config-BEq0Qw_a.mjs";
 import { O as workspaceDir, m as readWorkspaceState } from "./metro-BWLOJ_Wr.mjs";
-import { r as stopDeclaringSpawnsOn, t as declareSpawnsOn } from "./spawn-claims-CUleC2cM.mjs";
-import { n as workspaceProcessLockError, r as workspaceProcessLockPath, t as withWorkspaceProcessLock } from "./workspace-process-lock-BXA96myD.mjs";
+import { n as declareSpawnsOn, o as stopDeclaringSpawnsOn } from "./spawn-claims-BJwXTMPt.mjs";
+import { n as workspaceProcessLockError, r as workspaceProcessLockPath, t as withWorkspaceProcessLock } from "./workspace-process-lock-Cx74RSDZ.mjs";
 import { a as formatElapsed } from "./command-output-D5z2_bcF.mjs";
-import { h as listBuildLocks } from "./device-lease-CbEaIk7b.mjs";
-import { n as managedLockHolders, t as resolveSupervisorTarget } from "./ownership-BfPNRf3-.mjs";
+import { h as listBuildLocks } from "./device-lease-D83nqeMX.mjs";
+import { n as managedLockHolders, t as resolveSupervisorTarget } from "./ownership-BiojdtAp.mjs";
 import { lstatSync, readdirSync, rmSync, rmdirSync, statSync, unlinkSync } from "node:fs";
 import { realpathSync as realpathSync$1 } from "fs";
 import { resolve } from "path";