stim 1.10.1 → 1.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. package/dist/{build-progress-BXx-ZBe4.mjs → activity-CCZJs__P.mjs} +9 -182
  2. package/dist/{android-787HhP5w.mjs → android-75Sk2rIR.mjs} +81 -19
  3. package/dist/{android-Bu4mbDzc.mjs → android-B7X-8H7h.mjs} +426 -106
  4. package/dist/{android-DPov-fv2.mjs → android-BQiKJYK0.mjs} +1 -1
  5. package/dist/{android-cas-CITmIeWY.mjs → android-cas-DzLPXiEn.mjs} +7 -7
  6. package/dist/{app-install-Cfmqr3TQ.mjs → app-install-CsZi0SAT.mjs} +1 -1
  7. package/dist/{workspaces-wrH6dXfu.mjs → budget-DbzW5VTD.mjs} +651 -32
  8. package/dist/{dev-client-DExzPiOa.mjs → build-plan-CqntbR7b.mjs} +514 -38
  9. package/dist/build-progress-h60GPV27.mjs +179 -0
  10. package/dist/{cache-manifest-Pubfp8wV.mjs → cache-manifest-DWPF4RKJ.mjs} +1 -1
  11. package/dist/cache-manifest.mjs +1 -1
  12. package/dist/cli.mjs +16 -16
  13. package/dist/collector-run.mjs +4 -4
  14. package/dist/{command-output-D5z2_bcF.mjs → command-output-BWCj5Vh-.mjs} +1 -1
  15. package/dist/{config-BEq0Qw_a.mjs → config-0jCcMM0E.mjs} +10 -1
  16. package/dist/{dependency-state-r9UesA9a.mjs → dependency-state-DNN0yfx6.mjs} +1 -1
  17. package/dist/{deps-DP4eWqea.mjs → deps-CO-_7UOm.mjs} +2 -2
  18. package/dist/{device-Czh5kO8A.mjs → device-9r9xRYDa.mjs} +49 -11
  19. package/dist/{device-lease-CbEaIk7b.mjs → device-lease-B9LAXIUH.mjs} +55 -55
  20. package/dist/{device-pool-BBWLAr55.mjs → device-pool-BoezJd-c.mjs} +4 -4
  21. package/dist/{device-remote-powUHdbK.mjs → device-remote-C0_o-tJH.mjs} +254 -579
  22. package/dist/{doctor-CmqK1LcQ.mjs → doctor-LfDlbR-N.mjs} +20 -19
  23. package/dist/{error-diagnostics-xxWKNO3-.mjs → error-diagnostics-CCxjn31V.mjs} +7 -7
  24. package/dist/{gc-zCDpmdHU.mjs → gc-C4nQFcTX.mjs} +220 -282
  25. package/dist/{guide-DwmaD_Wa.mjs → guide-BPBlh9ML.mjs} +512 -73
  26. package/dist/{guide-status-CWvti2Lg.mjs → guide-status-i9ogHt4v.mjs} +2 -2
  27. package/dist/{idle--jn7pBNe.mjs → idle-S3tFZ53_.mjs} +7 -6
  28. package/dist/{in-use-CNIWU-r-.mjs → in-use-D9XYEgFD.mjs} +7 -7
  29. package/dist/{ios-CbdqTqOc.mjs → ios-CDzWL1mj.mjs} +302 -88
  30. package/dist/{ios-COGcGEcN.mjs → ios-CZWOHTTc.mjs} +24 -19
  31. package/dist/{ios-device-DNjPXBnb.mjs → ios-device-D9cLxVr5.mjs} +1 -1
  32. package/dist/{launch-verify-BhgkYAws.mjs → launch-verify-B2oR_kFN.mjs} +2 -2
  33. package/dist/logs-SzuYudOj.mjs +485 -0
  34. package/dist/merge-state-ytFQCeh4.mjs +262 -0
  35. package/dist/{metro-BWLOJ_Wr.mjs → metro-Dzo30hvJ.mjs} +1 -1
  36. package/dist/{named-ports-DiTfSz6p.mjs → named-ports-Dn1o61D9.mjs} +3 -3
  37. package/dist/{ownership-BfPNRf3-.mjs → ownership-B8d4kXBx.mjs} +49 -16
  38. package/dist/{ownership-D2xbLVoz.mjs → ownership-Dqnrjrio.mjs} +2 -2
  39. package/dist/{ports-CLSSFOuz.mjs → ports-Dp_QTwTC.mjs} +3 -3
  40. package/dist/{project-BXZzOABt.mjs → project-B8rbutVC.mjs} +4 -72
  41. package/dist/{reload-CymyF6Kk.mjs → reload-nocmx8KB.mjs} +9 -9
  42. package/dist/remote-cache-BRsRZru5.mjs +526 -0
  43. package/dist/{server-bare-DVbb7kXH.mjs → server-bare-Gn3ssSdK.mjs} +1 -1
  44. package/dist/{server-expo-BvOCeakp.mjs → server-expo-CeT1nIIk.mjs} +2 -2
  45. package/dist/server-expo-eWi9Coof.mjs +2 -0
  46. package/dist/{settings-DOugPlPz.mjs → settings-BlyDn2Oz.mjs} +14 -5
  47. package/dist/{settings-EWYNwe72.mjs → settings-bE-Gu3Ti.mjs} +23 -11
  48. package/dist/settings.schema.json +73 -1
  49. package/dist/{simslim-DZUxzsjq.mjs → simslim-COtEEP7x.mjs} +152 -96
  50. package/dist/{slot-launch-Dk4oTREM.mjs → slot-launch-DIACGEfH.mjs} +4 -4
  51. package/dist/{spawn-claims-CUleC2cM.mjs → spawn-claims-PT8aQpCa.mjs} +25 -2
  52. package/dist/{start-qWapeB4W.mjs → start-BFstVBlx.mjs} +1 -1
  53. package/dist/{start-RbmFPeZ7.mjs → start-BboE1HIS.mjs} +108 -17
  54. package/dist/{state-WGdIbi_d.mjs → state-DcDgzfu3.mjs} +15 -3
  55. package/dist/{stats-BAgJaLA4.mjs → stats-D8rUTPHd.mjs} +1 -1
  56. package/dist/{stats-DBYJ5bxL.mjs → stats-DiCtmluY.mjs} +4 -4
  57. package/dist/{status-Dr4fRkym.mjs → status-BUASYyy_.mjs} +92 -33
  58. package/dist/{status-Zp8kvexe.mjs → status-DI9Tjo7T.mjs} +255 -38
  59. package/dist/stim-desktop-D0xhpZt8.mjs +29 -0
  60. package/dist/stop-BI7QY76M.mjs +3 -0
  61. package/dist/{stop-DcEv5sk-.mjs → stop-Bn6v-GvS.mjs} +205 -37
  62. package/dist/supervisor-run.mjs +11 -11
  63. package/dist/{workspace-process-lock-BXA96myD.mjs → workspace-process-lock-BvvJTfo_.mjs} +10 -5
  64. package/dist/{worktree-DEG2o9F8.mjs → worktree-B5sTRskL.mjs} +1 -1
  65. package/dist/{worktree-Bd4dRvx7.mjs → worktree-ChDL5fO1.mjs} +17 -16
  66. package/dist/{worktree-BlizKDpZ.mjs → worktree-DeBQSVtR.mjs} +3 -1
  67. package/dist/{xcode-B2tBkf0m.mjs → xcode-BzplpQzc.mjs} +7 -7
  68. package/package.json +5 -5
  69. package/dist/budget-nDCEwtJv.mjs +0 -620
  70. package/dist/logs-MARIy6m9.mjs +0 -209
  71. package/dist/server-expo-DBVTdult.mjs +0 -2
  72. package/dist/stop-DI4BG4Os.mjs +0 -3
@@ -1,6 +1,7 @@
1
- import { o as findProjectRoot } from "./project-BXZzOABt.mjs";
2
- import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-DOugPlPz.mjs";
3
- import { t as guideStatus } from "./guide-status-CWvti2Lg.mjs";
1
+ import { i as findProjectRoot } from "./project-B8rbutVC.mjs";
2
+ import { t as ANDROID_AVD_CONFIG_HELP } from "./settings-BlyDn2Oz.mjs";
3
+ import { t as RECENT_LAUNCH_MS } from "./status-BUASYyy_.mjs";
4
+ import { t as guideStatus } from "./guide-status-i9ogHt4v.mjs";
4
5
  import { SETTINGS_SCHEMA_URL } from "@stim-cli/core/state";
