@awebai/oats 0.51.0 → 0.53.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 (166) hide show
  1. package/README.md +3 -1
  2. package/bin/oats.mjs +407 -123
  3. package/docs/capabilities.md +75 -6
  4. package/docs/configuration.md +200 -91
  5. package/docs/desktop-cli-api.md +1563 -113
  6. package/docs/desktop-instance-start.md +69 -0
  7. package/docs/desktop.md +10 -7
  8. package/docs/execution-targets.md +145 -58
  9. package/docs/first-team.md +3 -1
  10. package/docs/harness-trust.md +50 -2
  11. package/docs/implementation.md +238 -17
  12. package/docs/integrations.md +13 -9
  13. package/docs/knowledge-reference/acceptance.md +1 -0
  14. package/docs/knowledge-reference/harvester.md +5 -3
  15. package/docs/knowledge-reference/model.md +5 -3
  16. package/docs/knowledge-theory.md +1 -1
  17. package/docs/knowledge.md +25 -2
  18. package/docs/launch-prompt-completion.md +50 -48
  19. package/docs/macos-test-runs.md +246 -0
  20. package/docs/oats-local.schema.json +4 -3
  21. package/docs/official-catalog.md +5 -5
  22. package/docs/packages.md +14 -14
  23. package/docs/release-lane.md +225 -11
  24. package/docs/release-notes/v0.44.0.md +1 -1
  25. package/docs/release-notes/v0.52.0.md +933 -0
  26. package/docs/release-notes/v0.53.0.md +1274 -0
  27. package/docs/schedules.md +97 -4
  28. package/docs/souls-and-instances.md +332 -40
  29. package/docs/tui.md +584 -0
  30. package/docs/upgrading.md +298 -0
  31. package/docs/workspaces.md +3 -3
  32. package/lib/automations.mjs +22 -22
  33. package/lib/claim.mjs +278 -49
  34. package/lib/config-data.mjs +4 -1
  35. package/lib/core.mjs +1282 -289
  36. package/lib/errors.mjs +170 -0
  37. package/lib/harness-trust-write.mjs +68 -27
  38. package/lib/harness-trust.mjs +34 -16
  39. package/lib/instance-events.mjs +19 -1
  40. package/lib/instance-git.mjs +39 -3
  41. package/lib/instance-inspect.mjs +45 -17
  42. package/lib/instance-lifecycle.mjs +306 -57
  43. package/lib/instance-resolution.mjs +59 -6
  44. package/lib/launch-preference.mjs +236 -9
  45. package/lib/launch-prompt-completion.mjs +7 -43
  46. package/lib/launch-prompt-evidence.mjs +14 -7
  47. package/lib/launch-prompt-fixtures/README.md +86 -152
  48. package/lib/launch-prompt-fixtures/dev-channel-confirmation.json +50 -0
  49. package/lib/launch-prompt-fixtures.mjs +122 -109
  50. package/lib/launch-prompt-transport.mjs +2 -56
  51. package/lib/launch-prompts.mjs +102 -100
  52. package/lib/local-edit.mjs +118 -0
  53. package/lib/packages.mjs +13 -4
  54. package/lib/pi-bridge.mjs +308 -0
  55. package/lib/refused-text.mjs +11 -0
  56. package/lib/remote.mjs +190 -25
  57. package/lib/resolve.mjs +2 -1
  58. package/lib/retained-after-retire.mjs +2 -2
  59. package/lib/retire-output.mjs +12 -1
  60. package/lib/schedule-host.mjs +125 -22
  61. package/lib/schedule.mjs +73 -24
  62. package/lib/shell-word.mjs +13 -0
  63. package/lib/soul-launch-verbs.mjs +153 -0
  64. package/lib/stable-node.mjs +62 -0
  65. package/lib/system-tools.mjs +39 -0
  66. package/lib/teams-verbs.mjs +18 -46
  67. package/lib/tmux-server-scope.mjs +62 -0
  68. package/lib/triggers.mjs +4 -4
  69. package/lib/workspace.mjs +54 -30
  70. package/lib/worktree-hooks.mjs +98 -20
  71. package/lib/worktree.mjs +83 -24
  72. package/package-catalog.json +4 -4
  73. package/package.json +8 -2
  74. package/packages/client/attach-exit.mjs +25 -0
  75. package/packages/client/capability-show-contract.mjs +230 -0
  76. package/packages/client/capability-warnings-contract.mjs +57 -0
  77. package/packages/client/cli-adapter.mjs +561 -0
  78. package/packages/client/cli-environment.mjs +53 -0
  79. package/packages/client/cli-locator.mjs +253 -0
  80. package/packages/client/cli-probe-contract.mjs +47 -0
  81. package/packages/client/client-terms.mjs +60 -0
  82. package/packages/client/deployment-contract.mjs +72 -0
  83. package/packages/client/deployment-data.mjs +483 -0
  84. package/packages/client/deployment-facts.mjs +95 -0
  85. package/packages/client/deployment-label.mjs +76 -0
  86. package/packages/client/deployment-observer.mjs +89 -0
  87. package/packages/client/deployment-panel.mjs +180 -0
  88. package/packages/client/deployment-read-cli.mjs +57 -0
  89. package/packages/client/display-text.mjs +50 -0
  90. package/packages/client/harness-names.mjs +30 -0
  91. package/packages/client/inspect-contract.mjs +62 -0
  92. package/packages/client/instance-acts.mjs +90 -0
  93. package/packages/client/instance-admission.mjs +45 -0
  94. package/packages/client/instance-events-contract.mjs +76 -0
  95. package/packages/client/instance-git-contract.mjs +80 -0
  96. package/packages/client/instance-presentation.mjs +86 -0
  97. package/packages/client/instance-tree.mjs +462 -0
  98. package/packages/client/kernel-environment.mjs +11 -0
  99. package/packages/client/kernel-lines.mjs +31 -0
  100. package/packages/client/kernel-made.mjs +23 -0
  101. package/packages/client/launch-contract.mjs +51 -0
  102. package/packages/client/launch-prompt-outcome.mjs +200 -0
  103. package/packages/client/lifecycle-cli.mjs +61 -0
  104. package/packages/client/lifecycle-contract.mjs +413 -0
  105. package/packages/client/liveness-main.mjs +10 -0
  106. package/packages/client/liveness.mjs +48 -0
  107. package/packages/client/machine-contract.mjs +123 -0
  108. package/packages/client/own-codes.mjs +31 -0
  109. package/packages/client/own-environment.mjs +22 -0
  110. package/packages/client/panel-views.mjs +293 -0
  111. package/packages/client/readiness-contract.mjs +174 -0
  112. package/packages/client/refresh-loop.mjs +52 -0
  113. package/packages/client/remote-address.mjs +151 -0
  114. package/packages/client/remote-identity-memory.mjs +94 -0
  115. package/packages/client/remote-roster.mjs +153 -0
  116. package/packages/client/roster-sections.mjs +80 -0
  117. package/packages/client/session-attach.mjs +175 -0
  118. package/packages/client/spawn-apply-cli.mjs +104 -0
  119. package/packages/client/spawn-apply-contract.mjs +195 -0
  120. package/packages/client/spawn-decision.mjs +46 -0
  121. package/packages/client/spawn-messages.mjs +142 -0
  122. package/packages/client/spawn-preview-cli.mjs +38 -0
  123. package/packages/client/spawn-preview-contract.mjs +318 -0
  124. package/packages/client/team-members.mjs +41 -0
  125. package/packages/client/team-rows.mjs +45 -0
  126. package/packages/client/terminal-contract.mjs +57 -0
  127. package/packages/client/terminal-exec.mjs +21 -0
  128. package/packages/client/tmux-status.mjs +66 -0
  129. package/packages/client/waiting-on-you.mjs +88 -0
  130. package/packages/client/workspace-admission.mjs +45 -0
  131. package/packages/client/workspace-choices.mjs +95 -0
  132. package/packages/client/workspace-cli.mjs +142 -0
  133. package/packages/client/workspace-views.mjs +183 -0
  134. package/packages/record/README.md +21 -0
  135. package/packages/record/bin/setup.mjs +108 -15
  136. package/packages/tui/README.md +64 -0
  137. package/packages/tui/bin/tui.mjs +7 -0
  138. package/packages/tui/lib/actions.mjs +44 -0
  139. package/packages/tui/lib/client.mjs +35 -0
  140. package/packages/tui/lib/config.mjs +151 -0
  141. package/packages/tui/lib/main.mjs +176 -0
  142. package/packages/tui/lib/model.mjs +392 -0
  143. package/packages/tui/lib/read.mjs +473 -0
  144. package/packages/tui/lib/store.mjs +364 -0
  145. package/packages/tui/lib/term/keys.mjs +367 -0
  146. package/packages/tui/lib/term/screen.mjs +134 -0
  147. package/packages/tui/lib/term/style.mjs +43 -0
  148. package/packages/tui/lib/term/text.mjs +109 -0
  149. package/packages/tui/lib/term/tty.mjs +178 -0
  150. package/packages/tui/lib/term/width.mjs +124 -0
  151. package/packages/tui/lib/views/detail.mjs +46 -0
  152. package/packages/tui/lib/views/frame.mjs +256 -0
  153. package/packages/tui/lib/views/help.mjs +140 -0
  154. package/packages/tui/lib/views/instances.mjs +137 -0
  155. package/packages/tui/lib/views/scroll.mjs +19 -0
  156. package/packages/tui/lib/views/switcher.mjs +97 -0
  157. package/packages/tui/package.json +8 -0
  158. package/skills/oats-getting-started/SKILL.md +30 -23
  159. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +0 -35
  160. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +0 -35
  161. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +0 -35
  162. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +0 -35
  163. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +0 -77
  164. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/max-bypass-source.json +0 -88
  165. package/lib/launch-prompt-fixtures/structural-completion.json +0 -205
  166. package/lib/launch-prompt-policy.mjs +0 -87
