@awebai/oats 0.51.0 → 0.52.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 (128) hide show
  1. package/README.md +1 -0
  2. package/bin/oats.mjs +109 -37
  3. package/docs/capabilities.md +9 -2
  4. package/docs/configuration.md +134 -88
  5. package/docs/desktop-cli-api.md +927 -92
  6. package/docs/desktop-instance-start.md +56 -0
  7. package/docs/desktop.md +10 -7
  8. package/docs/execution-targets.md +144 -58
  9. package/docs/first-team.md +3 -1
  10. package/docs/harness-trust.md +50 -2
  11. package/docs/implementation.md +66 -9
  12. package/docs/integrations.md +9 -8
  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/oats-local.schema.json +4 -3
  20. package/docs/official-catalog.md +4 -4
  21. package/docs/packages.md +14 -14
  22. package/docs/release-lane.md +15 -5
  23. package/docs/release-notes/v0.44.0.md +1 -1
  24. package/docs/release-notes/v0.52.0.md +933 -0
  25. package/docs/schedules.md +91 -4
  26. package/docs/souls-and-instances.md +95 -25
  27. package/docs/tui.md +152 -0
  28. package/docs/workspaces.md +2 -2
  29. package/lib/claim.mjs +186 -46
  30. package/lib/core.mjs +730 -185
  31. package/lib/errors.mjs +170 -0
  32. package/lib/harness-trust-write.mjs +68 -27
  33. package/lib/harness-trust.mjs +34 -16
  34. package/lib/instance-inspect.mjs +40 -11
  35. package/lib/instance-lifecycle.mjs +169 -47
  36. package/lib/launch-preference.mjs +16 -0
  37. package/lib/launch-prompt-completion.mjs +7 -43
  38. package/lib/launch-prompt-evidence.mjs +14 -7
  39. package/lib/launch-prompt-fixtures/README.md +86 -152
  40. package/lib/launch-prompt-fixtures/dev-channel-confirmation.json +50 -0
  41. package/lib/launch-prompt-fixtures.mjs +122 -109
  42. package/lib/launch-prompt-transport.mjs +2 -56
  43. package/lib/launch-prompts.mjs +102 -100
  44. package/lib/schedule-host.mjs +154 -22
  45. package/lib/schedule.mjs +73 -24
  46. package/lib/system-tools.mjs +39 -0
  47. package/lib/tmux-server-scope.mjs +62 -0
  48. package/lib/triggers.mjs +4 -4
  49. package/lib/workspace.mjs +5 -11
  50. package/lib/worktree-hooks.mjs +98 -20
  51. package/lib/worktree.mjs +83 -24
  52. package/package-catalog.json +3 -3
  53. package/package.json +7 -2
  54. package/packages/client/capability-show-contract.mjs +230 -0
  55. package/packages/client/capability-warnings-contract.mjs +57 -0
  56. package/packages/client/cli-adapter.mjs +548 -0
  57. package/packages/client/cli-environment.mjs +53 -0
  58. package/packages/client/cli-locator.mjs +253 -0
  59. package/packages/client/cli-probe-contract.mjs +47 -0
  60. package/packages/client/client-terms.mjs +60 -0
  61. package/packages/client/deployment-contract.mjs +68 -0
  62. package/packages/client/deployment-data.mjs +483 -0
  63. package/packages/client/deployment-facts.mjs +34 -0
  64. package/packages/client/deployment-label.mjs +76 -0
  65. package/packages/client/deployment-observer.mjs +89 -0
  66. package/packages/client/deployment-panel.mjs +142 -0
  67. package/packages/client/deployment-read-cli.mjs +53 -0
  68. package/packages/client/display-text.mjs +44 -0
  69. package/packages/client/harness-names.mjs +30 -0
  70. package/packages/client/inspect-contract.mjs +62 -0
  71. package/packages/client/instance-acts.mjs +54 -0
  72. package/packages/client/instance-admission.mjs +45 -0
  73. package/packages/client/instance-events-contract.mjs +74 -0
  74. package/packages/client/instance-git-contract.mjs +80 -0
  75. package/packages/client/instance-presentation.mjs +22 -0
  76. package/packages/client/instance-tree.mjs +453 -0
  77. package/packages/client/kernel-environment.mjs +11 -0
  78. package/packages/client/launch-contract.mjs +51 -0
  79. package/packages/client/launch-prompt-outcome.mjs +165 -0
  80. package/packages/client/lifecycle-cli.mjs +61 -0
  81. package/packages/client/lifecycle-contract.mjs +372 -0
  82. package/packages/client/liveness-main.mjs +10 -0
  83. package/packages/client/liveness.mjs +35 -0
  84. package/packages/client/machine-contract.mjs +123 -0
  85. package/packages/client/own-environment.mjs +22 -0
  86. package/packages/client/panel-views.mjs +286 -0
  87. package/packages/client/readiness-contract.mjs +172 -0
  88. package/packages/client/refresh-loop.mjs +52 -0
  89. package/packages/client/remote-address.mjs +126 -0
  90. package/packages/client/remote-roster.mjs +67 -0
  91. package/packages/client/roster-sections.mjs +80 -0
  92. package/packages/client/spawn-apply-cli.mjs +104 -0
  93. package/packages/client/spawn-apply-contract.mjs +183 -0
  94. package/packages/client/spawn-decision.mjs +46 -0
  95. package/packages/client/spawn-messages.mjs +119 -0
  96. package/packages/client/spawn-preview-cli.mjs +32 -0
  97. package/packages/client/spawn-preview-contract.mjs +314 -0
  98. package/packages/client/team-members.mjs +41 -0
  99. package/packages/client/team-rows.mjs +45 -0
  100. package/packages/client/terminal-contract.mjs +57 -0
  101. package/packages/client/tmux-status.mjs +66 -0
  102. package/packages/client/waiting-on-you.mjs +88 -0
  103. package/packages/client/workspace-admission.mjs +45 -0
  104. package/packages/client/workspace-cli.mjs +142 -0
  105. package/packages/client/workspace-views.mjs +147 -0
  106. package/packages/tui/README.md +46 -0
  107. package/packages/tui/bin/tui.mjs +7 -0
  108. package/packages/tui/lib/actions.mjs +29 -0
  109. package/packages/tui/lib/client.mjs +4 -0
  110. package/packages/tui/lib/main.mjs +105 -0
  111. package/packages/tui/lib/term/keys.mjs +323 -0
  112. package/packages/tui/lib/term/screen.mjs +122 -0
  113. package/packages/tui/lib/term/style.mjs +43 -0
  114. package/packages/tui/lib/term/text.mjs +49 -0
  115. package/packages/tui/lib/term/tty.mjs +168 -0
  116. package/packages/tui/lib/term/width.mjs +124 -0
  117. package/packages/tui/lib/views/frame.mjs +62 -0
  118. package/packages/tui/lib/views/help.mjs +28 -0
  119. package/packages/tui/package.json +8 -0
  120. package/skills/oats-getting-started/SKILL.md +29 -22
  121. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +0 -35
  122. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +0 -35
  123. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +0 -35
  124. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +0 -35
  125. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +0 -77
  126. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/max-bypass-source.json +0 -88
  127. package/lib/launch-prompt-fixtures/structural-completion.json +0 -205
  128. package/lib/launch-prompt-policy.mjs +0 -87