5
6
  import chalk from "chalk";
6
7
  //#endregion
@@ -92,6 +93,10 @@ presence of eas.json does not select EAS or authorize building.
92
93
  Physical --device targets are supported. Follow EAS device-registration and
93
94
  rebuild remedies only when the session authorizes those account changes.
94
95
 
96
+ To learn whether the next build is a cache hit and how long it should take,
97
+ without building, run stim ios --plan (or stim android --plan); see stim guide
98
+ lifecycle builds.
99
+
95
100
  Read stim guide lifecycle concurrency when a build waits on another workspace
96
101
  or a build call times out. A native build can outlive a shell timeout; if the
97
102
  tool call timed out, retry the same command and follow its printed remedy if
@@ -173,7 +178,8 @@ RULES DURING THE LOOP
173
178
  them. Use stim doctor when a build is unexpectedly slow or the environment
174
179
  looks incomplete. If status reports a changed Android serial, rerun stim
175
180
  android with the same build options to restore forwarding, then reopen your automation
176
- session on the reported serial (guide lifecycle).
181
+ session on the reported serial (guide lifecycle). Each status issue names a
182
+ remedy to run from its workspace (guide facts status).
177
183
 
178
184
  OWNERSHIP AND DELETION
179
185
 
@@ -228,7 +234,9 @@ Ask the user before these actions:
228
234
  - stop when the workspace owns an EAS session, because it irreversibly ends
229
235
  that remote session. For a local device, stop shuts it down but does not
230
236
  delete it. An explicit stop shuts down a Stim-owned simulator even when
231
- another process uses it. It never shuts down an unowned simulator.
237
+ another process uses it. It never shuts down an unowned simulator. It also
238
+ cancels an ios or android run still building for the device it stops
239
+ (guide lifecycle).
232
240
 
233
241
  LEAVE THE MACHINE CLEAN
234
242
 
@@ -236,7 +244,11 @@ Run stim stop when you pause or finish a task, and stim worktree remove once
236
244
  it is merged or abandoned. Never create a simulator or emulator by hand;
237
245
  every device comes from Stim. Before starting a new workspace, check stim
238
246
  status for an idle workspace to reuse and confirm capacity headroom instead of
239
- adding another.
247
+ adding another. Never quit Device Hub or Simulator.app: on Xcode 27
248
+ (confirmed on 27A266a), quitting Device Hub by default shuts down every booted
249
+ simulator on the machine, including ones it never opened a window for and
250
+ ones other workspaces or agents are using. Use stim stop on workspaces you
251
+ own instead.
240
252
 
241
253
  SANDBOXES
242
254
 
@@ -299,7 +311,7 @@ FULL TOPIC LIST
299
311
  stim guide lifecycle builds # build optimizations, optional cache warm-up, fingerprints
300
312
  stim guide lifecycle concurrency # shared builds, wait timeouts, capacity limits
301
313
  stim guide lifecycle budget # disk and memory budgets, automatic reclaim
302
- stim guide lifecycle options # every flag, Android variants, --device-type, --system-image
314
+ stim guide lifecycle options # every flag, Android variants, --device-type, --system-image, --device-profile
303
315
  stim guide lifecycle devices # ios --device and android --device on a physical phone
304
316
  stim guide lifecycle release # Release configurations and ...Release variants
305
317
  stim guide facts # the --json payloads
@@ -312,7 +324,7 @@ FULL TOPIC LIST
312
324
  stim guide settings # configuration files and supported keys`
313
325
  },
314
326
  facts: {
315
- summary: "The --json payloads: `start`, `ios`, `android`, `reload`, `stop`, `status`, `doctor`, `device lock`/`unlock`, `gc`, and the error contract",
327
+ summary: "The --json payloads: `start`, `ios`, `android`, `ios|android --plan`, `reload`, `stop`, `status`, `doctor`, `device lock`/`unlock`, `gc`, and the error contract",
316
328
  preamble: () => `SLOTS
317
329
  Named ios/android runs add slot to their JSON facts. Default-run fields remain
318
330
  compatible. status adds a slots array per environment with each named slot's
@@ -331,12 +343,38 @@ status's unprovisionedWorktrees lists the linked worktrees with no Stim
331
343
  environment in every repository with a registered environment, plus the
332
344
  repository status runs from. A worktree counts as having an
333
345
  environment when one is registered at it or inside it. Each entry is
334
- { path, branch, repository }; repository is the main checkout, or the git
335
- directory of a bare repository. status reads git's own worktree records and
336
- never opens the worktree directories, so a worktree under a macOS-protected
337
- folder such as ~/Documents is listed without a privacy prompt.
346
+ { path, branch, repository, git }; repository is the main checkout, or the git
347
+ directory of a bare repository. status lists worktrees from git's own worktree
348
+ records, and on macOS runs no git in a worktree with no environment under a
349
+ protected folder such as ~/Documents, so listing it raises no privacy prompt.
338
350
  \`worktree warm\` does not create an environment; \`start\`, \`ios\`,
339
- \`android\` and \`doctor\` register it.
351
+ \`android\` and \`doctor\` register it. An environment's worktree is the
352
+ linked worktree it is registered at or inside.
353
+
354
+ Each worktree entry, in unprovisionedWorktrees and in an environment's
355
+ worktree, carries git:
356
+
357
+ git { changed, untracked, upstream, ahead, behind, mergedInto }, or
358
+ null when git fails or does not answer within 3 s, or the
359
+ worktree has no environment and sits in ~/Desktop, ~/Documents,
360
+ ~/Downloads, iCloud Drive, ~/Library/CloudStorage or /Volumes,
361
+ which status does not open on macOS
362
+ changed tracked paths with staged or unstaged changes, conflicts included
363
+ untracked untracked entries as git status lists them; a new directory
364
+ counts once
365
+ upstream the branch's upstream, such as "origin/feat/x", or null
366
+ ahead commits on HEAD and not on upstream; null with no upstream, or
367
+ behind when the upstream branch no longer exists
368
+ mergedInto "origin/<default>" when gc would call the branch merged, judged
369
+ from local refs without fetching, else null
370
+
371
+ status runs \`git status --porcelain=v2 --branch\` in every worktree in
372
+ parallel, and caches the merge verdict by HEAD and default-branch commit
373
+ under $STIM_HOME/git-merge. One call starts no new merge check 250 ms after
374
+ its first; later calls judge the rest, and until then a verdict for the same
375
+ HEAD at an older default-branch commit stands in. \`status --watch\` reuses a worktree's git read
376
+ for 5 s. Plain status prints "git: 2 changed, 1 untracked, ahead 3" under
377
+ each environment, and the same after each worktree with no environment.
340
378
 
341
379
  status's remoteDevices lists each environment's recorded EAS Simulator
342
380
  session. The session is billable while it runs, and it makes the environment
@@ -518,6 +556,10 @@ per session, with the preview URL.`,
518
556
  android.systemImage setting reports it too, not only a
519
557
  \`--system-image\` run. Null on \`--device\` and on an
520
558
  emulator Stim does not own
559
+ deviceProfile the avdmanager hardware profile of the owned AVD
560
+ ("pixel_6", "pixel_fold"), read from its config.ini
561
+ hw.device.name. Null where systemImage is null, and on an
562
+ AVD of the old generic profile, which has no hw.device.name
521
563
  fingerprint / cacheKey / cacheHit / cacheSkipped / waitedForBuild /
522
564
  appPath / installSkipped / launched
523
565
  as above -- cacheKey keys on the VARIANT here
@@ -640,6 +682,19 @@ ON FAILURE
640
682
  \`reclaimed\` is present the same way as on success when the run reclaimed
641
683
  before failing, including a STIM_LOW_DISK refusal.
642
684
 
685
+ An \`ios\` or \`android\` run that \`stim stop\` or Ctrl-C interrupted
686
+ reports STIM_CANCELLED and exits 130. A
687
+ run that exits on the interrupt at once (a second SIGINT, a physical-device
688
+ lease, Ctrl-C with no build tool running) exits 130 with no payload.
689
+
690
+ \`stop --json\` prints { root, ok, supervisor, collectors, metro, device,
691
+ port, metroTunnel, releasedLeases }. When it cannot end the \`ios\` or
692
+ \`android\` run holding the workspace, it prints the error contract with
693
+ root and ok: false instead, plus device.remote when it ended a recorded EAS
694
+ session first, and exits 1:
695
+
696
+ { "root": "...", "ok": false, "code": "STIM_STOP_BLOCKED", "message": "...", "remedy": "..." }
697
+
643
698
  Branch on \`code\`, never on the message text. \`guide errors\` enumerates
644
699
  every code.
645
700
 
@@ -787,16 +842,18 @@ RULES
787
842
  orphanedWorkspaces { dir, projectRoot, bytes } --delete removes the
788
843
  whole workspace directory
789
844
  linkedWorktrees { path, idleDays, mergedInto, willRemove,
790
- reason, detail } mergedInto is the default
791
- branch HEAD is merged into ("origin/main"),
792
- or null; detail says why it is removed
793
- ("merged into origin/main", "idle 9d") or kept.
794
- Without --worktrees, the source checkout and
795
- roots outside git are left out
845
+ reason, detail, eligibleAt } mergedInto is
846
+ the default branch HEAD is merged into
847
+ ("origin/main"), or null; detail says why it
848
+ is removed ("merged into origin/main", "idle
849
+ 9d") or kept. eligibleAt is the ISO time a
850
+ recent-activity worktree becomes removable,
851
+ else null. Without --worktrees, the source
852
+ checkout and roots outside git are left out
796
853
  parkedSimulators { udid, name, model, runtime, parkedAt, bytes,
797
854
  listed } with --older-than, only those parked
798
855
  at least that long
799
- parkedEmulators { name, systemImage, parkedAt, bytes, listed }
856
+ parkedEmulators { name, systemImage, deviceProfile, parkedAt, bytes, listed }
800
857
  likewise
801
858
  orphanedDevices { kind, id, name, bytes, directory }
802
859
  unverifiedDevices { kind, id, name, command } stim-* devices Stim
@@ -846,7 +903,8 @@ RULES
846
903
  locked | in-use | status-unreadable | dirty |
847
904
  unpushed-unchecked | unpushed | submodules |
848
905
  not-merged | merge-unknown | last-use-unknown |
849
- recently-used
906
+ recently-used | activity-unknown |
907
+ recent-activity
850
908
 
851
909
  These print the error contract instead and exit 1:
852
910
 
@@ -857,9 +915,47 @@ RULES
857
915
  - --cache together with --worktrees or --idle`
858
916
  },
