@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
@@ -25,6 +25,53 @@ session) is visible there. If the terminal is not ready within the wait, a
25
25
  notice says so and the instance's row opens it later. A refused launch keeps
26
26
  the dialog open with the kernel's error.
27
27
 
28
+ A start or restart that stops at a launch prompt is not a refusal: the kernel
29
+ keeps the session and answers `E_SPAWN_INCOMPLETE` with the outcome it
30
+ observed, as for a spawn. The dialog then says, in Desktop's words, that OATS
31
+ could not confirm the instance finished starting, with the kernel's reason and
32
+ whether input was sent, that its session was kept, and what to do: refresh
33
+ status, then open its terminal to read what it shows, and not start it again
34
+ before that. Under that sentence it shows what the screen differed in from the
35
+ confirmation OATS answers, when the kernel reported it ("OATS expected:" and
36
+ "The terminal showed:", the terminal's text as an attributed quote), and the
37
+ kernel's own message under "OATS says:". It never says the start failed, and
38
+ never that the instance started. An outcome the Desktop cannot read shows the
39
+ kernel's message, as before.
40
+
41
+ A start or restart can work while Claude Code ignores the development-channel
42
+ option: the instance runs, and mail and chat will not wake it. From 0.52 the
43
+ kernel's successful answer says so (`launchPrompts.status: "flag-ignored"`).
44
+ That start worked, so the dialog closes and the terminal opens as for any
45
+ start. A notice then says that the instance started and that Claude Code
46
+ ignored the channel option, so mail and chat will not wake it; with the reason
47
+ `channels-unavailable` it adds that Claude Code reported channels are not
48
+ available. Behind the notice's Details: "OATS says:" and the warnings of that
49
+ answer, whole and in the order given, each as one display line. It shows at
50
+ most 16 warnings, and at most 4096 characters of them: lines are taken in
51
+ order while both bounds hold, and no line is cut inside. With more, a last
52
+ line says how many are left out ("3 more not shown."). The cut is by
53
+ position. No warning is picked, matched or dropped by its words: the kernel's
54
+ own sentence is one string among them, and Desktop does not look for it. The
55
+ kernel puts that sentence last, so warnings that fill the bound before it
56
+ leave it out: the headline still says what happened, a person then does not
57
+ see OATS's own advice on what to check, and the last line says that something
58
+ was left out. The notice is also shown when the dialog was closed while the
59
+ start ran, as long as the workspace it was started from is still on screen.
60
+
61
+ The reader is `launchFlagIgnored` (`packages/client/launch-prompt-outcome.mjs`).
62
+ It takes an answer's `launchPrompts` and `warnings` and gives the fact
63
+ `{reason, warnings, omitted}`: the lines it keeps, bounded by
64
+ `FLAG_IGNORED_WARNINGS` lines and `FLAG_IGNORED_UNITS` UTF-16 units in total,
65
+ and how many lines the cut left out. It knows nothing of the act that was
66
+ answered. `flagIgnoredNotice` makes the headline and the
67
+ detail from that fact, and from nothing else. Both are tolerant: an answer the
68
+ reader cannot read, or any other status, gives no fact and no notice, and the
69
+ start reads as any start that worked. The start dialog calls them for a
70
+ start's and a restart's answer. A launched spawn's answer goes through the same
71
+ reader into its creation receipt, and the notice is the same
72
+ (`packages/desktop/docs/desktop-spawn-preview.md`, A spawn where Claude Code
73
+ ignored the channel option).
74
+
28
75
  If an ordinary Start dialog finds the instance already running, its action becomes
29
76
  **Open terminal**. A failed or timed-out start requires **Refresh status** before
30
77
  another attempt, because the launch may have succeeded before the reply was
@@ -70,6 +117,28 @@ The installed CLI must advertise `session-start`; remote starting also needs
70
117
  the remote operation. The execution host checks the actual saved session
71
118
  before launch. Desktop does not scaffold a home or execute a launcher itself.
72
119
 
120
+ A start that worked answers the kernel's result, whole. A failed start answers
121
+ `{error, code}`: the kernel's message and its code. When
122
+ the code is `E_SPAWN_INCOMPLETE` and its details hold a launch-prompt outcome
123
+ for the instance the route resolved, the answer also carries `incomplete`: the
124
+ details decoded by `retainedSpawnDetails`
125
+ (`packages/client/launch-prompt-outcome.mjs`), the same projection a spawn's
126
+ retained result uses. It is decoded again on the way to the dialog by the two
127
+ places that list the keys an error carries (`apiJson` and `httpError` in
128
+ `renderer/views/common.mjs`), and kept only beside that code.
129
+
130
+ In the app, main's `api` proxy waits 70 seconds for a start or a restart (the
131
+ route class `instance-start` of `api-url.mjs`, answered for exactly the paths
132
+ the server routes as one), where an ordinary read has 20. The kernel may watch
133
+ a launch prompt for 30 seconds before it answers what it kept, and the CLI call
134
+ has its own limit (`cliStart`, 60 seconds): the proxy must outlast that call,
135
+ and a test holds the two together, so the dialog shows the kernel's outcome, or
136
+ the CLI's own timeout, and never the proxy's.
137
+
138
+ A client never ends a start. The route awaits the CLI call whatever becomes of
139
+ its request: when the proxy gives up, or a window closes, the call runs to its
140
+ own end and the route goes on after it. Only the call's own limit ends it.
141
+
73
142
  Status collection reads each instance's recorded tmux socket and session,