@@ -207,7 +207,10 @@ A self-contained package has an `oats.json`:
207
207
  every host. Only then is its start time read: from `/proc`, or with `ps`
208
208
  where there is no `/proc`, as on macOS: the system `ps`, from
209
209
  `/usr/bin:/bin` whatever the caller's `PATH` holds, in a fixed `LC_ALL=C`,
210
- `TZ=UTC` environment. A start that cannot be read is never taken to mean the process is
210
+ `TZ=UTC` environment. A spawning process that has exited or was killed and
211
+ that its parent has not reaped (a zombie) is gone, although it still has
212
+ its pid and its start: the row shows the quarantine and `oats retire`
213
+ completes it. A start that cannot be read is never taken to mean the process is
211
214
  gone, nor shown as alive: `oats status` shows the quarantine
212
215
  (`rollbackIncomplete`, whose `inProgress` names the pid), and `oats retire`
213
216
  refuses with `E_LIFECYCLE_BUSY`, naming the recorded pid and start for a
@@ -244,7 +247,11 @@ A self-contained package has an `oats.json`:
244
247
  and nothing is silently dropped. Without `--force` that state fails closed with
245
248
  `E_UNIDENTIFIED_INSTANCE_HOME` rather than deleting whatever credentials the
246
249
  directory still holds; `--force` removes it and leaves any external state for