859
917
  status: {
860
- summary: "the status payload's build and device activity fields: a running build, its estimate, and who drives each device",
918
+ summary: "the status payload's issues and their codes, build and device activity fields: a running build, its estimate, each platform's last build, and who drives each device",
861
919
  body: () => ` stim status --json
862
920
 
921
+ Each environment carries issues, the things in that workspace that need
922
+ the user, and warnings, the same issues as text ("<slot>: " when not the
923
+ default slot, then "<message>; run \`<remedy>\`"):
924
+
925
+ issues [{ code, severity, message, remedy, workspace, slot? }]
926
+
927
+ code port-not-ours something other than this workspace's
928
+ Metro answers its reserved port
929
+ sim-missing the recorded simulator no longer exists
930
+ sim-without-metro the simulator is booted and no Metro
931
+ serves the workspace
932
+ avd-serial-changed the owned emulator came back on another
933
+ serial, so Metro forwarding is lost
934
+ avd-missing the recorded AVD no longer exists
935
+ avd-not-detected adb does not see the owned emulator while
936
+ the workspace expects it: it holds an
937
+ unexpired lease on its serial, or it
938
+ launched onto it and has not stopped
939
+ that slot since, and its dev server runs
940
+ or the launch was in the last
941
+ ${RECENT_LAUNCH_MS / 6e4} minutes. An idle workspace's
942
+ shut-down emulator is android.state
943
+ "not-detected" with no issue.
944
+ avd-unchecked the emulator listing could not be read
945
+ supervisor-unverified a supervisor record whose process status
946
+ cannot prove gone or ours; stop refuses to
947
+ signal it
948
+ severity "error" when stop or start refuses until it is resolved, else
949
+ "warning"
950
+ remedy a command to run from workspace, such as "stim android --slot
951
+ fold"
952
+ slot absent for the default slot
953
+
954
+ A supervisor record whose pid is gone or reused is not an issue: status
955
+ reports supervisor null, and the next stop or start clears the record.
956
+ \`stop --slot <name>\` forgets that slot's launch, so a device stopped on
957
+ purpose is not reported while the shared dev server keeps running.
958
+
863
959
  Each booted simulator and detected emulator in environments (and in
864
960
  slots) carries activity; a shut-down or physical device has none:
865
961
 
@@ -926,8 +1022,75 @@ RULES
926
1022
 
927
1023
  build: ios compile, 1m10s elapsed -- about 3 min left (median of 4 cold runs)
928
1024
 
1025
+ An environment with a recorded run also carries lastBuilds, each
1026
+ platform's most recent ios or android run, finished or failed:
1027
+
1028
+ lastBuilds { ios?, android? }, each { platform, status, cacheHit,
1029
+ cacheSkipped, durationMs, fingerprint, startedAt, finishedAt,
1030
+ errorCode?, missReason? }
1031
+
1032
+ status "ok" or "failed"
1033
+ cacheHit "local" or "remote" for an app from that cache tier; false
1034
+ for an ok run that compiled, or a failed run that had none
1035
+ durationMs the run's wall time; finishedAt is startedAt plus it. Both
1036
+ are null when the record carries no duration.
1037
+ fingerprint the key's fingerprint after any prebuild or pod install
1038
+ missReason only on a run that did not install a cached app (it
1039
+ compiled, or failed before finding one): { kind, summary, changes,
1040
+ changeCount, baseline, rekeyedBy }. kind is "changed",
1041
+ "no-baseline", "same-sources", "cache-skipped" or
1042
+ "fingerprint-error"; summary names the cause, such as
1043
+ "native dependency added: expo-clipboard". changes holds up to
1044
+ 20 { source, change, category } of changeCount changed sources;
1045
+ baseline is { fingerprint, from: "workspace" | "project" }, the
1046
+ cached build compared with; rekeyedBy lists "prebuild" or
1047
+ "pod install" when those steps moved the key.
1048
+
1049
+ Plain status prints "last build: ios local cache in 12s, android compiled
1050
+ in 7m02s". To predict the next run instead, see \`guide facts plan\`.
1051
+
929
1052
  There is no completion fraction: a compile's log volume depends on what
930
1053
  is already built, so it does not measure progress.`
1054
+ },
1055
+ plan: {
1056
+ summary: "the ios and android --plan payload: fingerprint, cacheHit, prebuild, missReason, expectedMs and basis",
1057
+ body: () => ` stim ios --plan --json # or: stim android --plan --json
1058
+
1059
+ { platform, slot?, fingerprint, cacheKey, cacheHit, provider,
1060
+ cacheSkipped, prebuild, outcome, expectedMs, basis, missReason?,
1061
+ refusal? }
1062
+
1063
+ fingerprint the fingerprint the run would look up first; with
1064
+ --eas-profile, the one EAS CLI computes
1065
+ cacheKey the key under that fingerprint; null for an EAS miss
1066
+ cacheHit "local", "remote", or false for a miss
1067
+ provider the remote tier that answered, "eas" with --eas-profile,
1068
+ otherwise null
1069
+ cacheSkipped true when cache reads are off (--no-build-cache or config)
1070
+ prebuild on a miss, the run's decision for the native dir: "none",
1071
+ "generate", "regenerate" or "refuse"; null on a hit
1072
+ outcome "hit" or "cold"; null when the run would refuse
1073
+ expectedMs the median wall time of this project's last successful runs
1074
+ with that outcome on that platform, or null with none
1075
+ basis how many runs expectedMs comes from (at most 10)
1076
+ missReason on a predicted cold build with cache reads on, why the
1077
+ cache has no app, in the shape of lastBuilds.<platform>
1078
+ .missReason (\`guide facts status\`), compared with the same
1079
+ baseline the run would use. kind is "changed",
1080
+ "no-baseline", "same-sources" or "prebuild-pending": a
1081
+ baseline exists and the run would prebuild first, which the
1082
+ plan does not, so changes compare the fingerprint before that
1083
+ prebuild; changeCount 0 then means those inputs match the
1084
+ baseline. rekeyedBy is empty.
1085
+ refusal { code, message, remedy } when the run would refuse:
1086
+ STIM_PREBUILD_FAILED for a tracked native dir the fingerprint
1087
+ leaves out, STIM_EAS_BUILD_MISSING for an EAS miss
1088
+
1089
+ A plan that would refuse still exits 0: the payload is the answer. A plan
1090
+ that cannot be computed prints the error contract and exits 1, for example
1091
+ STIM_NO_FINGERPRINT, STIM_EAS_UNAVAILABLE, or STIM_BAD_ARG for a flag that
1092
+ picks a device. When and why a plan and the run can differ: \`guide
1093
+ lifecycle builds\`.`
931
1094
  },