74
143
  with one query per socket per collection. A launcher shell with a harness
75
144
  child remains running; a fallback shell or dead pane is stopped. Errors that
package/docs/desktop.md CHANGED
@@ -501,10 +501,13 @@ Developer docs live in [`packages/desktop/README.md`](../packages/desktop/README
501
501
  (electron-builder; macOS ad-hoc signed — not Developer ID, not notarized —
502
502
  certificate auto-discovery disabled) and
503
503
  `npm run dist:smoke` verifies the packed artifact. Build/release CI uses the
504
- marked build-verify mode (inventory + strict codesign verification +
505
- node-pty ABI + a headless run of the bundled backend and its liveness
506
- collector from `app.asar`, no GUI launch); a local
507
- interactive run may also exercise the launch phase. The headless run starts
508
- the backend as the app does, checks that it answers and that it exits when its
509
- stdin closes, and runs the collector once; it does not exercise the GUI or,
510
- on Linux, the AppImage's launcher and runtime.
504
+ marked build-verify mode on every leg (inventory + strict codesign
505
+ verification + node-pty ABI + a headless run of the bundled backend, of its
506
+ liveness collector and of every module main imports, from `app.asar` and the
507
+ `client/` directory beside it, no GUI launch). The Linux leg then runs the
508
+ smoke once more with its launch phase, under a virtual display; no macOS leg
509
+ launches the window. A local interactive run may also exercise the launch
510
+ phase. The headless run starts the backend as the app does, checks that it
511
+ answers and that it exits when its stdin closes, and runs the collector once;
512
+ it does not exercise the GUI or, on Linux, the AppImage's launcher and
513
+ runtime.
@@ -130,6 +130,68 @@ options and environment, are left exactly as they were.
130
130
  earlier kernel failed a start whose recorded tmux server could not be
131
131
  reached when a sizing command was refused; this one does not.
132
132
 
133
+ #### A server started from inside a systemd service
134
+
135
+ A tmux server lives in the cgroup of the process that started it. When that
136
+ process runs inside a systemd service, the server and every agent pane in it
137
+ end when the service stops. The schedule tick's oneshot service ends after
138
+ each tick, and a Desktop run as a user service restarts at each upgrade. So,
139
+ on Linux, when OATS starts the `oats` server (no server answered) from inside
140
+ a service, it starts it in a transient scope of its own:
141
+
142
+ ```text
143
+ systemd-run --user --scope --collect --quiet --unit oats-tmux-<hash>-<random> -- env -u INVOCATION_ID tmux -u -L oats new-session -d …
144
+ ```
145
+
146
+ - **Only what changes.** The tmux command, its arguments and the environment
147
+ the server starts with are the same as without the scope, less any
148
+ `INVOCATION_ID`. `systemd-run` exports the scope's own `INVOCATION_ID` to
149
+ what it runs, and the system's `env -u INVOCATION_ID` removes it, so
150
+ neither the server nor its panes get it. It also removes a service's own
151
+ `INVOCATION_ID` that the start's environment would otherwise carry (when the
152
+ login environment cannot be read and the creator's is used). There is one
153
+ scope per start that starts the server: `<hash>` is the first 12 hex digits
154
+ of the SHA-256 of the server's address, and `<random>` 8 random hex digits.
155
+ `systemd-run` and `env` are the system's own (`/usr/bin`, `/bin`), never
156
+ ones found on `PATH`.
157
+ - **The server outlives the service.** It is a sibling of the service, not
158
+ part of it: the service can end, stop or restart, and the server and its
159
+ agents go on. The scope ends when its last process does, and `--collect`
160
+ removes it then. That is usually the server. On a tmux without systemd
161
+ support the panes are in the scope too, so a process that outlives the
162
+ server (one an agent started in the background) keeps the scope until it
163
+ exits. On a tmux with systemd support each pane has a scope of its own,
164
+ but the dead server's scope still stays listed (`loaded inactive dead`)
165
+ while a process from one of its panes lives. Either way, a later start
166
+ never reuses that scope: it gets one of its own.
167
+ - **See it:** `systemctl --user status 'oats-tmux-<hash>-*.scope'` (or
168
+ `'oats-tmux-*.scope'` for every OATS server), or
169
+ `systemd-cgls --user`. A tmux built with systemd support also puts each
170
+ pane in a `tmux-spawn-<id>.scope` of its own.
171
+ - **When the creator is inside a service:** `/proc/self/cgroup` is the
172
+ unified hierarchy (one `0::<path>` line) and the path's last component ends
173
+ in `.service`. An operator's shell (`session-N.scope`), an agent's pane, and
174
+ macOS are not, and start the server as before. A server that already
175
+ answers is used as it is.
176
+ - **The limits.**
177
+ - Only the unified cgroup hierarchy is judged. On the old or hybrid
178
+ hierarchy the server starts as before. When `INVOCATION_ID` shows the
179
+ creator is a systemd service, the answer warns that the server lives in
180
+ that service.
181
+ - The scope needs the user's systemd manager and its bus
182
+ (`XDG_RUNTIME_DIR`), and `systemd-run` and `env` in `/usr/bin` or `/bin`:
183
+ a host without them gets the warning below at every start from a
184
+ service. A system service (one outside the user's manager) is
185
+ wrapped the same way, and without a user bus it gets the warning below.
186
+ - When `systemd-run` is missing or fails, and no other creator's server
187
+ answers in the meantime, the server starts as before. The answer's
188
+ `warnings` (spawn, session start and restart), and the schedule tick's
189
+ record of that run, then say `the OATS tmux server was started inside
190
+ <unit>: it ends when that unit stops; start the OATS tmux server from
191
+ your own shell, or enable the user systemd bus (<reason>)`.
192
+ - macOS is not wrapped: launchd lets the server, which leaves the job's
193
+ process group, outlive the job.
194
+
133
195
  <a id="the-servers-start-environment"></a>
134
196
  #### The environment of the server and its panes
135
197
 
@@ -318,6 +380,7 @@ with: `COLORFGBG`, `TMUX`, `TMUX_PANE`; the launch identity and roots
318
380
  (`OATS_INSTANCE`, `OATS_INSTANCE_HOME`, `OATS_HOME`, `OATS_AGENT`,
319
381
  `OATS_SOUL`, `OATS_SOUL_ID`, `OATS_ROOT`, `OATS_CONTEXT`, `OATS_WORKSPACE`,
320
382
  `OATS_EVENT`, `OATS_SETTINGS`, `OATS_SETTINGS_ORIGINS`, `OATS_CLI_BIN`,
383
+ `OATS_NODE_BIN` (the node a hook writes into anything that outlives it),
321
384
  `PI_AGENT_INSTANCE`, `PI_AGENT_HOME`, `PI_AGENTS_ROOT`); what a hook, an
322
385
  operation, a retire or a trigger is given (`OATS_CAPABILITY`, `OATS_LAYER`,
323
386
  `OATS_LEVEL`, `OATS_META`, `OATS_DEPLOYMENT`, `OATS_RESOLUTION`,
@@ -327,8 +390,10 @@ operation, a retire or a trigger is given (`OATS_CAPABILITY`, `OATS_LAYER`,
327
390
  `OATS_TRIGGER_EVENT_FILE`, `OATS_TEST_LOGIN_SHELL` (a test seam that replaces
328
391
  the login shell, honoured only for a process whose `HOME` is not your home
329
392
  directory; a launch configuration cannot set it),
330
- `OATS_TEST_WORKTREE_HOOK_TIMEOUT_MS`, `OATS_TEST_WORKTREE_FETCH_TIMEOUT_MS`
331
- and `OATS_TEST_PROCESS_START_PS` (below), a `worktree` hook's tree
393
+ `OATS_TEST_WORKTREE_HOOK_TIMEOUT_MS`, `OATS_TEST_WORKTREE_FETCH_TIMEOUT_MS`,
394
+ `OATS_TEST_PROCESS_START_PS` (below), `OATS_TEST_CGROUP` and
395
+ `OATS_TEST_SYSTEM_TOOL_DIRS` (test seams of the server's
396
+ [own scope](#a-server-started-from-inside-a-systemd-service)), a `worktree` hook's tree
332
397
  (`OATS_TREE`, `OATS_TREE_CLONE`, `OATS_TREE_REMOTE`, `OATS_TREE_MEMBER`,
333
398
  `OATS_TREE_BASE`, `OATS_TREE_BASE_OID`, `OATS_PURPOSE`, `OATS_TREE_ORIGIN`), `OATS_TEAM_NAME`, `OATS_TEAM_SCOPE`,
334
399
  `OATS_TEAM_ID`, `OATS_TEAM_LABEL`, `OATS_TEAM_LABELS`, `OATS_TEAMS`,
@@ -348,7 +413,9 @@ tests can reach it. `OATS_TEST_WORKTREE_FETCH_TIMEOUT_MS` does the same for the
348
413
  the kernel read a process's start time with `ps`, as on a host without
349
414
  `/proc` (macOS), on a host that has it; an absolute path instead runs that
350
415
  file as `ps`, directly and in the same fixed environment; any other value
351
- reads no start at all. A launch configuration cannot set any of them. Do not set them in a deployment.
416
+ reads no start at all. That `ps` is asked for the start and the state in one
417
+ call (`-o lstart= -o stat= -p <pid>`); a file that answers the start alone
418
+ is read as a process that is not a zombie, never as an error. A launch configuration cannot set any of them. Do not set them in a deployment.
352
419
 
353
420
  **An instance creates an agents' session or window without its own
354
421
  environment.** Nothing of an instance's environment reaches a server or a
@@ -617,43 +684,54 @@ starts in place. It never escalates: a harness still running is reported
617
684
 
618
685
  ### Launch prompt outcomes
619
686
 
620
- For a home with [explicit host-local consent](configuration.md#exact-home-launch-prompt-consent),
621
- spawn, start and restart can observe only the process created by that invocation.
622
- A new window supplies the exact pane identity. Reusing a pane requires a changed
623
- numeric process ID and fresh visible bytes differing from the pre-respawn
624
- screen. An already-running process, stale screen or scrollback grants no input
625
- authority. Home, socket, pane, PID, geometry and exact visible signature are
626
- rechecked before each key.
627
-
628
- Observation is bounded to 30 seconds with 100 ms intervals. Only accepted
629
- version/platform-specific startup and prompt frames keep authority open;
630
- unexpected output permanently closes it. Only the exact aweb development-channel
631
- confirmation can be answered, once, with one Enter. Folder-trust and API-key
632
- prompts are unexpected and block; no multi-prompt sequence is authorized.
633
- For a qualified launch, the controller saves the exclusively owned window's
634
- size policy and dimensions, temporarily pins it to the fixture's 110x35
635
- geometry, and confirms the size before matching. It audits restoration on
636
- every exit, including timeout and failure; a replaced process/window is never
637
- resized during cleanup. Pinning a reused pane cannot establish freshness: that
638
- must already be proved at its original geometry. The selected-option frame
639
- is rechecked before Enter. Uncertain submission is never retried. Only the
640
- qualified Claude executable/platform/geometry in
641
- [configuration](configuration.md#exact-home-launch-prompt-consent) has an enabled
642
- development-channel fixture. Installed version alone grants no match. Ordinary
643
- `session input` and wake delivery do not enter this controller.
687
+ When a spawn, start or restart launches Claude with
688
+ `--dangerously-load-development-channels plugin:aweb-channel@awebai-marketplace`
689
+ ([configuration](configuration.md#the-development-channel-confirmation)), the
690
+ launcher observes only the process created by that invocation. A new window
691
+ supplies the exact pane identity. Reusing a pane requires a changed numeric
692
+ process ID and fresh visible bytes differing from the pre-respawn screen, at the
693
+ pane's original size: a resize could reflow the old prompt into a match. An
694
+ already-running process, stale screen or scrollback grants no input authority.
695
+ Home, socket, pane and PID are rechecked before the key, and the screen is
696
+ captured twice, identical, around the durable intent.
697
+
698
+ Observation is bounded to 30 seconds with 100 ms intervals. A blank screen, or
699
+ one that keeps changing (a prompt still being painted), keeps observing. Only a
700
+ screen whose normalized text equals a tolerance entry can be answered, once,
701
+ with one Enter. A screen with a notice block (a maximal run of rows that begin
702
+ with `▎`, each row's `▎` dropped, then the same normalization) that equals a
703
+ `flag-ignored` entry, on a screen with no question marker, means Claude ignored
704
+ the flag and shows no confirmation: the start ends `flag-ignored`, reason `channels-unavailable`, with no key, and
705
+ succeeds. An unknown screen that holds still for the settle window (`SETTLE`,
706
+ 2 s; a transient frame Claude paints while starting is waited out) permanently
707
+ closes authority with `blocked: unexpected prompt`. The last unknown screen when
708
+ the bound is reached, still changing, closes it with `blocked: observation
709
+ timeout` (with `differed` and that screen as evidence; no prompt was
710
+ established). When either screen starts with Claude's
711
+ running-session banner (`Claude Code v<semver>`, after only the logo's block
712
+ elements U+2580–U+259F and spaces), the result carries
713
+ `claudeSessionShown: true`. A screen blank for the whole bound also reports
714
+ `blocked: observation timeout`. Folder-trust and API-key prompts
715
+ are unexpected and block; no multi-prompt sequence is authorized. The controller
716
+ never resizes the pane. Uncertain submission is never retried. Ordinary
717
+ `session input` and wake delivery do not enter this controller. A launch with any
718
+ other argv records `launchPrompts: {status: "not-engaged", startId, at}` and
719
+ captures nothing.
644
720
 
645
721
  Both spawn and start return `E_SPAWN_INCOMPLETE` for retained prompt failures.
646
722
  With `launchPrompts.status` set to `blocked`, the home, actual terminal target,
647
- provider effects and committed parent lineage are retained. Only an opted-in
648
- launch commits a new parent link before dispatch; ordinary launches keep their
649
- post-launch lineage commit and compensate a failed anchor write. That preserves
650
- timing, not overwrite behavior: even non-opted-in parent spawns now refuse an
723
+ provider effects and committed parent lineage are retained. Only a launch that
724
+ engages the confirmation commits a new parent link before dispatch; other launches
725
+ keep their post-launch lineage commit and compensate a failed anchor write. That
726
+ preserves timing, not overwrite behavior: every parent spawn refuses an
651
727
  anchor edited or removed since the original pre-hook snapshot, instead of
652
728
  replacing concurrent changes with stale metadata. `launchPrompts` records `status`,
653
- `answers`, `reason` and event `receipt`; unknown prompts use
654
- `blocked: unexpected prompt`. Status `incomplete` means the audit could not be
655
- completed, including a possible key followed by an audit failure or failure to
656
- retain mandatory structural-completion evidence. It is
729
+ `answers`, `reason` and event `receipt`, and a blocked result `differed`; unknown
730
+ prompts use `blocked: unexpected prompt`. Status `incomplete` means the audit could
731
+ not be completed, including a possible key followed by an audit failure or failure
732
+ to retain completion evidence. No complete clean `SETTLE` window (2 s) within the
733
+ bound after the Enter is `blocked: observation timeout`, with the one Enter in the
734
+ answers. It is
657
735
  not proof that no input was sent. Both outcomes record `launched:false` while
658
736
  retaining the real process/endpoint for inspection: this is never permission
659
737
  to allocate another harness.
@@ -671,28 +749,26 @@ prior evidence, and adds `{ok:false, results:[]}` to the receipt array. That
671
749
  entry means zero audit destinations were attempted, not a successful write.
672
750
  No audit or metadata write is directed into the replacement home.
673
751
 
674
- A blocked result can follow a successfully submitted Enter. The accepted
675
- completion families cover exact installed-plugin and plugin-absent banners,
676
- plus source-derived billing-only variants of those empty frames (Max, Pro,
677
- Team and Enterprise), and source-derived empty Max/bypass/medium frames.
678
- Other model, billing, effort or permission text can leave the pane active while
679
- reporting a retained block. Inspect `answers` and the event receipts; never infer
680
- that nothing started or nothing was answered. See the
681
- [completion limitation](configuration.md#exact-home-launch-prompt-consent).
752
+ A blocked result can follow a successfully submitted Enter: a question marker
753
+ after it, or the confirmation coming back, leaves the pane active while reporting
754
+ a retained block. Inspect `answers` and the event receipts; never infer that
755
+ nothing started or nothing was answered. See the
756
+ [completion rule](launch-prompt-completion.md).
682
757
 
683
758
  ### Private unmatched launch evidence
684
759
 
685
- This section also covers mandatory structural-completion evidence.
760
+ This section also covers mandatory completion evidence.
686
761
 
687
- After a submitted launch answer, an unmatched 110x35 frame is retained locally
688
- at `<home>/.oats/launch-prompt-evidence/<sha256(startId)>/frame.txt`, with
762
+ The screen of a miss (`blocked: unexpected prompt`, before or after the Enter, or
763
+ `blocked: repeated or unsupported prompt`) is retained locally at
764
+ `<home>/.oats/launch-prompt-evidence/<sha256(startId)>/frame.txt`, with
689
765
  `receipt.json` published last. This is the exact UTF-8 text already compared by
690
766
  the controller, including whitespace and final newline, not a later recapture.
691
- It is bounded to 64 KiB and 35 rows. There is no new input, observation, retry,
692
- geometry change or readiness claim. Evidence is also mandatory when the post-answer
693
- [structural completion rule](launch-prompt-completion.md) selects completion.
694
- Previously qualified exact completion does not acquire that requirement. No
695
- frame is saved before a submitted answer or for unrelated blocked reasons.
767
+ It is bounded to 64 KiB, with one row per pane row at the pane's own size. There
768
+ is no new input, observation, retry, geometry change or readiness claim. Evidence
769
+ is also mandatory when the post-answer [completion rule](launch-prompt-completion.md)
770
+ reports completion. No frame is saved for unrelated blocked reasons (ownership,
771
+ timeouts, capture failures).
696
772
 
697
773
  Find the invocation's existing `launch-prompt` event in the home's
698
774
  `.oats-events.jsonl` (or the checked event rows in `launchPrompts.receipt`). Its
@@ -711,9 +787,12 @@ means no independent capture timestamp was recorded. It does not substitute an
711
787
  event timestamp for capture time. Same-uid concurrent mutation between checks is
712
788
  not excluded.
713
789
 
714
- Private receipt version 2 uses `kind:"launch-prompt-frame"` and admits only
715
- `outcome:"blocked", recognition:"unmatched"` or
716
- `outcome:"completed", recognition:"structural"`. These fields describe the
790
+ Private receipt version 2 uses `kind:"launch-prompt-frame"`. This kernel writes
791
+ only `outcome:"blocked", recognition:"unmatched"`,
792
+ `outcome:"completed", recognition:"stable-screen"` or
793
+ `outcome:"flag-ignored", recognition:"notice-block"`; readers also accept
794
+ `outcome:"completed", recognition:"structural"`, written by kernels 0.47–0.51 for
795
+ completion recognized by Claude's footer structure. These fields describe the
717
796
  recognition whose frame was saved, not the final public launch result: a later
718
797
  audit or cleanup failure can still report `incomplete`. Historical version 1
719
798
  receipts with `kind:"launch-prompt-unmatched"` describe blocked/unmatched
@@ -735,11 +814,12 @@ and adds only `; private launch evidence retention failed` to its diagnostic
735
814
  reason. Already published files may remain, including a receipt if a later
736
815
  verification fails; their presence alone is not a success claim. The submitted
737
816
  answer is preserved. Existing event-audit failures still report `incomplete`.
738
- A structural-completion save failure instead reports checked `incomplete` with
817
+ A completion save failure instead reports checked `incomplete` with
739
818
  `private launch evidence retention failed`, preserving the submitted answer and
740
819
  retained target. It never retries publication or input. An audit failure remains
741
820
  incomplete even if private evidence was saved. No public result or event contains
742
- the raw screen or private receipt.
821
+ the raw screen or private receipt; a miss's `differed` carries at most 40
822
+ characters of the normalized screen at its first difference.
743
823
 
744
824
  The frame can contain private task or account text. It stays on this host with
745
825
  no automatic transmission or expiry. Preserve needed evidence privately before
@@ -770,7 +850,11 @@ SIGTERM. Restart the instance later with `oats session start` or
770
850
  `oats session restart`. An instance whose recorded tmux socket file is
771
851
  missing while a process works in its home, or the process scan cannot run,
772
852
  is not reported idle: its result is `E_SESSION_UNAVAILABLE` and nothing is
773
- stopped ([missing socket file](#missing-socket)).
853
+ stopped ([missing socket file](#missing-socket)). A stop apply holds the
854
+ claim of every instance it stops, the one a retire holds (OATS 0.52.0): one
855
+ that meets a retire of any of them answers `E_INSTANCE_RETIRING`, one that
856
+ meets another stop `E_LIFECYCLE_BUSY`, before anything is stopped
857
+ ([the table](desktop-cli-api.md#lifecycle-pairs)).
774
858
 
775
859
  ### Inspect, input and attach
776
860
 
@@ -962,7 +1046,10 @@ Unattended execution never implies yolo.
962
1046
  ### Explicit deployment trust
963
1047
 
964
1048
  Use `oats harness trust --dir <deployment> --harness claude|codex|all --plan`,
965
- then the same command without `--plan`, on the execution host. This is the explicit
1049
+ then the same command without `--plan`, on the execution host. It covers the ambient
1050
+ configuration file and each launch configuration's `CLAUDE_CONFIG_DIR` /
1051
+ `CODEX_HOME`; launch-time checks read the file the launch's own environment
1052
+ selects. This is the explicit
966
1053
  operator-only native-config write path; spawn/start/retire remain read-only with
967
1054
  respect to native trust. See [native trust](harness-trust.md) for qualified formats,
968
1055
  Git-boundary limits, audit evidence and partial-failure recovery. Root trust does
@@ -95,7 +95,9 @@ Select `claude` or `codex` instead of `all` when only one is needed. The apply
95
95
  records a deployment audit; it does not launch a harness. Claude inheritance
96
96
  stops at a Git boundary; Codex uses the existing per-invocation home override.
97
97
  See [native trust](harness-trust.md) for qualification, format and recovery
98
- limits. Spawn and `oats readiness` warn when the selected home remains uncovered.
98
+ limits. A launch configuration that sets its own `CLAUDE_CONFIG_DIR` or
99
+ `CODEX_HOME` is one more file, and the same command covers it. Spawn and
100
+ `oats readiness` warn when the file a launch reads does not establish trust.
99
101
 
100
102
  ## 3. Give the deployment a team
101
103
 
@@ -24,6 +24,31 @@ The command writes only the canonical deployment root's native trust leaf:
24
24
  - Codex: `projects[root].trust_level = "trusted"` in
25
25
  `$CODEX_HOME/config.toml`, or `~/.codex/config.toml`.
26
26
 
27
+ It writes that leaf into every configuration file a launch of the deployment
28
+ reads. The targets of each selected harness are:
29
+
30
+ - the ambient file, selected by the operator's own `CLAUDE_CONFIG_DIR` or
31
+ `CODEX_HOME`, else the default above;
32
+ - one file for each launch configuration (`launch-configs:` in the
33
+ deployment's `oats-local.yaml`) of that harness whose `env` sets
34
+ `CLAUDE_CONFIG_DIR` (claude) or `CODEX_HOME` (codex), as a literal or a
35
+ `{fromEnv: NAME}` reference resolved from the environment the command runs
36
+ in.
37
+
38
+ Targets with the same canonical directory are one file. Each plan entry says
39
+ whether it is the ambient file (`ambient`) and which launch configurations
40
+ use it (`launchConfigs`). A launch configuration whose reference is not set,
41
+ whose path is not absolute, or whose directory does not exist is a named
42
+ `problem` on its entry. OATS never creates a harness configuration directory:
43
+ create it, or start the harness with it once, then rerun. A missing ambient
44
+ directory (`~/.codex` for a user who has never run Codex, for example) means
45
+ the harness has not run as this user: with `--harness all` that harness's
46
+ entry is `skipped`, with its `reason`, and the other harness proceeds; naming
47
+ that harness (`--harness codex`) makes it a problem. Any problem refuses the
48
+ whole plan before a write, as an unsupported file does.
49
+ Each file is verified through the reader under the environment that selects
50
+ it.
51
+
27
52
  Nonempty override directories must be absolute. Directory aliases are resolved;
28
53
  symlink/nonregular/hardlinked leaves, foreign ownership and ACLs refuse. On Linux, GNU ls's single `.` security-context marker is accepted;
29
54
  the context must be readable, match the same-directory candidate before replacement,
@@ -36,7 +61,7 @@ On macOS, any extended-attribute (`@`) or ACL (`+`) marker deliberately refuses,
36
61
  including `com.apple.provenance`. This v1 writer does not copy or remove those
37
62
  attributes. Inspect the selected file; a refusal never authorizes stripping its
38
63
  metadata automatically. Existing file permissions are preserved.
39
- New config directories use 0700 and files 0600. The plan shows the effective file,
64
+ No configuration directory is ever created; a new file uses 0600. The plan shows the effective file,
40
65
  semantic key, current/desired trust scalar, byte digests and override provenance;
41
66
  it never returns other config values or credentials.
42
67
 
@@ -89,6 +114,29 @@ A Claude root entry cannot cover a home behind an intervening Git boundary.
89
114
  Readiness may still warn after an unchanged root apply. Inspect that boundary;
90
115
  do not automatically write a second root or answer a trust dialog.
91
116
 
117
+ ## Launch-time checks and readiness
118
+
119
+ Spawn, `session start|restart`, `launch-config preview` and `oats readiness`
120
+ read folder trust from the file the launch's own environment selects: the
121
+ host's environment plus the launch configuration's `env`. Codex's
122
+ per-invocation home trust follows the same file. They never write it.
123
+
124
+ Readiness reports one `harness-trust` item (in `checks.configured`, never
125
+ required) for the launch a home recorded, or for the launch a soul selects.
126
+ It passes, naming the file, when that file trusts the deployment root or an
127
+ ancestor (for Claude, up to a Git boundary; a yolo Codex launch always
128
+ passes). Otherwise it warns, and the spawn warns with the same text:
129
+
130
+ ```text
131
+ <harness> folder trust is not established in <file>: oats harness trust --dir <deployment>
132
+ ```
133
+
134
+ A missing root entry does not prove that the harness will prompt (a native
135
+ gate can skip the question), so neither says the session will stop. A launch
136
+ configuration whose reference is not set on this host is named instead of a
137
+ file. OATS never answers a folder-trust prompt, and launch consent authorizes
138
+ no trust write.
139
+
92
140
  ## Durability, audit and recovery
93
141
 
94
142
  All selected configs are preflighted before any native write. Cooperating OATS
@@ -110,7 +158,7 @@ or mtime. Plan creates no audit, directory, lock or temporary file. Invalid or
110
158
  truncated existing JSONL refuses until operator inspection.
111
159
 
112
160
  `all` is not a transaction. Failure stops later work, retains earlier changes and
113
- reports unattempted entries. Trust may already have been consumed, so no rollback
161
+ reports unattempted entries; the error message names the failed files. Trust may already have been consumed, so no rollback
114
162
  is simulated. Inspect the native files and audit before rerunning; a correct
115
163
  existing entry converges as a no-op. `E_HARNESS_TRUST_INCOMPLETE` has closed reasons
116
164
  `locked|changed|audit|write|verify` and a conservative `mayHaveChanged` flag.