247
- the operator to clean up by hand. Home entries declared in
250
+ the operator to clean up by hand. One home is the exception for now: a home
251
+ whose `instance.json` is there and cannot be read is refused by every
252
+ retire, `--force` included, until the file is restored from a copy
253
+ ([souls-and-instances.md](souls-and-instances.md#retire); awebai/oats#896).
254
+ Home entries declared in
248
255
  `retirement.disposable.home` (below) go with the home: recovery holds no
249
256
  copy of them.
250
257
  - `retirement.disposable` declares what retirement treats as the provider's
@@ -541,6 +548,9 @@ Hooks receive:
541
548
  compatibility alias), `OATS_AGENT`, `OATS_SOUL`, `OATS_SOUL_ID`,
542
549
  `OATS_CONTEXT`, `OATS_WORKSPACE`, `OATS_ROOT`;
543
550
  - `OATS_CLI_BIN` (the running kernel's `bin/oats.mjs`);
551
+ - `OATS_NODE_BIN` (the node to write into anything that outlives the hook:
552
+ the node running the kernel, by a path that survives a Node upgrade,
553
+ [below](#the-node-a-hook-writes-down));
544
554
  - `OATS_SETTINGS`, `OATS_SETTINGS_ORIGINS`, `OATS_META`;
545
555
  - the team and workspace variables of
546
556
  [Teams in the provider environment](#teams-in-the-provider-environment),
@@ -560,6 +570,8 @@ from the deployment directory) receives:
560
570
 
561
571
  - `OATS_CAPABILITY`;
562
572
  - `OATS_CLI_BIN`;
573
+ - `OATS_NODE_BIN`: the node to write into anything that outlives the command,
574
+ as hooks get it;
563
575
  - `OATS_SETTINGS`, `OATS_SETTINGS_ORIGINS`: the home's recorded payload, or
564
576
  the soul's merged payload from the deployment;
565
577
  - the team and workspace variables, as hooks get them;
@@ -728,6 +740,47 @@ Spawn order is by capability name; retirement reverses successful
728
740
  spawn order. Hooks run from the instance's own copy
729
741
  (`<home>/.oats/modules/<cap>/`).
730
742
 
743
+ ### The node a hook writes down
744
+
745
+ A hook or a command that writes a `node` path into something that outlives it
746
+ (a harness's settings file, a unit, a script) writes `OATS_NODE_BIN`, never
747
+ its own `process.execPath`: on Homebrew that is the versioned keg
748
+ (`…/Cellar/node/<version>/bin/node`), which the next `brew upgrade node`
749
+ removes, and what was written then fails where nobody sees it. To run
750
+ something at once, `process.execPath` is still right.
751
+
752
+ `OATS_NODE_BIN` is the node running the kernel, the one that runs
753
+ `OATS_CLI_BIN`. A hook is itself run as the `node` first on its `PATH`, which
754
+ can be another one. The kernel computes the path once per process, by the one
755
+ rule it also uses for [the host timer's unit](schedules.md#the-host-timers-unit):
756
+
757
+ 1. the keg's `<prefix>/opt/<formula>/bin/node`, when that is the node running
758
+ the kernel;
759
+ 2. else the first `node` on the kernel's own `PATH` that is that same file.
760
+ Entries inside an instance home and inside a versioned keg are not looked
761
+ at;
762
+ 3. else the node's own path, as it is.
763
+
764
+ The second case answers only a `node` that is the same file as the one
765
+ running the kernel. A version manager's shim is another program, so it is
766
+ never the answer: which node a shim runs depends on the directory it is run
767
+ from. With mise the answer is the version's own install, which lasts until
768
+ that version is removed (measured: mise's shim puts that directory on the
769
+ `PATH` of what it starts). Other version managers were not measured.
770
+
771
+ In the third case a spawn and a start each carry one warning, for every
772
+ harness, that the node path is not stable; a preview carries none. The hook
773
+ itself cannot report it.
774
+
775
+ A package that also runs under a kernel older than the variable falls back to
776
+ `process.execPath` when `OATS_NODE_BIN` is absent or not an absolute path.
777
+
778
+ `oats setup` is given the same answer: the kernel sets `OATS_NODE_BIN` in its
779
+ own process, over any value the caller's environment held, before it runs the
780
+ turn record's setup script (`packages/record/bin/setup.mjs`), which writes it
781
+ into the capture hooks and the capture watcher's unit. In the third case
782
+ `oats setup` carries the warning, a dry run included.
783
+
731
784
  ### The worktree event
732
785
 
733
786
  `OATS_EVENT=worktree` (OATS 0.49.0) lets a capability set up a Git tree the
@@ -965,8 +1018,20 @@ clears it.
965
1018
  symlink or not a directory.
966
1019
  - **When it writes.** It writes at spawn, because `oats spawn` runs no
967
1020
  launch hook, and at every `oats session start|restart`, so the node and
968
- CLI paths it bakes in follow the current kernel. A launch preview writes
969
- nothing. Every pass answers `{}`: no launch arguments and no env. Codex
1021
+ CLI paths it bakes in follow the current kernel. The node is
1022
+ `OATS_NODE_BIN` ([the node a hook writes down](#the-node-a-hook-writes-down)):
1023
+ the kernel's own node, by a path that survives a Node upgrade. Under a
1024
+ kernel that does not set the variable it is the hook's own
1025
+ `process.execPath`, which on Homebrew is the versioned keg, gone at the
1026
+ next `brew upgrade node`. With mise the variable is the version's own
1027
+ path, as the hook's own node was (other version managers were not
1028
+ measured), and a start rewrites the hooks after the version changes. The
1029
+ hook a start runs is the copy of oats.core
1030
+ in the home (`.oats/modules/oats.core`), which a start does not refresh. A
1031
+ home spawned with an oats.core that does not read the variable therefore
1032
+ writes its hook's own node path at every start: a restart repairs its
1033
+ hooks after each Node upgrade, and a respawn gives it the lasting path. A
1034
+ launch preview writes nothing. Every pass answers `{}`: no launch arguments and no env. Codex
970
1035
  and pi homes get nothing.
971
1036
  - **It never hurts the session.** Claude Code reads a hook's stdout and exit
972
1037
  code as decisions. So every command runs the script through `/bin/sh`
@@ -1207,6 +1272,8 @@ passed as arguments; no shell is involved.
1207
1272
  - `OATS_CAPABILITY`, `OATS_SETTINGS` (the payload as JSON) and
1208
1273
  `OATS_SETTINGS_ORIGINS` (where each leaf came from, as hooks get it);
1209
1274
  - `OATS_CLI_BIN`;
1275
+ - `OATS_NODE_BIN` (the node to write into anything that outlives the check,
1276
+ as hooks get it);
1210
1277
  - `OATS_WORKSPACE` (the deployment);
1211
1278
  - the team variables `OATS_DEFAULT_TEAM`, `OATS_DEFAULT_TEAM_ID`,
1212
1279
  `OATS_DEFAULT_TEAM_FROM`, `OATS_TEAMS`, `OATS_TEAMS_SOURCE` (see
@@ -1381,8 +1448,10 @@ its own; the tick records what it folds.
1381
1448
  **Environment:** the one a `--soul` [readiness check](#readiness-check-bindingcheck)
1382
1449
  gets, for the trigger's soul: every ambient `OATS_*`, `OAS_*` and `PI_*`
1383
1450
  variable removed, the rest inherited, and the kernel's `OATS_CAPABILITY`,
1384
- `OATS_SETTINGS`, `OATS_SETTINGS_ORIGINS`, `OATS_CLI_BIN`, `OATS_WORKSPACE`,
1385
- the team variables, `OATS_AGENT`, `OATS_SOUL_ID` and `OATS_SOUL`. There is no
1451
+ `OATS_SETTINGS`, `OATS_SETTINGS_ORIGINS`, `OATS_CLI_BIN`, `OATS_NODE_BIN`
1452
+ (the node to write into anything that outlives the run, as hooks get it),
1453
+ `OATS_WORKSPACE`, the team variables, `OATS_AGENT`, `OATS_SOUL_ID` and
1454
+ `OATS_SOUL`. There is no
1386
1455
  `OATS_INSTANCE` or `OATS_INSTANCE_HOME`, and the kernel passes no credential.
1387
1456
  Under the host timer, the inherited environment is the timer's (only `PATH`
1388
1457
  and `OATS_HOME_DIR`): keep the source's login in its own store under `HOME`,
@@ -60,17 +60,17 @@ refused (`E_WORKSPACE_SCHEMA`).
60
60
  | `workspace` | Repo ref of the workspace host (`git:host/org/repo`, `https://…`, `git@host:…`, `file:///…`, `/abs/bare.git`). Read with your own Git credentials; it need not be cloned. |
61
61
  | `standalone` | A repo ref to realize on its own: its souls and `from: here` capabilities plus `oats.core`, with no workspace lookup. For a repository whose workspace this machine cannot read ([workspaces.md](workspaces.md#the-standalone-case)). |
62
62
  | `clones` | `<repo key>: <absolute path>` for a member clone that is not at `<deployment>/<member name>/`. Only a soul whose work target needs a clone (`work: worktree \| checkout`) uses it. Lookup order: `spawn --repo`, then this map, then `<deployment>/<member name>` (a member named `agents` → `<deployment>/agents-repo`). None → `E_CLONE_MISSING`; a directory whose `origin` is another repository → `E_CLONE_MISMATCH`. |
63
- | `launchPromptAnswers.homes.<absolute-home>` | Explicit per-home `awebDevelopmentChannel` boolean consent; defaults false. See [launch prompt consent](#exact-home-launch-prompt-consent). |
63
+ | `launchPromptAnswers` | Ignored, with a warning to remove it; a home entry `awebDevelopmentChannel: false` is refused. See [the development-channel confirmation](#the-development-channel-confirmation). |
64
64
  | `settings.<cap>.<key>` | Host-owned values a capability's manifest asks for: absolute paths, state roots, delivery modes. The workspace file refuses absolute paths; they go here. Merged into the capability's provider payload after the soul's own and before any `--provider` flag ([three homes](workspaces.md#provider-payloads-have-three-homes)). |
65
65
  | `teams.<label>` | A **local** team: `{ team: <provider team id>, description? }`, a team only this deployment uses; every soul may join it. Allowed only where `oats-workspace.yaml` says `localTeams: true` (or in the standalone view); otherwise refused (`E_WORKSPACE_SCHEMA`, reason `local-teams-closed`). Shared teams are committed in `oats-workspace.yaml`; a label in both is `team-label-collision` (the shared one wins). Written by `oats teams add <label> --team <id>` and `oats teams remove <label>`. |
66
66
  | `defaultTeam` | This deployment's default team: a label of a local or shared team, under the same condition as `teams`. A soul's own default in the workspace's `souls:` wins over it; it wins over the workspace's `defaultTeam`. The first `oats teams add` sets it (unless `--no-default`); `oats teams default <label>` changes it, and `--if-absent` / `--expect <label>` change it only where there is no effective default / it is that label. |
67
- | `souls.disabled` | Souls not run on this machine; a spawn is refused with `E_SOUL_DISABLED`. A bare name disables every soul of that name; `<package>/<soul>` or `<member>/<soul>` disables one. |
67
+ | `souls.disabled` | Souls not run on this machine; a spawn is refused with `E_SOUL_DISABLED`. A bare name disables every soul of that name; `<package>/<soul>` or `<member>/<soul>` disables one. It is for a soul that must not run here (broken, or not for this machine), with the reason in a comment; it is not a gate for souls without a `launch:`, which take the host default like any launch nobody named (see [Launch preferences](#launch-preferences)). |
68
68
  | `session.tmuxSession` | The tmux session new tmux instances open their windows in (0.31). Absent: `OATS_TMUX_SESSION`, else `PI_AGENTS_TMUX_SESSION` (the pre-0.31 variable), else `oats-agents`. `session: { tmuxSession: pi-agents }` keeps the pre-0.31 layout. `oats inspect --json` reports it as `session`. |
69
69
  | `host.name` | This machine's name. A workspace trigger or schedule runs only on the host named by its `runsOn` ([schedules.md](schedules.md)). |
70
70
  | `automations.trust` | The workspace triggers and schedules (`<member>/<id>`) this host agrees to run, or `"*"` for every one the workspace places here (0.30). Absent or empty: none runs. See [Who runs workspace automations](#who-runs-workspace-automations). |
71
71
  | `triggers.disabled`, `schedules.disabled` | Workspace triggers and schedules (`<member>/<id>`) this host does not run, without a commit. Written by `oats trigger disable` / `oats schedule disable`. |
72
72
  | `launch-configs.<name>` | A named way to start a harness on this host, chosen at spawn or session start, never by the soul. `default: true` makes it this host's baseline for its harness (0.32). See [Launch configurations](#launch-configurations). |
73
- | `souls.launch` | This machine's launch preference per soul (0.30): `"*"` for every soul, a soul's own entry (its name, or `<package>/<soul>`) over it. A value is a `launch-configs` name or an inline `{ harness, model? }`. It overrides the soul's own `launch:`; explicit spawn flags win over both. See [Launch preferences](#launch-preferences). |
73
+ | `souls.launch` | This machine's launch preference per soul (0.30): `"*"` for every soul, a soul's own entry (its name, or `<package>/<soul>`) over it. A value is a `launch-configs` name or an inline `{ harness, model? }`. It overrides the soul's own `launch:`; explicit spawn flags win over both. Written by `oats soul launch set\|remove` (0.53). See [Launch preferences](#launch-preferences). |
74
74
 
75
75
  Which teams a soul may join, and its default, are committed in the workspace's
76
76
  `souls:`, never here: `souls.teams` and `souls.default` were removed in 0.38.0
@@ -138,9 +138,9 @@ Claude config directory the host's Claude launch configuration uses (its
138
138
  Respawn a home to adopt the route. Setup never restarts running agents
139
139
  without the operator's word.
140
140
 
141
- **No launch-prompt opt-in** is needed in approved mode: the
142
- [exact-home consent](#exact-home-launch-prompt-consent) applies only to
143
- development mode, and qualifies only Claude 2.1.289 on `darwin-arm64`.
141
+ **No prompt** appears in approved mode, so there is nothing for OATS to
142
+ confirm: [the development-channel confirmation](#the-development-channel-confirmation)
143
+ applies only to a launch with the development-channel flag.
144
144
 
145
145
  **Verify:**
146
146
 
@@ -170,89 +170,121 @@ development mode, and qualifies only Claude 2.1.289 on `darwin-arm64`.
170
170
  account-level feature flag gates channels on every route. The allowlist
171
171
  matches the marketplace by name.
172
172
 
173
- ## Exact-home launch prompt consent
174
-
175
- `launchPromptAnswers` belongs only in the host's `oats-local.yaml`. It is
176
- refused in workspace and soul declarations. Add an entry only for a home whose
177
- owner has explicitly authorized Claude's aweb development-channel confirmation:
178
-
179
- ```yaml
180
- launchPromptAnswers:
181
- homes:
182
- /absolute/canonical/instance/home:
183
- awebDevelopmentChannel: false
184
- ```
185
-
186
- `awebDevelopmentChannel` is a strict boolean; absent means `false`. Unknown keys
187
- are refused. `workspaceTrust` is unsupported: remove it and handle folder trust
188
- through the explicit [native trust command](harness-trust.md). Launch prompt
189
- consent does not authorize a native trust write.
190
- Each home key is an exact absolute canonical path, with no symlink alias,
191
- wildcard, dot segment, trailing separator, ancestor inheritance or soul-wide
192
- default. A home not yet created uses its resolved existing directory ancestor
193
- plus its intended suffix; launch checks the created home's identity again.
194
- No existing home is enabled automatically. Removing an entry disables consent
195
- for future launches.
196
- On a case-insensitive filesystem (the macOS default) one home has several
197
- letter-case spellings, and a key in any of them is valid. A key spelled exactly
198
- as the home is launched decides. Otherwise the single key naming the same
199
- directory decides, and `consentSource` points at that key. Several keys naming
200
- it in different case, with none spelled exactly, decide nothing: no consent.
201
- Consent never reaches another directory.
202
-
203
- The sole confirmation covered is Claude's development-channel prompt for
204
- `plugin:aweb-channel@awebai-marketplace`. The provider's `claudeChannelMode`
205
- selects arguments; it does not grant consent. Approved-mode arguments, another
206
- plugin, multiple plugins or contradictory channel arguments cannot qualify.
207
- Environment values, spawn flags and saved launch recipes cannot enable consent.
208
- Existing harness folder-trust configuration remains independent.
209
- The version-independent route, with no prompt to answer, is
210
- [the approved route](#claude-channel-delivery-the-approved-route).
211
-
212
- Preview reports effective `launchPromptAnswers.awebDevelopmentChannel` and
213
- `consentSource` without terminal capture or input. `--no-launch` never answers.
214
- The qualified fixture is limited to Claude 2.1.289 on `darwin-arm64`, at terminal
215
- geometry 110 columns by 35 rows, with executable SHA-256
216
- `03d66745e3bb69ec727d66023696f3820bc0a00a8a5ba725eb6706d0c67cbe69`.
217
- The launch must satisfy these guards and the exact complete frame, selection
218
- and argument checks. Reported version alone is insufficient; another
219
- executable, platform, geometry or prompt variant does not inherit acceptance.
220
- The qualified channel frame starts on its accepted option and permits one
221
- Enter only. Folder-trust and API-key questions remain unexpected and block.
222
- A qualified normal-output boundary closes observation without asserting readiness.
223
-
224
- **Qualified completion and limitation:** the existing exact captured and
225
- source-derived empty API/subscription frames remain supported. After one recorded
226
- submitted channel Enter, the same qualified Claude 2.1.289 darwin-arm64 executable
227
- also recognizes the [bounded bottom input/footer structure](launch-prompt-completion.md)
228
- at 110x35. Its six mode labels, five effort labels and finite hints are
229
- source-qualified; header/billing/model and preceding task text are not structural
230
- completion conditions. The 21 exact question markers take precedence over both
231
- completion paths after submission. Normal `? for shortcuts` and `esc to interrupt`
232
- are not markers. Input authorization and exact-home consent are unchanged.
233
-
234
- **Accepted reporting risk:** an unknown dialog retaining the composer/footer can
235
- be misclassified completed. Completion permanently closes input authority, but
236
- proves neither absence of all questions nor idle/account/channel readiness.
237
- Missing effort, trailing notices, wrapped footers and other unsupported shapes
238
- still block. A feature-flag footer change can reduce matches without a binary
239
- change. A matched structural frame must be saved privately before completed is
240
- audited; failure reports incomplete with the answer and target preserved.
241
-
242
- A submitted Enter can therefore precede `E_SPAWN_INCOMPLETE`; the pane may already
243
- be active. Inspect the answer, checked event receipt and retained target, rather
244
- than automatically retrying input or relaunching. Existing API fixtures used
245
- isolated dummy credentials; the observed Max regression is a labeled home-only
246
- sanitized derivative of one controller-compared in-progress frame, not a new
247
- end-to-end launch proof or general production-success claim.
248
-
249
- When a harness update changes the version-bound prompt frame, opted-in homes
250
- block again with `blocked: unexpected prompt` until fixtures are refreshed.
251
- There is no fallback keystroke or broader matching rule. The returned
252
- `launchPrompts.receipt` identifies the launch-prompt event receipt; the home
253
- and pane are retained for inspection. See [launch outcomes](execution-targets.md#launch-prompt-outcomes)
254
- for recovery. Answering a confirmation never establishes harness or messaging
255
- receive readiness.
173
+ ## The development-channel confirmation
174
+
175
+ **What engages it.** Whenever OATS itself starts Claude Code (a spawn, `oats
176
+ session start` or `session restart`, by hand or by an agent) with
177
+ `--dangerously-load-development-channels plugin:aweb-channel@awebai-marketplace`
178
+ in its argv, the launcher confirms Claude's development-channel prompt once.
179
+ Launching with that flag is the decision: there is no consent setting and no
180
+ list of homes. Every Claude home the messaging provider starts in development
181
+ mode (`settings.oats.aweb.delivery: channel` with `claudeChannelMode:
182
+ development`, today's defaults) is covered, existing homes included at their
183
+ next start. This reverses the earlier rule that no existing home is enabled
184
+ automatically. Any other argv (approved-mode `--channels`, another plugin,
185
+ several plugins, contradictory channel arguments), Codex and pi never engage it,
186
+ and nothing is captured. `--no-launch` never answers.
187
+
188
+ **What it proves before the one key.** The visible screen of the pane this start
189
+ created, normalized by the [enumerated tolerance](../lib/launch-prompt-fixtures/README.md)
190
+ (box-drawing rows dropped, whitespace collapsed, nothing else), must equal one
191
+ entry of the tolerance list: the confirmation's own text, exactly one channel
192
+ (`plugin:aweb-channel@awebai-marketplace`), the affirmative option
193
+ `1. I am using this for local development` with `❯` before it, option `2. Exit`
194
+ without it, and nothing else on the screen. Matching does not depend on the pane
195
+ width, the Claude binary or the platform: one entry covers Claude 2.1.289 and
196
+ 2.1.296 on macOS and Linux, from committed captures, and a release review
197
+ reports the same match for 2.1.288 on linux-x64. A pane too narrow for Claude to wrap at word
198
+ boundaries (about 40 columns for this prompt) does not match.
199
+
200
+ **What it never does.** It sends one `Enter`, never another key, never a retry,
201
+ and never into a pane it did not create in this start (a respawned pane must
202
+ show a new process and a fresh screen). It confirms no other prompt: folder trust
203
+ (owned by [`oats harness trust`](harness-trust.md)), API-key and login questions
204
+ are unexpected and block. While the screen keeps changing it waits, within 30 s
205
+ at 100 ms. An unknown screen is no verdict until it has held unchanged for the
206
+ settle window (`SETTLE`, 2 s): Claude paints transient frames while it starts (a
207
+ logo mid-animation, a renderer notice) and can hold one for a second or more
208
+ under load. An unknown screen that holds still for `SETTLE` blocks with no key,
209
+ `blocked: unexpected prompt`, and the receipt says what `differed` from the
210
+ nearest entry. A screen still changing when the 30 s bound is reached, or blank
211
+ for the whole bound, never settled into a prompt: it blocks with no key,
212
+ `blocked: observation timeout`, keeping what `differed` and the last screen as
213
+ evidence, and its error and readiness remedy say no prompt was established (look
214
+ at the pane; restart a running session) rather than to read and answer one. The instance then waits for a person: the spawn is retained
215
+ (`E_SPAWN_INCOMPLETE`), the home records `launchPrompts.status: "blocked"`, and
216
+ readiness shows the `launch-prompt` warning. Every attempt and outcome is a
217
+ `launch-prompt` event carrying the Claude version read from the executable's
218
+ path (`claudeVersion`, `claudeVersionSource`) and the entry it matched; the
219
+ version is `unknown` when Claude is started through a wrapper, whose path carries
220
+ no version, so it informs and never decides. What
221
+ follows the Enter is reported, never answered: the start completes after
222
+ `SETTLE` (2 s) of consecutive clean captures (no question marker, no
223
+ confirmation; the screen may keep changing), and a question first painted more
224
+ than 2 s after the session is working is the session's own, not a launch prompt.
225
+ See [launch completion](launch-prompt-completion.md).
226
+
227
+ **When Claude ignores the flag.** This affects a Claude account (or
228
+ organization) for which Claude Code offers no channels, on the messaging
229
+ provider's default `delivery: channel`. Claude Code disables channels when telemetry is opted out (`DISABLE_TELEMETRY`, `DO_NOT_TRACK`, `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`), so a launch
230
+ environment that sets any of them is affected the same way; the messaging
231
+ provider's readiness warning names the three variables that do it. Claude then ignores
232
+ `--dangerously-load-development-channels`, shows no confirmation, and starts the
233
+ session with a notice: `--dangerously-load-development-channels ignored
234
+ (plugin:aweb-channel@awebai-marketplace) Channels are not currently available`.
235
+ Before 0.52 such a start reported launched and said nothing, and the instance
236
+ was never woken by mail or chat. Now, when that notice block equals a
237
+ `flag-ignored` tolerance entry (the block's rows with their `▎` dropped,
238
+ normalized the same way; never a contains test; the entry takes no input), and
239
+ the screen shows no question (none of the
240
+ [question markers](launch-prompt-completion.md)), OATS sends no key and the start
241
+ succeeds. A notice beside a question blocks like any unknown screen. It records `launchPrompts: {status:
242
+ "flag-ignored", reason: "channels-unavailable", signatureId, startId, at}` (the
243
+ entry's id, no screen text), and the start's warnings say, in place of the
244
+ statement that OATS confirms the prompt:
245
+
246
+ > Claude reported that channels are not currently available and ignored the development-channel flag, so this instance gets no channel delivery: mail and chat will not wake it. Check first for a telemetry opt-out in the launch environment (DISABLE_TELEMETRY, DO_NOT_TRACK or CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: Claude Code disables channels when one is set), then whether this Claude account offers channels; otherwise change the messaging provider's delivery (its readiness warning says where the setting is). See docs/configuration.md#the-development-channel-confirmation.
247
+
248
+ Every start says so until the cause is removed or delivery changes. The kernel's readiness shows no `launch-prompt` warning for it; the
249
+ messaging provider's readiness reports the missing channel. A notice in a wording
250
+ no entry holds is an unknown screen and blocks.
251
+
252
+ **Known limit: a hidden notice.** Claude shows a limited number of notices. On a
253
+ fresh Claude configuration another notice (for example, auto mode becoming the
254
+ default) can take the slot and keep this one behind `1 more notice hidden`,
255
+ typically on an instance's first spawn. OATS cannot see a hidden notice, so that
256
+ start stays `blocked: unexpected prompt` (no key, the home retained). When the
257
+ blocked screen starts with Claude's running-session banner (`Claude Code
258
+ v<semver>` after the logo, which may be caught mid-animation), the error and the readiness remedy add:
259
+
260
+ > Claude may have reported that channels are not currently available and ignored the development-channel flag, its notice hidden behind another one: look at the pane. If the session is running, restart the instance, and the notice will then show. Check first for a telemetry opt-out in the launch environment (DISABLE_TELEMETRY, DO_NOT_TRACK or CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC), then whether this Claude account offers channels; otherwise change the messaging provider's delivery (its readiness warning says where the setting is). See docs/configuration.md#the-development-channel-confirmation.
261
+
262
+ A restart where the notice shows records `flag-ignored`.
263
+
264
+ **The two settings that stop it.** OATS confirms the prompt only because the
265
+ deployment launches Claude with the development-channel flag. To keep the prompt
266
+ for a person, stop launching that way: `settings.oats.aweb.delivery: session`
267
+ (the host wake broker instead of the channel), or `settings.oats.aweb.claudeChannelMode:
268
+ approved` ([the approved route](#claude-channel-delivery-the-approved-route), no
269
+ prompt at all). Both are captured at spawn, so respawn a home to change it. Every
270
+ start that engages the confirmation says so in its output (`launch-config preview`,
271
+ the spawn's warnings, `session start|restart`). `spawn --preview` cannot say it
272
+ yet: the argv comes from the provider's spawn hook, which a preview does not run.
273
+
274
+ **A new Claude wording** blocks loudly until a reviewed change adds it as a new
275
+ tolerance entry with its captured provenance. Until then, read the prompt in the
276
+ instance's terminal and press Enter yourself.
277
+
278
+ **An old `launchPromptAnswers` block** in `oats-local.yaml` is judged, never used:
279
+
280
+ - only `awebDevelopmentChannel: true` entries, an empty block, or
281
+ `workspaceTrust`: ignored, with one warning per command naming the key and
282
+ saying to remove it;
283
+ - any home entry `awebDevelopmentChannel: false`: refused (`E_WORKSPACE_SCHEMA`,
284
+ reason `removed-key`, at that entry), because this kernel can no longer honour
285
+ that refusal. The message names the two settings above.
286
+
287
+ `launchPromptAnswers` remains refused in workspace and soul declarations.
256
288
 
257
289
  ## Launch configurations
258
290
 
@@ -276,7 +308,8 @@ configuration is a host choice: a soul never names one.
276
308
  it.
277
309
  - `oats launch-config list` shows the effective entries;
278
310
  `oats launch-config set <name> --file <json>` and
279
- `oats launch-config remove <name>` rewrite only this block;
311
+ `oats launch-config remove <name>` rewrite only this block, under the
312
+ lock every kernel command that rewrites `oats-local.yaml` holds;
280
313
  `oats launch-config preview (--home <abs> | --soul <name>) --json` shows
281
314
  what a start would run (harness, model, executable, argv, redacted
282
315
  environment, command and preflight checks) and starts nothing.
@@ -307,6 +340,18 @@ account directory (`CLAUDE_CONFIG_DIR`), a wrapper `executable`, an argument.
307
340
  - **One per harness.** A second `default: true` for the same harness is
308
341
  refused (`E_LAUNCH_CONFIG_INVALID`, naming both); move it by clearing the
309
342
  old one first.
343
+ - **Several configurations and no default is ambiguous for a spawn.** When a
344
+ spawn's harness has more than one configuration here, none of them
345
+ `default: true`, and the spawn names none, it is refused in preview and
346
+ apply alike (`E_LAUNCH_CONFIG_AMBIGUOUS`, naming the harness and its
347
+ configurations) instead of starting the bare harness. Naming one decides
348
+ it: `--launch-config <name>`, `--launch-config none` (the bare harness) or
349
+ a `souls.launch` name (`none` included). An inline `souls.launch`
350
+ preference, the soul's `launch:` and `--harness` alone name no
351
+ configuration. One configuration for the harness is not ambiguous (without
352
+ `default: true` it is not used). `oats souls` and `oats inspect --soul`
353
+ show the refusal as the launch's `problem`. A start or restart of an
354
+ existing home, with `--harness` or `--reselect-launch` too, is not refused.
310
355
  - **Existing homes keep their launch** until `--reselect-launch` or a
311
356
  respawn, like any change of preference. Declaring a default is such a
312
357
  change: `oats readiness --home` warns `launch-changed` on each existing
@@ -345,6 +390,38 @@ souls:
345
390
  oats.engineering/code-reviewer: { harness: codex } # a package soul
346
391
  ```
347
392
 
393
+ - **Write `souls.launch` with `oats soul launch`** (0.53.0), not by hand:
394
+
395
+ ```
396
+ oats soul launch set <soul>|'*' (--launch-config <name>|none | --harness pi|claude|codex [--model <id>])
397
+ oats soul launch remove <soul>|'*'|<exact key>
398
+ ```
399
+
400
+ each with `--plan` (every check, nothing written), `--dir <deployment>`
401
+ and `--json`.
402
+ - `set` names the soul as a spawn does and writes the key that soul has:
403
+ its bare name, or `<package>/<soul>` for a package's. So it cannot write
404
+ a key that names no soul. `'*'` is every soul without an entry of its
405
+ own. `--launch-config <name>` must be a launch configuration this file
406
+ declares (`none` is the bare harness); `--harness` writes the inline
407
+ preference.
408
+ - `remove` takes a soul, `'*'`, or the exact text of a key in the file.
409
+ The exact text is tried first and needs no read of the workspace, so a
410
+ key that names no soul can always be removed. An entry the file does not
411
+ have is refused (`E_LAUNCH_PREFERENCE_UNKNOWN`), never answered "done".
412
+ - Both answer what the next spawn of that soul selects, and every key of
413
+ `souls.launch` that still names no soul the workspace offers.
414
+ - **The file is rewritten, and every other entry keeps its value and its
415
+ comments.** The write holds the lock `oats teams` holds, so neither
416
+ drops the other's change.
417
+ - **A name two members offer.** A member's soul is keyed by its bare name,
418
+ so one entry pins every member's soul of that name: an entry cannot pin
419
+ one of them and leave the other. `oats soul launch set <member>/<soul>`
420
+ writes the bare name and lists each soul the entry applies to; the bare
421
+ name alone is refused, as for a spawn (`E_SOUL_AMBIGUOUS`). To run one
422
+ of them differently, name its launch on that spawn (`--launch-config` or
423
+ `--harness`), or keep the other off this machine (`souls.disabled` takes
424
+ `<member>/<soul>`).
348
425
  - **Precedence for a new launch:** `--launch-config` or `--harness`, then
349
426
  `souls.launch.<soul>`, then `souls.launch."*"`, then the soul's `launch:`,
350
427
  then `pi` with its defaults. `--model` alone keeps the deciding layer's
@@ -353,9 +430,41 @@ souls:
353
430
  **inline or soul preference** runs its harness the way this host starts it
354
431
  without a configuration: [the harness default](#the-harness-default) if
355
432
  one is declared, else the executable on `PATH` with no args and no env,
356
- with the preference's `model`. A preference without `model` uses the
433
+ with the preference's `model`. A spawn is refused instead when the harness
434
+ has several configurations and none is its default
435
+ (`E_LAUNCH_CONFIG_AMBIGUOUS`). A preference without `model` uses the
357
436
  harness default's model, else the harness's own; it never borrows a lower
358
437
  layer's.
438
+ - **A key that names no soul refuses the launches it might have pinned**
439
+ (0.53). While `souls.launch` holds a key, other than `"*"`, that is the key
440
+ of no soul the workspace offers, a new launch that names no launch, of a
441
+ soul with no entry of its own, is refused
442
+ (`E_LAUNCH_PREFERENCE_UNMATCHED`). `souls.launch."*"`, the soul's `launch:`
443
+ or the host default would have decided that launch, and the kernel cannot
444
+ tell which soul the key was meant to pin. Before 0.53 the key was never
445
+ read, and the soul it was written for ran on the fall-through.
446
+ - **Refused:** `oats spawn`, preview and apply, and `oats session
447
+ start|restart --reselect-launch`, before anything is created, stopped or
448
+ started. `--model` alone names no launch.
449
+ - **Goes on:** a soul with its own entry; a launch named with
450
+ `--launch-config` or `--harness`; a plain start or restart of an
451
+ existing home, which selects nothing again.
452
+ - **The remedy, in this order:** pin the soul the key was meant for (`oats
453
+ soul launch set <soul> --launch-config <name>`, or `--harness <h>`),
454
+ then remove the key (`oats soul launch remove <key>`). Removing first
455
+ ends the refusal and leaves that soul on the fall-through. The refusal
456
+ names the keys and, for each, the nearest soul keys.
457
+ - **Where it shows:** `oats souls` and `oats inspect --soul` carry it on
458
+ each soul a spawn would refuse and list each such key; `oats doctor`
459
+ lists each key with the command that removes it, from this machine's
460
+ last read of the souls.
461
+ - **A key the kernel could not check refuses nothing:** a bare key while a
462
+ member is not confirmed or a member's or an external soul failed to
463
+ read, a `<package>/…` key while that package is declared and not locked
464
+ or one of its souls failed to read, and every key in the standalone view
465
+ of a workspace whose host cannot be read. `oats doctor` says so
466
+ (`launch-preference-unchecked`). The key of a soul listed in
467
+ `souls.disabled` matches that soul. `"*"` is never reported.
359
468
  - **A missing harness is refused**, never replaced: `E_HARNESS_UNAVAILABLE`
360
469
  names the layer that chose it and the fix (install the harness, or override
361
470
  it here in `souls.launch`). `oats souls` still lists the soul, with the