932
1095
  stats: {
933
1096
  summary: "the stats payload, what counts as a run, hit, miss and failed, timeSavedMs, the heartbeat estimate",
@@ -1051,9 +1214,12 @@ REMOTE DEVICE BACKENDS
1051
1214
  AGENT_DEVICE_DAEMON_AUTH_TOKEN. Stim creates no remote session for it.
1052
1215
 
1053
1216
  The EAS backend needs eas-cli 21.6.0 or later and an account with EAS
1054
- Simulator access. An EAS session is billable. EAS does not inherit the proxy
1055
- credentials. Always tear the session down: \`stop\`, \`worktree remove\`,
1056
- and \`gc --delete\` can end sessions that Stim proves it owns.
1217
+ Simulator access. An EAS session is billable. Stim prepares the app before
1218
+ it creates or reconnects the session, so a failed build starts no session
1219
+ and the install follows the connection directly. EAS does not inherit the
1220
+ proxy credentials. Always tear the session down: \`stop\`,
1221
+ \`worktree remove\`, and \`gc --delete\` can end sessions that Stim proves
1222
+ it owns.
1057
1223
  \`stim status\` lists each recorded session with its preview URL (see
1058
1224
  \`guide facts\`).
1059
1225
 
@@ -1252,8 +1418,8 @@ usually untagged: use an unfiltered workspace query to inspect those errors.
1252
1418
 
1253
1419
  FLAGS
1254
1420
  --slot <name> only this slot's records (default includes untagged records)
1255
- --source <s...> metro, client, device, build (one or more), or all. An
1256
- unknown value is REJECTED rather than quietly matching
1421
+ --source <s...> metro, client, device, build, agent (one or more), or all.
1422
+ An unknown value is REJECTED rather than quietly matching
1257
1423
  nothing.
1258
1424
  --level <l> minimum level: debug, info, warn, error, fatal
1259
1425
  --since <d> only records newer than this: 30s, 5m, 2h
@@ -1344,7 +1510,7 @@ FLAGS
1344
1510
 
1345
1511
  THE RECORD
1346
1512
  { ts, src, level, msg } always. ts is epoch milliseconds; src is one of
1347
- metro / client / device / build; level is one of the five above.
1513
+ metro / client / device / build / agent; level is one of the five above.
1348
1514
  Optional fields:
1349
1515
  event the producer's own event name (bundle_build_done, client_log, ...)
1350
1516
  stack frames of { file, line, column, fn }, passed through as reported
@@ -1493,6 +1659,21 @@ WHAT WRITES WHAT
1493
1659
  archive rather than a stream. Streaming with full fidelity needs
1494
1660
  libimobiledevice or pymobiledevice3, which are third-party installs Stim
1495
1661
  does not require. See appandflow/stim#179.
1662
+ agent no file. Each query reads agent-device's session
1663
+ records (~/.agent-device/sessions, or
1664
+ AGENT_DEVICE_STATE_DIR) for this workspace's owned
1665
+ simulators and emulators, read-only. An action is
1666
+ info (msg is agent-device's summary, e.g. "Tapped
1667
+ (201, 731)"; event agent_action with command, session,
1668
+ deviceId and details); a failed command is error
1669
+ (event agent_failed). A plain query includes them;
1670
+ --errors only with --source agent or all. iOS sessions
1671
+ match a simulator through their runner.log, Android
1672
+ sessions only while agent-device's claim on the
1673
+ emulator is live (released claims drop their
1674
+ actions from later queries). A session in an
1675
+ unrecognized format yields one warn record
1676
+ (agent_format_unknown) instead of its actions.
1496
1677
  build-ios.ndjson the xcodebuild / gradle transcript at level debug, the
1497
1678
  build-android.ndjson extracted diagnostics at level error, and the launch as
1498
1679
  a marker record. One RUN's worth: each build starts the
@@ -2122,7 +2303,12 @@ so a Debug run on one is wired to a LAN origin instead of localhost.`,
2122
2303
  The project already owns a simulator of a different model, and Stim will
2123
2304
  not silently boot a different one. Reap it (\`worktree remove\`, or
2124
2305
  \`gc --delete\`) and run \`stim ios\` again to create the requested model.
2125
- That loses the old sim's app state.`
2306
+ That loses the old sim's app state.
2307
+
2308
+ "this project's emulator uses device profile X, but Y was requested"
2309
+ The Android counterpart, from \`--device-profile\` or android.deviceProfile.
2310
+ Reap the AVD the same way, or pass \`--slot <name>\` to create the requested
2311
+ profile beside it.`
2126
2312
  },
2127
2313
  STIM_DEVICE_BUSY: {
2128
2314
  summary: "another workspace holds the lease on that phone and the wait ran out",
@@ -2434,16 +2620,22 @@ captured" (in metro.ndjson, bare RN)
2434
2620
  nearest registered descendant app with logs when one exists), an
2435
2621
  android/app/build.gradle that declares product flavors with
2436
2622
  no variant selected (the refusal names the debug variants), or a
2437
- \`--device-type\`, \`--runtime\` or \`--system-image\` name that is BLANK or
2438
- is not installed on this machine. For the unknown-name case the installed
2439
- names are printed in the message -- the versions \`xcrun simctl list
2440
- runtimes\` reports, the models those runtimes can actually CREATE (not the
2441
- whole \`simctl list devicetypes\` table, which also names watchOS, tvOS and
2442
- visionOS models no iOS runtime offers), or the system images the SDK has --
2443
- so the remedy is to re-run with one of them. An ios.deviceType, ios.runtime
2444
- or android.systemImage setting is checked the same way, and the check applies
2623
+ \`--device-type\`, \`--runtime\`, \`--system-image\` or \`--device-profile\`
2624
+ name that is BLANK or is not installed on this machine. For the
2625
+ unknown-name case the installed names are printed in the message -- the
2626
+ versions \`xcrun simctl list runtimes\` reports, the models those runtimes
2627
+ can actually CREATE (not the whole \`simctl list devicetypes\` table, which
2628
+ also names watchOS, tvOS and visionOS models no iOS runtime offers), the
2629
+ system images the SDK has, or the hardware profiles \`avdmanager list device
2630
+ -c\` offers -- so the remedy is to re-run with one of them. An
2631
+ ios.deviceType, ios.runtime, android.systemImage or android.deviceProfile
2632
+ setting is checked the same way, and the check applies
2445
2633
  even when this workspace ALREADY owns a device, so a name that could never
2446
- create anything is caught rather than left to a later run.
2634
+ create anything is caught rather than left to a later run. The
2635
+ \`pixel_fold\` and \`resizable\` profiles on a system image without
2636
+ foldable support (SupportPixelFold in its advancedFeatures.ini) refuse the
2637
+ same way, since the emulator quits on boot; the remedy names an installed
2638
+ image that has it, or an sdkmanager install when none does.
2447
2639
  \`gc --json --cache <name>\` refuses with STIM_BAD_ARG when no shared cache
2448
2640
  carries the name; the remedy names the caches on this machine. \`gc\`
2449
2641
  refuses --cache together with --worktrees the same way.
@@ -2455,7 +2647,8 @@ captured" (in metro.ndjson, bare RN)
2455
2647
  reporting that nothing was running.
2456
2648
  These errors are caught before the port is reserved and before any build or
2457
2649
  device work, so nothing was started. The one listing they need
2458
- (\`simctl list runtimes\`, the SDK's system-images directory) runs only when
2650
+ (\`simctl list runtimes\`, the SDK's system-images directory, \`avdmanager
2651
+ list device -c\`) runs only when
2459
2652
  a name was actually given, and a listing that fails is reported as
2460
2653
  STIM_NO_DEVICE naming the tool, never as a crash.`
2461
2654
  },
