@awebai/oats 0.50.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 (132) hide show
  1. package/README.md +1 -0
  2. package/bin/oats.mjs +153 -51
  3. package/docs/capabilities.md +11 -3
  4. package/docs/configuration.md +134 -88
  5. package/docs/desktop-cli-api.md +994 -71
  6. package/docs/desktop-instance-start.md +56 -0
  7. package/docs/desktop.md +10 -7
  8. package/docs/execution-targets.md +230 -59
  9. package/docs/first-team.md +3 -1
  10. package/docs/harness-trust.md +50 -2
  11. package/docs/implementation.md +73 -8
  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 +43 -7
  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.51.0.md +156 -0
  25. package/docs/release-notes/v0.52.0.md +933 -0
  26. package/docs/schedules.md +91 -4
  27. package/docs/servers.md +21 -2
  28. package/docs/souls-and-instances.md +113 -21
  29. package/docs/tui.md +152 -0
  30. package/docs/workspaces.md +2 -2
  31. package/lib/claim.mjs +266 -0
  32. package/lib/core.mjs +845 -166
  33. package/lib/errors.mjs +170 -0
  34. package/lib/harness-trust-write.mjs +68 -27
  35. package/lib/harness-trust.mjs +34 -16
  36. package/lib/instance-inspect.mjs +40 -11
  37. package/lib/instance-lifecycle.mjs +169 -47
  38. package/lib/launch-preference.mjs +16 -0
  39. package/lib/launch-prompt-completion.mjs +7 -43
  40. package/lib/launch-prompt-evidence.mjs +14 -7
  41. package/lib/launch-prompt-fixtures/README.md +86 -152
  42. package/lib/launch-prompt-fixtures/dev-channel-confirmation.json +50 -0
  43. package/lib/launch-prompt-fixtures.mjs +122 -109
  44. package/lib/launch-prompt-transport.mjs +2 -56
  45. package/lib/launch-prompts.mjs +102 -100
  46. package/lib/schedule-host.mjs +154 -22
  47. package/lib/schedule.mjs +73 -24
  48. package/lib/servers.mjs +20 -4
  49. package/lib/session-viewer.mjs +87 -10
  50. package/lib/system-tools.mjs +39 -0
  51. package/lib/tmux-server-scope.mjs +62 -0
  52. package/lib/triggers.mjs +4 -4
  53. package/lib/workspace.mjs +5 -11
  54. package/lib/worktree-hooks.mjs +116 -23
  55. package/lib/worktree.mjs +89 -102
  56. package/package-catalog.json +3 -3
  57. package/package.json +7 -2
  58. package/packages/client/capability-show-contract.mjs +230 -0
  59. package/packages/client/capability-warnings-contract.mjs +57 -0
  60. package/packages/client/cli-adapter.mjs +548 -0
  61. package/packages/client/cli-environment.mjs +53 -0
  62. package/packages/client/cli-locator.mjs +253 -0
  63. package/packages/client/cli-probe-contract.mjs +47 -0
  64. package/packages/client/client-terms.mjs +60 -0
  65. package/packages/client/deployment-contract.mjs +68 -0
  66. package/packages/client/deployment-data.mjs +483 -0
  67. package/packages/client/deployment-facts.mjs +34 -0
  68. package/packages/client/deployment-label.mjs +76 -0
  69. package/packages/client/deployment-observer.mjs +89 -0
  70. package/packages/client/deployment-panel.mjs +142 -0
  71. package/packages/client/deployment-read-cli.mjs +53 -0
  72. package/packages/client/display-text.mjs +44 -0
  73. package/packages/client/harness-names.mjs +30 -0
  74. package/packages/client/inspect-contract.mjs +62 -0
  75. package/packages/client/instance-acts.mjs +54 -0
  76. package/packages/client/instance-admission.mjs +45 -0
  77. package/packages/client/instance-events-contract.mjs +74 -0
  78. package/packages/client/instance-git-contract.mjs +80 -0
  79. package/packages/client/instance-presentation.mjs +22 -0
  80. package/packages/client/instance-tree.mjs +453 -0
  81. package/packages/client/kernel-environment.mjs +11 -0
  82. package/packages/client/launch-contract.mjs +51 -0
  83. package/packages/client/launch-prompt-outcome.mjs +165 -0
  84. package/packages/client/lifecycle-cli.mjs +61 -0
  85. package/packages/client/lifecycle-contract.mjs +372 -0
  86. package/packages/client/liveness-main.mjs +10 -0
  87. package/packages/client/liveness.mjs +35 -0
  88. package/packages/client/machine-contract.mjs +123 -0
  89. package/packages/client/own-environment.mjs +22 -0
  90. package/packages/client/panel-views.mjs +286 -0
  91. package/packages/client/readiness-contract.mjs +172 -0
  92. package/packages/client/refresh-loop.mjs +52 -0
  93. package/packages/client/remote-address.mjs +126 -0
  94. package/packages/client/remote-roster.mjs +67 -0
  95. package/packages/client/roster-sections.mjs +80 -0
  96. package/packages/client/spawn-apply-cli.mjs +104 -0
  97. package/packages/client/spawn-apply-contract.mjs +183 -0
  98. package/packages/client/spawn-decision.mjs +46 -0
  99. package/packages/client/spawn-messages.mjs +119 -0
  100. package/packages/client/spawn-preview-cli.mjs +32 -0
  101. package/packages/client/spawn-preview-contract.mjs +314 -0
  102. package/packages/client/team-members.mjs +41 -0
  103. package/packages/client/team-rows.mjs +45 -0
  104. package/packages/client/terminal-contract.mjs +57 -0
  105. package/packages/client/tmux-status.mjs +66 -0
  106. package/packages/client/waiting-on-you.mjs +88 -0
  107. package/packages/client/workspace-admission.mjs +45 -0
  108. package/packages/client/workspace-cli.mjs +142 -0
  109. package/packages/client/workspace-views.mjs +147 -0
  110. package/packages/tui/README.md +46 -0
  111. package/packages/tui/bin/tui.mjs +7 -0
  112. package/packages/tui/lib/actions.mjs +29 -0
  113. package/packages/tui/lib/client.mjs +4 -0
  114. package/packages/tui/lib/main.mjs +105 -0
  115. package/packages/tui/lib/term/keys.mjs +323 -0
  116. package/packages/tui/lib/term/screen.mjs +122 -0
  117. package/packages/tui/lib/term/style.mjs +43 -0
  118. package/packages/tui/lib/term/text.mjs +49 -0
  119. package/packages/tui/lib/term/tty.mjs +168 -0
  120. package/packages/tui/lib/term/width.mjs +124 -0
  121. package/packages/tui/lib/views/frame.mjs +62 -0
  122. package/packages/tui/lib/views/help.mjs +28 -0
  123. package/packages/tui/package.json +8 -0
  124. package/skills/oats-getting-started/SKILL.md +29 -22
  125. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +0 -35
  126. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +0 -35
  127. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +0 -35
  128. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +0 -35
  129. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +0 -77
  130. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/max-bypass-source.json +0 -88
  131. package/lib/launch-prompt-fixtures/structural-completion.json +0 -205
  132. package/lib/launch-prompt-policy.mjs +0 -87