@@ -60,7 +60,7 @@ 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. |
@@ -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
 
@@ -307,6 +339,18 @@ account directory (`CLAUDE_CONFIG_DIR`), a wrapper `executable`, an argument.
307
339
  - **One per harness.** A second `default: true` for the same harness is
308
340
  refused (`E_LAUNCH_CONFIG_INVALID`, naming both); move it by clearing the
309
341
  old one first.
342
+ - **Several configurations and no default is ambiguous for a spawn.** When a
343
+ spawn's harness has more than one configuration here, none of them
344
+ `default: true`, and the spawn names none, it is refused in preview and
345
+ apply alike (`E_LAUNCH_CONFIG_AMBIGUOUS`, naming the harness and its
346
+ configurations) instead of starting the bare harness. Naming one decides
347
+ it: `--launch-config <name>`, `--launch-config none` (the bare harness) or
348
+ a `souls.launch` name (`none` included). An inline `souls.launch`
349
+ preference, the soul's `launch:` and `--harness` alone name no
350
+ configuration. One configuration for the harness is not ambiguous (without
351
+ `default: true` it is not used). `oats souls` and `oats inspect --soul`
352
+ show the refusal as the launch's `problem`. A start or restart of an
353
+ existing home, with `--harness` or `--reselect-launch` too, is not refused.
310
354
  - **Existing homes keep their launch** until `--reselect-launch` or a
311
355
  respawn, like any change of preference. Declaring a default is such a
312
356
  change: `oats readiness --home` warns `launch-changed` on each existing
@@ -353,7 +397,9 @@ souls:
353
397
  **inline or soul preference** runs its harness the way this host starts it
354
398
  without a configuration: [the harness default](#the-harness-default) if
355
399
  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
400
+ with the preference's `model`. A spawn is refused instead when the harness
401
+ has several configurations and none is its default
402
+ (`E_LAUNCH_CONFIG_AMBIGUOUS`). A preference without `model` uses the
357
403
  harness default's model, else the harness's own; it never borrows a lower
358
404
  layer's.
359
405
  - **A missing harness is refused**, never replaced: `E_HARNESS_UNAVAILABLE`