@@ -2471,14 +2664,57 @@ captured" (in metro.ndjson, bare RN)
2471
2664
  \`workspace removal\` -- both are \`stim worktree remove\`). Let it finish,
2472
2665
  then run the command again. \`start --remote\` reports this same case as
2473
2666
  STIM_WORKTREE_REMOVAL_IN_PROGRESS instead.`
2667
+ },
2668
+ STIM_CANCELLED: {
2669
+ summary: "an ios or android run was interrupted by `stim stop` or Ctrl-C before it finished",
2670
+ body: () => `STIM_CANCELLED (ios, android; exit 130)
2671
+ "The ios run was cancelled by \`stim stop\` (pid <n>) before it finished."
2672
+ The run received SIGINT: from \`stim stop\`, which interrupts a build it
2673
+ leaves with nothing to deploy to, or from Ctrl-C. It forwarded the interrupt
2674
+ to the build tool it was running (xcodebuild, Gradle, pod install, expo
2675
+ prebuild) and failed through its own cleanup; the next line names the step it
2676
+ stopped at. An interrupted build stores no artifact, so the next run looks
2677
+ up the cache as usual. Stopped between build tools, a run that \`stop\`
2678
+ cancelled starts no further build tool and stops before it installs. A
2679
+ second SIGINT exits at once, and so does a run that holds a physical-device
2680
+ lease; those exits print no payload. Run the same command again when you want the
2681
+ app on a device.`
2682
+ },
2683
+ STIM_STOP_BLOCKED: {
2684
+ summary: "`stop` could not interrupt the ios or android run holding this workspace; names its pid and claim",
2685
+ body: () => `STIM_STOP_BLOCKED (stop)
2686
+ \`stop\` found a live \`ios\` or \`android\` run holding this workspace's
2687
+ native-run claim and could not end it:
2688
+ - "... did not exit within 60s of SIGINT": the run was interrupted but is
2689
+ still running. Wait for it, or end it with the \`kill <pid>\` the remedy
2690
+ prints, then run \`stim stop\` again.
2691
+ - "... pid <n> is no longer that run; the build tool it started (pid <m>)
2692
+ still holds the claim": the run itself died and its build tool keeps the
2693
+ claim. Stim signals only a claim owner whose recorded identity it can
2694
+ prove, so it leaves the tool alone. Wait for pid <m> to exit or end it.
2695
+ On Windows this is the usual outcome of an interrupt: Node cannot deliver
2696
+ a catchable SIGINT to another process there, so the run ends at once and
2697
+ its Gradle build keeps the claim until it exits.
2698
+ A recorded EAS session is ended before this refusal: ending a billable
2699
+ session never waits on a build. The JSON payload carries the session
2700
+ outcome under device.remote. Devices, collectors and the dev server are left
2701
+ as they were.`
2474
2702
  },