@@ -25,6 +25,40 @@ 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 every warning of that
49
+ answer, whole and in the order given, each as one display line. No warning is
50
+ picked, matched or dropped by its words: the kernel's own sentence is one
51
+ string among them, and Desktop does not look for it. The notice is also shown
52
+ when the dialog was closed while the start ran, as long as the workspace it was
53
+ started from is still on screen.
54
+
55
+ The reader is `flagIgnoredNotice` (`packages/client/launch-prompt-outcome.mjs`).
56
+ It takes an answer's `launchPrompts` and `warnings`, gives the headline and the
57
+ lines, and knows nothing of the act that was answered. It is tolerant: an
58
+ answer it cannot read, or any other status, gives no notice, and the start
59
+ reads as any start that worked. Only the start dialog calls it: the Desktop
60
+ does not yet read `launchPrompts` on a spawn's answer.
61
+
28
62
  If an ordinary Start dialog finds the instance already running, its action becomes
29
63
  **Open terminal**. A failed or timed-out start requires **Refresh status** before
30
64
  another attempt, because the launch may have succeeded before the reply was
@@ -70,6 +104,28 @@ The installed CLI must advertise `session-start`; remote starting also needs
70
104
  the remote operation. The execution host checks the actual saved session
71
105
  before launch. Desktop does not scaffold a home or execute a launcher itself.