2475
2703
  STIM_LOCK_TIMEOUT: {
2476
2704
  summary: "a lock held past the wait; workspace-process and short directory locks",
2477
2705
  body: () => `STIM_LOCK_TIMEOUT
2478
2706
  The same locks, held by an ordinary command that is still running, for
2479
- longer than the wait -- 60s by default, 4 minutes for the remote-session and
2480
- EAS project locks, and ~90 minutes for the \`worktree warm\` lock, which one
2481
- \`--refresh\` can hold for a whole dependency install. That wait prints its
2707
+ longer than the wait -- 60s by default, 4 minutes for the remote-session lock
2708
+ and for \`gc\` deleting EAS sessions under the EAS project lock (its sweep
2709
+ skips at once while that lock is held), and ~90 minutes for the \`worktree warm\` lock, which one
2710
+ \`--refresh\` can hold for a whole dependency install. The machine-wide EAS
2711
+ project lock admits one EAS session start at a time. A \`--remote eas\` run
2712
+ waits on it after its build with no overall limit, printing \`lock waiting
2713
+ for EAS remote start (pid 41233, in <workspace>, running for 1m12s) to
2714
+ release the EAS project lock\` at once and \`still waiting for ...\` every 30
2715
+ seconds. It refuses only when one holder has held the lock for longer than
2716
+ the slowest EAS session start (39 minutes), naming that pid.
2717
+ The \`worktree warm\` wait prints its
2482
2718
  elapsed waiting time and holder every 30 seconds (\`lock waiting 40s
2483
2719
  for stim worktree warm --refresh (pid 41233)\`) and the refusal names the same holder
2484
2720
  and the lock directory under ~/.stim/warm-locks.
@@ -2944,6 +3180,10 @@ ANDROID EMULATOR RESTARTS
2944
3180
  started is alive. Stim keeps waiting on the same emulator; it never
2945
3181
  launches a duplicate. See \`stim guide errors STIM_NO_DEVICE\` for the
2946
3182
  wait windows, diagnostics, and recovery steps.
3183
+ On macOS, androidEmulatorApp "stim-desktop", the default while Stim Desktop
3184
+ is installed, boots owned emulators without a window and shows them in Stim
3185
+ Desktop; see guide settings. An emulator that is already running keeps its current
3186
+ display until it next boots.
2947
3187
 
2948
3188
  DESTRUCTIVE COMMANDS -- ask the user first
2949
3189
  gc --delete deletes orphaned devices Stim created, tens of GB
@@ -2961,6 +3201,24 @@ one answers from the project. A dev server whose supervisor died is stopped
2961
3201
  only when its recorded process identity still matches. There is no
2962
3202
  \`--delete\` flag on \`stop\`.
2963
3203
 
3204
+ STOP DURING A BUILD
3205
+ \`ios\`, \`android\` and \`stop\` take turns on the workspace's
3206
+ native-run lock. A command that has to wait says so on stderr at once and
3207
+ every 30 seconds:
3208
+ lock waiting for \`stim ios\` (pid 41233, running for 12m04s) in this workspace to finish
3209
+ \`stop\` does not wait out a build it leaves with nothing to deploy to: a
3210
+ plain \`stop\`, \`stop --slot <name>\` for the slot the build targets, or
3211
+ for the workspace's only device. It sends that run SIGINT, only after
3212
+ proving the run's recorded process identity, and waits up to 60 seconds for
3213
+ it to exit. The run stops its build tool, stores nothing from the
3214
+ interrupted build, and exits 130 with STIM_CANCELLED. A run that does not
3215
+ exit in time, or whose build tool outlived it, is refused with
3216
+ STIM_STOP_BLOCKED naming its pid and claim. \`stop --slot <name>\` while the
3217
+ build targets another slot that stays leaves the build running and stops
3218
+ the slot without the lock. A plain \`stop\` ends a recorded EAS session as
3219
+ soon as it sees the lock held: ending a billable session never waits on a
3220
+ build.
3221
+
2964
3222
  CAPACITY
2965
3223
  A booted iOS sim is roughly 1-2 GB of RAM, an Android emulator 2-3 GB. On a
2966
3224
  16 GB machine plan for 2-3 live environments. Nothing enforces this;
@@ -3430,7 +3688,7 @@ result as proof instead of requiring an unrelated screenshot.`
3430
3688
  The wipe resets apps, accounts, device settings and the shared storage
3431
3689
  inside the data partition; the AVD's creation settings and any separate
3432
3690
  SD card image remain. Status lists parked Android emulators; GC
3433
- reports their system image, age and disk size.
3691
+ reports their system image, hardware profile, age and disk size.
3434
3692
  `
3435
3693
  },
3436
3694
  builds: {
@@ -3448,6 +3706,46 @@ result as proof instead of requiring an unrelated screenshot.`
3448
3706
 
3449
3707
  Follow the normal ownership and consent rules in guide agent.
3450
3708
 
3709
+ PREDICTING THE NEXT BUILD (--plan)
3710
+ \`stim ios --plan\` and \`stim android --plan\` answer "will the next run
3711
+ be a cache hit, and how long will it take?" without building, booting,
3712
+ installing, or starting Metro. They take no workspace lock and write no
3713
+ Stim state, cache entry or statistic, so they run beside a build.
3714
+
3715
+ stim ios --plan
3716
+ plan ios 1b625d.. -> local cache hit
3717
+ expect ~2.7s (median of 1 hit run)
3718
+
3719
+ A plan resolves the fingerprint and cache key the way the run would, with
3720
+ the same --slot, --scheme, --configuration, --variant, --device-type,
3721
+ --runtime, --system-image, --device-profile, --eas-profile and
3722
+ --no-build-cache, then looks
3723
+ in the build's order: the local cache, the cache.provider setting's
3724
+ provider, then the app config's build cache provider. A provider has no
3725
+ lookup that skips the download, so a remote check downloads the artifact:
3726
+ the cache.provider tier into a temporary directory the plan removes, the
3727
+ app config's provider wherever it keeps its downloads, as during a run.
3728
+ On a miss it adds the prebuild decision the run would make (generate,
3729
+ regenerate, none, or refuse with STIM_PREBUILD_FAILED) and, with cache
3730
+ reads on, the miss reason the run would print, such as "native dependency
3731
+ added: expo-clipboard". A plan never prebuilds, so when the run would and a
3732
+ baseline exists, the reason's kind is prebuild-pending and it compares the
3733
+ fingerprint before that prebuild. With --eas-profile it asks EAS for a matching
3734
+ build (config, fingerprint:generate, build:list) and downloads nothing.
3735
+ expectedMs is the median of this project's recorded runs with that outcome;
3736
+ the payload is in \`guide facts plan\`.
3737
+
3738
+ A plan is a prediction for the moment it runs. Three things can still
3739
+ change the run: another workspace can store the key first; a prebuild or
3740
+ pod install can move the fingerprint, and the run then looks up the new
3741
+ key once; and a Release hit that fails its JS swap builds fresh.
3742
+ An Android plan reads the ABI from the emulator the slot records, or from
3743
+ the system image a new one would use. A plan refuses --device, --remote,
3744
+ --wait, --no-wait, --no-metro-check and --simulator-app with STIM_BAD_ARG.
3745
+ Without --eas-profile it also refuses the android.remote setting and the
3746
+ experimental compiler CAS with STIM_BAD_ARG, and refuses with
3747
+ STIM_NO_DEVICE when no system image is installed.
3748
+
3451
3749
  IOS SCHEME SELECTION
3452
3750
  Pass \`stim ios --scheme "App Staging"\` to select an exact shared Xcode
3453
3751
  app scheme. Unknown names refuse with the available choices. This is the
@@ -3659,10 +3957,18 @@ THE BUILD CACHE HAS THREE LEVELS
3659
3957
  trims, and clears local caches only: the provider contract has no delete
3660
3958
  operation, so no local command can remove data a team or CI system shares.
3661
3959
 
3662
- A MISS explains itself when it can. When this workspace's previous build
3663
- stored its fingerprint sources beside the cache entry, the fingerprint line
3664
- gains " -- N sources changed: <up to three paths>", and the full list
3665
- (capped at 20 names) lands in the build log as a fingerprint_diff record.
3960
+ A MISS EXPLAINS ITSELF. Each local cache entry keeps the per-source hashes
3961
+ of its fingerprint (hashes only, pruned with the entry). Before compiling,
3962
+ Stim compares the sources it is about to store with a baseline: the entry
3963
+ this workspace's last build of the same platform used, else the newest one
3964
+ another worktree of the same project used. It prints one line:
3965
+
3966
+ cache miss: native dependency added: expo-clipboard (+2 more)
3967
+
3968
+ records the reason as lastBuilds.<platform>.missReason in status --json
3969
+ (see \`guide facts status\`), and writes the changed sources (capped at 20
3970
+ names) to the build log as a fingerprint_diff record. With no baseline the
3971
+ line says there was nothing to compare with.
3666
3972
 
3667
3973
  THE KEY CAN MOVE MID-RUN, and the run says so in two facts rather than two
3668
3974
  explanations. \`expo prebuild\` and \`pod install\` rewrite fingerprinted
@@ -3896,8 +4202,8 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
3896
4202
  summary: "every flag per command, Android variants and flavors, the per-run simulator model, runtime and system image",
3897
4203
  body: () => `THE OPTION SURFACE, IN FULL
3898
4204
  start --json --wait <seconds> --remote --reset-cache
3899
- 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>
3900
- android --slot <name> --json --no-metro-check --no-build-cache --variant <name> --system-image <id> --device [serial] --wait <seconds> --no-wait --remote <proxy|eas>
4205
+ 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>
4206
+ 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>
3901
4207
  reload [ios|android] --json
3902
4208
  device lock <ios|android> [id] --slot <name> --for <duration> --wait <seconds> --json;
3903
4209
  unlock [ios|android] --slot <name> --json
@@ -3927,13 +4233,20 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
3927
4233
  stim stop --slot tablet
3928
4234
 
3929
4235
  All slots share this workspace's Metro server and build cache. Native CLI
3930
- runs serialize workspace mutations; a waiting run can wait up to 30 minutes.
4236
+ runs serialize workspace mutations; a waiting run can wait up to 30 minutes
4237
+ and prints what it waits for. \`stop --slot\` interrupts a build only for
4238
+ its own slot or when it stops the workspace's only device (see STOP DURING
4239
+ A BUILD).
3931
4240
  Named slots support local devices; remote sessions use the default slot.
3932
4241
  Names use 1-64 letters, digits, underscores or hyphens, starting with a letter
3933
4242
  or digit. Reserved object-property names are refused.
3934
4243
 
3935
4244
  stop --slot shuts down that slot's owned devices and releases its leases,
3936
- retaining Metro and sibling slots. Plain stop handles the whole workspace.
4245
+ retaining Metro and sibling slots. stop --slot default targets only the
4246
+ workspace's default device, the same one ios/android address with no
4247
+ --slot and status reports with no [slot] label; it never touches a remote
4248
+ session even though remote sessions use the default slot. Plain stop
4249
+ handles the whole workspace.
3937
4250
  status reports named devices under slots and counts their memory. Device
3938
4251
  caps count every slot. Recycling uses the same model/runtime-matched pool
3939
4252
  for every slot, with one shared cap per platform and oldest-first eviction.
@@ -4094,8 +4407,11 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
4094
4407
  says "happens on iPad on iOS 26.5" gets reproduced without writing a
4095
4408
  \`.stim.json\`. \`android --system-image <id>\` is the Android half, taking
4096
4409
  the sdkmanager package id
4097
- ("system-images;android-36;google_apis;arm64-v8a"). Each overrides its
4098
- setting (ios.deviceType, ios.runtime, android.systemImage) for that one
4410
+ ("system-images;android-36;google_apis;arm64-v8a"), and
4411
+ \`android --device-profile <id>\` picks the Android hardware profile, as
4412
+ \`avdmanager list device -c\` spells it: "pixel_tablet" for a tablet,
4413
+ "pixel_fold" for a foldable. Each overrides its setting (ios.deviceType,
4414
+ ios.runtime, android.systemImage, android.deviceProfile) for that one
4099
4415
  invocation, exactly as \`--configuration\` overrides ios.configuration.
4100
4416
 
4101
4417
  A name that is not INSTALLED on this machine refuses with STIM_BAD_ARG
@@ -4117,11 +4433,22 @@ OPT-IN CONCURRENCY LIMITS (UNLIMITED BY DEFAULT)
4117
4433
  ALREADY owns a simulator and \`--device-type\` names a different model,
4118
4434
  Stim refuses rather than silently booting the wrong one: reap the current
4119
4435
  sim with \`stim worktree remove\` (or \`stim gc --delete\`), then run
4120
- \`stim ios\` again to create the requested one. \`--runtime\` and
4121
- \`--system-image\` apply at creation only, so an existing device keeps the
4122
- version it was made with. The --json payload reports what was actually
4123
- used: \`deviceType\` and \`runtime\` on iOS, \`systemImage\` on Android,
4124
- read from the device itself, so a settings-driven run reports them too.`
4436
+ \`stim ios\` again to create the requested one. \`--device-profile\` does
4437
+ the same for an AVD of another profile. To keep both devices, give the new
4438
+ one its own \`--slot\`. \`--runtime\` and the ios.runtime and
4439
+ android.systemImage settings apply at creation only, so an existing device
4440
+ keeps the version it was made with. An explicit \`--system-image\` that
4441
+ names another image than this workspace's AVD refuses the same way, unless
4442
+ that AVD never finished a boot (for example one made from an image its
4443
+ profile cannot boot): Stim then deletes it through owned-device teardown and
4444
+ creates the requested one. \`--device-profile pixel_fold\` or
4445
+ \`resizable\` on a system image without foldable support (SupportPixelFold
4446
+ in its advancedFeatures.ini) refuses with STIM_BAD_ARG before anything is
4447
+ created, since the emulator quits on boot; the remedy names an installed
4448
+ image that has it.
4449
+ The --json payload reports what was actually used: \`deviceType\` and
4450
+ \`runtime\` on iOS, \`systemImage\` and \`deviceProfile\` on Android, read
4451
+ from the device itself, so a settings-driven run reports them too.`
4125
4452
  },
4126
4453
  devices: {
4127
4454
  summary: "ios --device and android --device on a phone: what the run skips, signing, the LAN wiring, the collector",
@@ -4318,6 +4645,12 @@ HOLDING A DEVICE ACROSS RUNS
4318
4645
  With no id, \`lock\` and a \`--device\` run pick from the POOL of connected
4319
4646
  devices, so two phones on one machine no longer refuse.
4320
4647
 
4648
+ An id may also name this workspace's own Stim-owned simulator (UDID) or
4649
+ running emulator (\`emulator-NNNN\`), in any slot; \`--slot\`, if given,
4650
+ must match it. Status then reports the device \`driven by stim device
4651
+ lock\`, so other agents leave it alone. A workspace holds one lease per
4652
+ platform and slot, so this refuses while the slot leases a phone.
4653
+
4321
4654
  THE POOL: WHICH DEVICE AN ID-LESS \`--device\` PICKS
4322
4655
  Candidates are the connected devices the resolver already accepts: on iOS,
4323
4656
  paired, with Developer Mode on, over a cable or Wi-Fi; on Android, every
@@ -4472,9 +4805,10 @@ HOST MEMORY PRESSURE AND STALLED SIMULATORS
4472
4805
  boot (including the initial boot request) up to 10 minutes, and app installation
4473
4806
  up to 5 minutes. Process termination confirmation can take another 10 seconds;
4474
4807
  a final boot-state query can take 30 seconds. After boot, Stim opens the owned
4475
- simulator in the selected Xcode's Device Hub on Xcode 27, or Simulator on
4476
- older Xcode. Top-level iosSimulatorApp in the machine config can select
4477
- Siniulator or Stim Desktop instead; see guide settings. Override it for one
4808
+ simulator in Stim Desktop while it is installed, otherwise in the selected
4809
+ Xcode's Device Hub on Xcode 27, or Simulator on older Xcode. Top-level
4810
+ iosSimulatorApp in the machine config can select another viewer; see guide
4811
+ settings. Override it for one
4478
4812
  local run with \`stim ios --simulator-app siniulator\`,
4479
4813
  \`--simulator-app stim-desktop\`, or \`--simulator-app xcode\`. This also
4480
4814
  opens an already running owned simulator without rebooting it or saving the
@@ -4494,7 +4828,11 @@ HOST MEMORY PRESSURE AND STALLED SIMULATORS
4494
4828
 
4495
4829
  If pressure is elevated, free host memory before retrying. Use \`stim stop\`
4496
4830
  only in workspaces you own and have finished using; ask before closing other
4497
- agents' simulators or heavy apps. Rebooting a simulator under the same pressure
4831
+ agents' simulators or heavy apps. Never quit Device Hub or Simulator.app to
4832
+ free memory: on Xcode 27 (confirmed on 27A266a), quitting Device Hub by
4833
+ default shuts down every booted simulator on the machine, including ones it
4834
+ never opened a window for and ones other workspaces or agents are using.
4835
+ Rebooting a simulator under the same pressure
4498
4836
  can repeat the stall. Consider fewer concurrent builds/devices (guide lifecycle
4499
4837
  concurrency) and a reviewed SimSlim profile for future runs.`
4500
4838
  }
@@ -4522,6 +4860,8 @@ WHAT RECLAIMS AN OWNED DEVICE
4522
4860
  verified parked simulators and emulators, and