72
106
 
107
+ A start that worked answers the kernel's result, whole. A failed start answers
108
+ `{error, code}`: the kernel's message and its code. When
109
+ the code is `E_SPAWN_INCOMPLETE` and its details hold a launch-prompt outcome
110
+ for the instance the route resolved, the answer also carries `incomplete`: the
111
+ details decoded by `retainedSpawnDetails`
112
+ (`packages/client/launch-prompt-outcome.mjs`), the same projection a spawn's
113
+ retained result uses. It is decoded again on the way to the dialog by the two
114
+ places that list the keys an error carries (`apiJson` and `httpError` in
115
+ `renderer/views/common.mjs`), and kept only beside that code.
116
+
117
+ In the app, main's `api` proxy waits 70 seconds for a start or a restart (the
118
+ route class `instance-start` of `api-url.mjs`, answered for exactly the paths
119
+ the server routes as one), where an ordinary read has 20. The kernel may watch
120
+ a launch prompt for 30 seconds before it answers what it kept, and the CLI call
121
+ has its own limit (`cliStart`, 60 seconds): the proxy must outlast that call,
122
+ and a test holds the two together, so the dialog shows the kernel's outcome, or
123
+ the CLI's own timeout, and never the proxy's.
124
+
125
+ A client never ends a start. The route awaits the CLI call whatever becomes of
126
+ its request: when the proxy gives up, or a window closes, the call runs to its
127
+ own end and the route goes on after it. Only the call's own limit ends it.
128
+
73
129
  Status collection reads each instance's recorded tmux socket and session,
74
130
  with one query per socket per collection. A launcher shell with a harness
75
131
  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
 
@@ -327,8 +389,10 @@ operation, a retire or a trigger is given (`OATS_CAPABILITY`, `OATS_LAYER`,
327
389
  `OATS_TRIGGER_EVENT_FILE`, `OATS_TEST_LOGIN_SHELL` (a test seam that replaces
328
390
  the login shell, honoured only for a process whose `HOME` is not your home
329
391
  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
392
+ `OATS_TEST_WORKTREE_HOOK_TIMEOUT_MS`, `OATS_TEST_WORKTREE_FETCH_TIMEOUT_MS`,
393
+ `OATS_TEST_PROCESS_START_PS` (below), `OATS_TEST_CGROUP` and
394
+ `OATS_TEST_SYSTEM_TOOL_DIRS` (test seams of the server's
395
+ [own scope](#a-server-started-from-inside-a-systemd-service)), a `worktree` hook's tree
332
396
  (`OATS_TREE`, `OATS_TREE_CLONE`, `OATS_TREE_REMOTE`, `OATS_TREE_MEMBER`,
333
397
  `OATS_TREE_BASE`, `OATS_TREE_BASE_OID`, `OATS_PURPOSE`, `OATS_TREE_ORIGIN`), `OATS_TEAM_NAME`, `OATS_TEAM_SCOPE`,
334
398
  `OATS_TEAM_ID`, `OATS_TEAM_LABEL`, `OATS_TEAM_LABELS`, `OATS_TEAMS`,
@@ -346,8 +410,11 @@ positive whole number of milliseconds replaces the fixed 30-minute timeout of
346
410
  tests can reach it. `OATS_TEST_WORKTREE_FETCH_TIMEOUT_MS` does the same for the
347
411
  10-minute fetch of `oats worktree add`. `OATS_TEST_PROCESS_START_PS=1` makes
348
412
  the kernel read a process's start time with `ps`, as on a host without
349
- `/proc` (macOS), on a host that has it. A launch configuration cannot set
350
- any of them. Do not set them in a deployment.
413
+ `/proc` (macOS), on a host that has it; an absolute path instead runs that
414
+ file as `ps`, directly and in the same fixed environment; any other value
415
+ reads no start at all. That `ps` is asked for the start and the state in one
416
+ call (`-o lstart= -o stat= -p <pid>`); a file that answers the start alone
417
+ 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.
351
418
 
352
419
  **An instance creates an agents' session or window without its own
353
420
  environment.** Nothing of an instance's environment reaches a server or a
@@ -616,43 +683,54 @@ starts in place. It never escalates: a harness still running is reported
616
683
 
617
684
  ### Launch prompt outcomes
618
685
 
619
- For a home with [explicit host-local consent](configuration.md#exact-home-launch-prompt-consent),
620
- spawn, start and restart can observe only the process created by that invocation.
621
- A new window supplies the exact pane identity. Reusing a pane requires a changed
622
- numeric process ID and fresh visible bytes differing from the pre-respawn
623
- screen. An already-running process, stale screen or scrollback grants no input
624
- authority. Home, socket, pane, PID, geometry and exact visible signature are
625
- rechecked before each key.
626
-
627
- Observation is bounded to 30 seconds with 100 ms intervals. Only accepted
628
- version/platform-specific startup and prompt frames keep authority open;
629
- unexpected output permanently closes it. Only the exact aweb development-channel
630
- confirmation can be answered, once, with one Enter. Folder-trust and API-key
631
- prompts are unexpected and block; no multi-prompt sequence is authorized.
632
- For a qualified launch, the controller saves the exclusively owned window's
633
- size policy and dimensions, temporarily pins it to the fixture's 110x35
634
- geometry, and confirms the size before matching. It audits restoration on
635
- every exit, including timeout and failure; a replaced process/window is never
636
- resized during cleanup. Pinning a reused pane cannot establish freshness: that
637
- must already be proved at its original geometry. The selected-option frame
638
- is rechecked before Enter. Uncertain submission is never retried. Only the
639
- qualified Claude executable/platform/geometry in
640
- [configuration](configuration.md#exact-home-launch-prompt-consent) has an enabled
641
- development-channel fixture. Installed version alone grants no match. Ordinary
642
- `session input` and wake delivery do not enter this controller.
686
+ When a spawn, start or restart launches Claude with
687
+ `--dangerously-load-development-channels plugin:aweb-channel@awebai-marketplace`
688
+ ([configuration](configuration.md#the-development-channel-confirmation)), the
689
+ launcher observes only the process created by that invocation. A new window
690
+ supplies the exact pane identity. Reusing a pane requires a changed numeric
691
+ process ID and fresh visible bytes differing from the pre-respawn screen, at the
692
+ pane's original size: a resize could reflow the old prompt into a match. An
693
+ already-running process, stale screen or scrollback grants no input authority.
694
+ Home, socket, pane and PID are rechecked before the key, and the screen is
695
+ captured twice, identical, around the durable intent.
696
+
697
+ Observation is bounded to 30 seconds with 100 ms intervals. A blank screen, or
698
+ one that keeps changing (a prompt still being painted), keeps observing. Only a
699
+ screen whose normalized text equals a tolerance entry can be answered, once,
700
+ with one Enter. A screen with a notice block (a maximal run of rows that begin
701
+ with `▎`, each row's `▎` dropped, then the same normalization) that equals a
702
+ `flag-ignored` entry, on a screen with no question marker, means Claude ignored
703
+ the flag and shows no confirmation: the start ends `flag-ignored`, reason `channels-unavailable`, with no key, and
704
+ succeeds. An unknown screen that holds still for the settle window (`SETTLE`,
705
+ 2 s; a transient frame Claude paints while starting is waited out) permanently
706
+ closes authority with `blocked: unexpected prompt`. The last unknown screen when
707
+ the bound is reached, still changing, closes it with `blocked: observation
708
+ timeout` (with `differed` and that screen as evidence; no prompt was
709
+ established). When either screen starts with Claude's
710
+ running-session banner (`Claude Code v<semver>`, after only the logo's block
711
+ elements U+2580–U+259F and spaces), the result carries
712
+ `claudeSessionShown: true`. A screen blank for the whole bound also reports
713
+ `blocked: observation timeout`. Folder-trust and API-key prompts
714
+ are unexpected and block; no multi-prompt sequence is authorized. The controller
715
+ never resizes the pane. Uncertain submission is never retried. Ordinary
716
+ `session input` and wake delivery do not enter this controller. A launch with any
717
+ other argv records `launchPrompts: {status: "not-engaged", startId, at}` and
718
+ captures nothing.
643
719
 
644
720
  Both spawn and start return `E_SPAWN_INCOMPLETE` for retained prompt failures.
645
721
  With `launchPrompts.status` set to `blocked`, the home, actual terminal target,
646
- provider effects and committed parent lineage are retained. Only an opted-in
647
- launch commits a new parent link before dispatch; ordinary launches keep their
648
- post-launch lineage commit and compensate a failed anchor write. That preserves
649
- timing, not overwrite behavior: even non-opted-in parent spawns now refuse an
722
+ provider effects and committed parent lineage are retained. Only a launch that
723
+ engages the confirmation commits a new parent link before dispatch; other launches
724
+ keep their post-launch lineage commit and compensate a failed anchor write. That
725
+ preserves timing, not overwrite behavior: every parent spawn refuses an
650
726
  anchor edited or removed since the original pre-hook snapshot, instead of
651
727
  replacing concurrent changes with stale metadata. `launchPrompts` records `status`,
652
- `answers`, `reason` and event `receipt`; unknown prompts use
653
- `blocked: unexpected prompt`. Status `incomplete` means the audit could not be
654
- completed, including a possible key followed by an audit failure or failure to
655
- retain mandatory structural-completion evidence. It is
728
+ `answers`, `reason` and event `receipt`, and a blocked result `differed`; unknown
729
+ prompts use `blocked: unexpected prompt`. Status `incomplete` means the audit could
730
+ not be completed, including a possible key followed by an audit failure or failure
731
+ to retain completion evidence. No complete clean `SETTLE` window (2 s) within the
732
+ bound after the Enter is `blocked: observation timeout`, with the one Enter in the
733
+ answers. It is
656
734
  not proof that no input was sent. Both outcomes record `launched:false` while
657
735
  retaining the real process/endpoint for inspection: this is never permission
658
736
  to allocate another harness.
@@ -670,28 +748,26 @@ prior evidence, and adds `{ok:false, results:[]}` to the receipt array. That
670
748
  entry means zero audit destinations were attempted, not a successful write.
671
749
  No audit or metadata write is directed into the replacement home.
672
750
 
673
- A blocked result can follow a successfully submitted Enter. The accepted
674
- completion families cover exact installed-plugin and plugin-absent banners,
675
- plus source-derived billing-only variants of those empty frames (Max, Pro,
676
- Team and Enterprise), and source-derived empty Max/bypass/medium frames.
677
- Other model, billing, effort or permission text can leave the pane active while
678
- reporting a retained block. Inspect `answers` and the event receipts; never infer
679
- that nothing started or nothing was answered. See the
680
- [completion limitation](configuration.md#exact-home-launch-prompt-consent).
751
+ A blocked result can follow a successfully submitted Enter: a question marker
752
+ after it, or the confirmation coming back, leaves the pane active while reporting
753
+ a retained block. Inspect `answers` and the event receipts; never infer that
754
+ nothing started or nothing was answered. See the
755
+ [completion rule](launch-prompt-completion.md).
681
756
 
682
757
  ### Private unmatched launch evidence
683
758
 
684
- This section also covers mandatory structural-completion evidence.
759
+ This section also covers mandatory completion evidence.
685
760
 
686
- After a submitted launch answer, an unmatched 110x35 frame is retained locally
687
- at `<home>/.oats/launch-prompt-evidence/<sha256(startId)>/frame.txt`, with
761
+ The screen of a miss (`blocked: unexpected prompt`, before or after the Enter, or
762
+ `blocked: repeated or unsupported prompt`) is retained locally at
763
+ `<home>/.oats/launch-prompt-evidence/<sha256(startId)>/frame.txt`, with
688
764
  `receipt.json` published last. This is the exact UTF-8 text already compared by
689
765
  the controller, including whitespace and final newline, not a later recapture.
690
- It is bounded to 64 KiB and 35 rows. There is no new input, observation, retry,
691
- geometry change or readiness claim. Evidence is also mandatory when the post-answer
692
- [structural completion rule](launch-prompt-completion.md) selects completion.
693
- Previously qualified exact completion does not acquire that requirement. No
694
- frame is saved before a submitted answer or for unrelated blocked reasons.
766
+ It is bounded to 64 KiB, with one row per pane row at the pane's own size. There
767
+ is no new input, observation, retry, geometry change or readiness claim. Evidence
768
+ is also mandatory when the post-answer [completion rule](launch-prompt-completion.md)
769
+ reports completion. No frame is saved for unrelated blocked reasons (ownership,
770
+ timeouts, capture failures).
695
771
 
696
772
  Find the invocation's existing `launch-prompt` event in the home's
697
773
  `.oats-events.jsonl` (or the checked event rows in `launchPrompts.receipt`). Its
@@ -710,9 +786,12 @@ means no independent capture timestamp was recorded. It does not substitute an
710
786
  event timestamp for capture time. Same-uid concurrent mutation between checks is
711
787
  not excluded.
712
788
 
713
- Private receipt version 2 uses `kind:"launch-prompt-frame"` and admits only
714
- `outcome:"blocked", recognition:"unmatched"` or
715
- `outcome:"completed", recognition:"structural"`. These fields describe the
789
+ Private receipt version 2 uses `kind:"launch-prompt-frame"`. This kernel writes
790
+ only `outcome:"blocked", recognition:"unmatched"`,
791
+ `outcome:"completed", recognition:"stable-screen"` or
792
+ `outcome:"flag-ignored", recognition:"notice-block"`; readers also accept
793
+ `outcome:"completed", recognition:"structural"`, written by kernels 0.47–0.51 for
794
+ completion recognized by Claude's footer structure. These fields describe the
716
795
  recognition whose frame was saved, not the final public launch result: a later
717
796
  audit or cleanup failure can still report `incomplete`. Historical version 1
718
797
  receipts with `kind:"launch-prompt-unmatched"` describe blocked/unmatched
@@ -734,11 +813,12 @@ and adds only `; private launch evidence retention failed` to its diagnostic
734
813
  reason. Already published files may remain, including a receipt if a later
735
814
  verification fails; their presence alone is not a success claim. The submitted
736
815
  answer is preserved. Existing event-audit failures still report `incomplete`.
737
- A structural-completion save failure instead reports checked `incomplete` with
816
+ A completion save failure instead reports checked `incomplete` with
738
817
  `private launch evidence retention failed`, preserving the submitted answer and
739
818
  retained target. It never retries publication or input. An audit failure remains
740
819
  incomplete even if private evidence was saved. No public result or event contains
741
- the raw screen or private receipt.
820
+ the raw screen or private receipt; a miss's `differed` carries at most 40
821
+ characters of the normalized screen at its first difference.
742
822
 
743
823
  The frame can contain private task or account text. It stays on this host with
744
824
  no automatic transmission or expiry. Preserve needed evidence privately before
@@ -769,7 +849,11 @@ SIGTERM. Restart the instance later with `oats session start` or
769
849
  `oats session restart`. An instance whose recorded tmux socket file is
770
850
  missing while a process works in its home, or the process scan cannot run,
771
851
  is not reported idle: its result is `E_SESSION_UNAVAILABLE` and nothing is
772
- stopped ([missing socket file](#missing-socket)).
852
+ stopped ([missing socket file](#missing-socket)). A stop apply holds the
853
+ claim of every instance it stops, the one a retire holds (OATS 0.52.0): one
854
+ that meets a retire of any of them answers `E_INSTANCE_RETIRING`, one that
855
+ meets another stop `E_LIFECYCLE_BUSY`, before anything is stopped
856
+ ([the table](desktop-cli-api.md#lifecycle-pairs)).
773
857
 
774
858
  ### Inspect, input and attach
775
859
 
@@ -777,6 +861,7 @@ stopped ([missing socket file](#missing-socket)).
777
861
  oats session inspect --home /abs/home --json
778
862
  oats session input --home /abs/home --text-file message.txt --json
779
863
  oats session attach --home /abs/home
864
+ oats session attach --home /abs/home --detach-key 'C-\'
780
865
  ```
781
866
 
782
867
  - **inspect** reports `backend`, `present` and `state`: `unknown` for a live
@@ -826,6 +911,89 @@ oats session attach --home /abs/home
826
911
  session linked to the agent's window alone.
827
912
  Closing the viewer leaves the agent running.
828
913
 
914
+ **Leaving the viewer.** Without `--detach-key` there is no keyboard exit:
915
+ every key goes to the agent, the tmux prefix included. Close the terminal.
916
+ With `--detach-key <key>` (`--detach-key=<key>` is the same; feature
917
+ `session-attach-detach-key`, OATS 0.51.0), pressing `<key>` detaches that
918
+ viewer's client. The agent's window and every other viewer are untouched.
919
+ The key is taken from the agent's input: the agent never receives it while
920
+ this viewer is attached. A keyed viewer reads a tmux key table of its own,
921
+ named as its temporary session and removed with it, so the key is bound
922
+ for that viewer alone. Check the feature in `oats version --json` before
923
+ passing the flag: a kernel without it ignores the flag and opens a viewer
924
+ with no exit.
925
+
926
+ The key is one of these, spelled exactly (case-sensitive):
927
+
928
+ ```
929
+ key = control / meta / function
930
+ control = "C-" ( "a"-"g" / "j"-"l" / "n"-"z" / "\" / "]" / "^" / "_" )
931
+ meta = "M-" ( "a"-"z" / "0"-"9" )
932
+ function = [ "C-" / "M-" / "S-" ] "F" ( "1" … "12" )
933
+ ```
934
+
935
+ Anything else is `E_BAD_ARGS`, before any tmux or ssh call: a missing
936
+ value, a plain character, `C-i` and `C-m` (Tab and Enter on tmux before
937
+ 3.5), `C-h` (the byte, 0x08, that many terminals send for Ctrl+Backspace
938
+ and some for Backspace, so the name is not one key everywhere), `C-[`
939
+ (Escape), `M-[`, `M-]`, `M-\`, `M-O` and the other ESC + C1 introducers (a
940
+ terminal reply can arrive as that key), `Any`, mouse key names, two keys,
941
+ upper case, and anything with a space, `;` or a control character. The
942
+ kernel does not judge whether a harness reads the key: that is the
943
+ caller's choice.
944
+
945
+ **While the pane is scrolled back.** The viewer's wheel and drag bindings
946
+ put the pane in tmux's copy mode, and there copy mode's key table is read
947
+ before the viewer's. A detach key that copy mode binds acts in copy mode
948
+ and does not detach; it detaches once the mode is left (`q`, or scrolling
949
+ back to the bottom). The grammar does not exclude those keys. The
950
+ copy-mode tables are the tmux server's, shared by every session and
951
+ changed by the operator's `~/.tmux.conf`, so no grammar can promise a key
952
+ is free there, and the kernel never binds a detach key in a table other
953
+ sessions read. With tmux's default tables (3.7c), 35 of the 111 keys are
954
+ taken in emacs or vi copy mode (for example `C-e`, `C-c`, `M-w`, `C-u`);
955
+ `C-\` and `F12` are bound in neither and detach from copy mode. Detaching
956
+ while scrolled back leaves the agent's pane in copy mode for the next
957
+ viewer, as closing a viewer mid-scroll does.
958
+
959
+ **The suggested key is `C-\`**, written `--detach-key 'C-\'` (quoted: an
960
+ unquoted trailing backslash continues the line). The kernel fixes no key.
961
+ What was checked:
962
+
963
+ - It has no default binding in Claude Code 2.1.288 (which refuses to let
964
+ a user bind it: "terminal quit signal"), Codex CLI 0.160.0 or pi 1.0.2.
965
+ It is unbound in bash 5.3 (`bind -p`) and in zsh's and fish's documented
966
+ defaults. It is the default detach key of dtach and abduco.
967
+ - A viewer with this key gives up: in a fallback shell, the tty's QUIT (no
968
+ SIGQUIT from the keyboard); in vim and nvim, the `C-\ C-n` prefix; in
969
+ nano, Replace (also on `M-r`).
970
+ - On a layout where `\` needs AltGr, use `F12`: it has no default binding
971
+ in the same three harnesses, bash, nvim or less. Some terminals and
972
+ laptops keep F12 for themselves.
973
+ - `C-]`, `C-_`, `C-g`, `C-t` and `C-b` are each bound by all three
974
+ harnesses.
975
+
976
+ **Exit status.**
977
+
978
+ | How the command ended | Status |
979
+ |---|---|
980
+ | Left by the detach key (the agent keeps running) | 20 |
981
+ | The viewer ended without the key: the agent's window ended, or `oats` itself was stopped by SIGHUP, SIGTERM or SIGINT and closed the viewer | 0 |
982
+ | A refusal (bad arguments, not launched, session gone), or tmux failing under the viewer (its server exited) | 1 |
983
+
984
+ 20 is answered only when the key's own binding ran, and only by a kernel
985
+ with the feature. No status an existing caller sees changes meaning. 20 is
986
+ nonzero, so `set -e`, an `&&` chain and tmux's `remain-on-exit failed`
987
+ treat a leave by the key as a failure. The routed form (`--server`) relays
988
+ these statuses and adds ssh's own 255 ([servers.md](servers.md#run-there)).
989
+
990
+ With `--detach-key`, `oats` handles SIGQUIT. `C-\` is also the terminal's
991
+ QUIT character: pressed before the viewer has the terminal, or again once
992
+ the viewer has given it back, it would otherwise end `oats` with status 131
993
+ and leave the viewer's session and key table on the tmux server. A QUIT
994
+ that arrives before the key was used stops the attach, with status 1;
995
+ after a leave by the key it changes nothing, and the status is 20.
996
+
829
997
  ### Attachments
830
998
 
831
999
  `oats session upload --file <local> --home <abs>` copies a file into
@@ -877,7 +1045,10 @@ Unattended execution never implies yolo.
877
1045
  ### Explicit deployment trust
878
1046
 
879
1047
  Use `oats harness trust --dir <deployment> --harness claude|codex|all --plan`,
880
- then the same command without `--plan`, on the execution host. This is the explicit
1048
+ then the same command without `--plan`, on the execution host. It covers the ambient
1049
+ configuration file and each launch configuration's `CLAUDE_CONFIG_DIR` /
1050
+ `CODEX_HOME`; launch-time checks read the file the launch's own environment
1051
+ selects. This is the explicit
881
1052
  operator-only native-config write path; spawn/start/retire remain read-only with
882
1053
  respect to native trust. See [native trust](harness-trust.md) for qualified formats,
883
1054
  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.