4523
4861
  runs \`stim worktree remove\` on every clean,
4524
4862
  Stim-managed linked worktree whose branch is merged
4863
+ and that shows no activity within
4864
+ gc.worktreeGraceMinutes
4525
4865
  stim gc --delete --older-than <days>
4526
4866
  also reaps the device of a workspace no Stim
4527
4867
  command has used in that long, even though the
@@ -4544,8 +4884,12 @@ boot rather than a create, a provision and a reinstall.
4544
4884
 
4545
4885
  Before shutting down, parking or deleting an owned device, Stim best-effort
4546
4886
  closes local agent-device sessions bound to its exact iOS UDID or live Android
4547
- serial. It rechecks device ownership and uses agent-device's rejecting session
4548
- target guard; sessions on other devices stay open. Physical devices are outside
4887
+ serial. An Android session must also name the owned AVD, because the next
4888
+ emulator on a console port reuses its serial. \`stop\` closes a session only
4889
+ when agent-device's claim on the device names it and was taken inside this
4890
+ workspace; sessions from another workspace or claim stay open. Stim rechecks
4891
+ device ownership and uses agent-device's rejecting session target guard;
4892
+ sessions on other devices stay open. Physical devices are outside
4549
4893
  this cleanup. agent-device is optional: a missing binary skips this step, and a
4550
4894
  failed or timed-out list/close prints a device line on stderr while teardown
4551
4895
  continues. Cleanup allows at most 15 seconds of agent-device calls per device.
@@ -4601,6 +4945,26 @@ SWEEPING FINISHED WORKTREES
4601
4945
  initialized submodules. Without --worktrees, the report leaves out the
4602
4946
  source checkout and roots outside git.
4603
4947
 
4948
+ IN USE means its dev server supervisor runs, a stim ios, android or stop
4949
+ run holds its native-run lock, a live build lock or slot names it, a
4950
+ managed tunnel or remote lock is held, an owned simulator or emulator of
4951
+ the workspace is booted (an agent-device session needs one), or it holds
4952
+ an unexpired device lease. When the simulator or emulator list cannot be
4953
+ read, the worktree counts as in use. A device left booted keeps the
4954
+ worktree until \`stim stop\` in it, or \`gc --idle <duration>\`, shuts
4955
+ the device down.
4956
+
4957
+ RECENT ACTIVITY keeps a worktree gc would otherwise remove until
4958
+ gc.worktreeGraceMinutes (120 by default, \`guide settings\`) have passed
4959
+ since the latest of: a write to its git index, HEAD or HEAD reflog, a write
4960
+ to its Stim workspace state or log files, and, for a merged branch, the
4961
+ committer date of the commit that brought it into the default branch. That
4962
+ window is when an agent that just merged runs \`stim stop\` and \`stim
4963
+ worktree remove\` itself. The reason is recent-activity, and the report
4964
+ and the JSON eligibleAt field say when it becomes removable. When that
4965
+ activity cannot be read, the worktree is kept (reason activity-unknown).
4966
+ 0 turns the grace period off.
4967
+
4604
4968
  MERGED means, with the default branch taken from origin/HEAD, after a
4605
4969
  \`git fetch origin <default>\` per repository (30s timeout, no credential
4606
4970
  prompt; skipped when that checkout fetched in the last 10 minutes):
@@ -4629,8 +4993,9 @@ SWEEPING FINISHED WORKTREES
4629
4993
  --cache with --worktrees is refused with STIM_BAD_ARG; run them separately.
4630
4994
  With --delete it runs the \`stim worktree remove\` pipeline, never --force,
4631
4995
  on each removable worktree. That pipeline re-inspects the worktree and
4632
- re-checks use under the removal locks, and idleness for an idle worktree
4633
- or an unchanged HEAD for a merged one, then parks devices and handles the
4996
+ re-checks use and recent activity under the removal locks, and idleness
4997
+ for an idle worktree or an unchanged HEAD for a merged one, then parks
4998
+ devices through the same teardown and handles the
4634
4999
  branch exactly as a manual \`stim worktree remove\`, which keeps the
4635
5000
  checkout when its HEAD moves while devices are reclaimed. A worktree that
4636
5001
  changed since the report is kept with the reason. A worktree that fails is
@@ -4968,7 +5333,8 @@ Resolution order, first match wins:
4968
5333
  1. workspace ~/.stim/config.json, under this project's entry
4969
5334
  2. repo ~/.stim/config.json, under this repo's git common dir
4970
5335
  3. committed .stim.json beside the app's package.json
4971
- 4. machine ~/.stim/config.json, top-level optimizations only
5336
+ 4. machine ~/.stim/config.json, top-level optimizations and
5337
+ android.deviceProfile only
4972
5338
  5. Stim default
4973
5339
  An environment override, where a setting has one, wins over every layer.
4974
5340
 
@@ -5061,9 +5427,33 @@ KEYS STIM READS
5061
5427
  from. The \`--system-image\` flag overrides this per
5062
5428
  invocation, and an id this SDK has not installed is
5063
5429
  STIM_BAD_ARG with the installed ids printed.
5064
- New AVDs use the Pixel 6 hardware profile (1080x2400,
5065
- 420 dpi). Existing AVDs keep their display settings;
5066
- parked AVDs from the old generic profile are not adopted.
5430
+ android.deviceProfile e.g. "pixel_fold" -- the avdmanager hardware profile a
5431
+ new owned AVD is created with, spelled exactly as
5432
+ \`avdmanager list device -c\` prints it. Defaults to
5433
+ pixel_6 (1080x2400, 420 dpi); "pixel_tablet" and
5434
+ "pixel_fold" give a tablet and a foldable, and
5435
+ avdmanager writes the foldable's hinge and posture
5436
+ keys from its profile. Readable from the machine
5437
+ layer too, so one machine can default every workspace
5438
+ to a tablet. A set profile counts as a request: each
5439
+ run then checks it with avdmanager (about 2s), and a
5440
+ workspace that already owns an AVD of another profile
5441
+ refuses until that AVD is reaped. The \`--device-profile\` flag overrides it
5442
+ per invocation, and an id avdmanager does not offer is
5443
+ STIM_BAD_ARG with the offered ids printed; that check
5444
+ runs avdmanager only when a profile is given. A
5445
+ parked AVD is adopted only by a request for its own
5446
+ profile. When this workspace already owns an AVD of
5447
+ another profile, a requested profile refuses rather
5448
+ than booting it; reap the AVD to create the new one.
5449
+ "pixel_fold" and "resizable" need a system image
5450
+ whose advancedFeatures.ini turns on SupportPixelFold
5451
+ (recent images such as API 34 google_apis do); the
5452
+ emulator quits on boot without it, so Stim refuses
5453
+ the pair with
5454
+ STIM_BAD_ARG and names an installed image that has it.
5455
+ Existing AVDs keep their display settings; parked AVDs
5456
+ from the old generic profile are not adopted.
5067
5457
  android.dataPartitionSizeGb
5068
5458
  whole GiB for a newly created owned AVD's data
5069
5459
  partition. Defaults to 8; accepts 6 through 16384.
@@ -5090,10 +5480,16 @@ ${ANDROID_AVD_CONFIG_HELP.map((line) => ` ${line}`).joi
5090
5480
  keys are protected. The emulator may normalize a valid
5091
5481
  value. These overrides apply only to a newly created
5092
5482
  AVD; existing and recovered AVDs are never rewritten.
5483
+ Unless these settings set hw.keyboard, every AVD Stim
5484
+ creates gets hw.keyboard=yes, so the emulator takes
5485
+ gRPC key events. The one rewrite: a parked AVD created
5486
+ before that default gets it when a workspace adopts it.
5093
5487
  On displayless Linux, Stim launches with
5094
5488
  -gpu swiftshader_indirect -noaudio; those arguments
5095
5489
  override hw.gpu.enabled, hw.gpu.mode, hw.audioInput,
5096
- and hw.audioOutput for that headless launch.
5490
+ and hw.audioOutput for that headless launch. With
5491
+ androidEmulatorApp "stim-desktop" on macOS, -gpu host
5492
+ overrides hw.gpu.mode the same way.
5097
5493
  android.variant e.g. "productionDebug" -- the gradle variant to
5098
5494
  assemble and install on a project with product
5099
5495
  flavors. A repo like tlon-mobile with
@@ -5271,8 +5667,13 @@ STIM_BAD_ARG. See \`guide lifecycle budget\` for what each limit reclaims.
5271
5667
  THE IOS SIMULATOR APP IS MACHINE-LEVEL
5272
5668
  Top-level \`iosSimulatorApp\` in ~/.stim/config.json selects the macOS app that
5273
5669
  displays Stim's owned local iOS simulator after boot. It is not a project
5274
- setting. Unset or \`"xcode"\` opens the selected Xcode's Device Hub on Xcode 27,
5275
- or Simulator on older Xcode. To use an installed Siniulator instead:
5670
+ setting. Unset, it is \`"stim-desktop"\` while Stim Desktop is installed and
5671
+ \`"xcode"\` otherwise. \`"xcode"\` opens the selected Xcode's Device Hub on Xcode 27,
5672
+ or Simulator on older Xcode. On Xcode 27 (confirmed on 27A266a), quitting
5673
+ Device Hub by default shuts down every booted simulator on the machine,
5674
+ including ones it never opened a window for and ones other workspaces or
5675
+ agents are using; never quit it to free memory or clean up. To use an
5676
+ installed Siniulator instead:
5276
5677
 
5277
5678
  { "iosSimulatorApp": "siniulator" }
5278
5679
 
@@ -5296,6 +5697,29 @@ window shuts down that simulator. Enable "Leave simulator running after window
5296
5697
  is closed" in Siniulator Settings if Stim should keep it running. See \`guide lifecycle simslim\` for
5297
5698
  window behavior.
5298
5699
 
5700
+ THE ANDROID EMULATOR APP IS MACHINE-LEVEL
5701
+ Top-level \`androidEmulatorApp\` in ~/.stim/config.json selects how an owned
5702
+ Android emulator that Stim boots on macOS is displayed. Unset, it is
5703
+ \`"stim-desktop"\` while Stim Desktop is installed and \`"emulator"\`
5704
+ otherwise. \`"emulator"\` opens the emulator's own window. To boot it
5705
+ headlessly and show it in Stim Desktop:
5706
+
5707
+ { "androidEmulatorApp": "stim-desktop" }
5708
+
5709
+ Stim then starts the emulator with \`-no-window -gpu host\` and opens
5710
+ \`stim-desktop://open?serial=<serial>\` in the background. Stim Desktop reads
5711
+ frames and sends input over the emulator's gRPC endpoint. The setting applies
5712
+ only when Stim boots the emulator: one that is already running keeps its
5713
+ current display until it next boots, and physical devices are unaffected.
5714
+ An invalid value refuses before boot. On Linux and Windows the setting has
5715
+ no effect.
5716
+
5717
+ Stim finds Stim Desktop by its bundle id, dev.stim.desktop, in Launch Services.
5718
+ \`stim settings\` shows that default as \`(default: Stim Desktop installed)\`,
5719
+ \`settings get\` prints it on stderr, and \`--json\` adds
5720
+ \`"defaultReason": "Stim Desktop installed"\`. A set value always wins; set
5721
+ \`"xcode"\` or \`"emulator"\` to keep the device windows.
5722
+
5299
5723
  THE DEVICE POOL BOUNDS ARE MACHINE-LEVEL TOO
5300
5724
  \`pool.iosParkedMax\` caps how many parked simulators \`worktree remove\` may
5301
5725
  leave behind for a later workspace to adopt. It is machine-level for the same
@@ -5326,6 +5750,21 @@ test suites and the end-to-end harness use one -- and a scoped config must not
5326
5750
  leave simulators on the machine it cannot account for. A redirected home that
5327
5751
  wants a pool says so with the variable.
5328
5752
 
5753
+ THE GC WORKTREE GRACE PERIOD IS MACHINE-LEVEL
5754
+ \`gc.worktreeGraceMinutes\` is how long \`gc --delete\` waits before it removes
5755
+ a merged or idle linked worktree. The clock starts at the worktree's latest
5756
+ activity: a write to its git index, HEAD or HEAD reflog, its Stim workspace
5757
+ state or logs, or the merge of its branch into the default branch.
5758
+
5759
+ {
5760
+ "gc": { "worktreeGraceMinutes": 120 }
5761
+ }
5762
+
5763
+ in ~/.stim/config.json, or STIM_GC_WORKTREE_GRACE_MINUTES in the environment,
5764
+ which overrides the file. Absent means 120. \`0\` removes a finished worktree at
5765
+ once. A value that is not a whole number 0 or more is warned about by \`gc\`,
5766
+ which then uses 120. See \`guide cleanup\` for what else keeps a worktree.
5767
+
5329
5768
  STIM NEEDS NO PROJECT CHANGES TO RUN
5330
5769
  Nothing above is required to use Stim. The performance caches that used to
5331
5770
  be setup steps are supplied by Stim on the command lines it composes itself: