@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.
- package/README.md +3 -1
- package/bin/oats.mjs +407 -123
- package/docs/capabilities.md +75 -6
- package/docs/configuration.md +200 -91
- package/docs/desktop-cli-api.md +1563 -113
- package/docs/desktop-instance-start.md +69 -0
- package/docs/desktop.md +10 -7
- package/docs/execution-targets.md +145 -58
- package/docs/first-team.md +3 -1
- package/docs/harness-trust.md +50 -2
- package/docs/implementation.md +238 -17
- package/docs/integrations.md +13 -9
- package/docs/knowledge-reference/acceptance.md +1 -0
- package/docs/knowledge-reference/harvester.md +5 -3
- package/docs/knowledge-reference/model.md +5 -3
- package/docs/knowledge-theory.md +1 -1
- package/docs/knowledge.md +25 -2
- package/docs/launch-prompt-completion.md +50 -48
- package/docs/macos-test-runs.md +246 -0
- package/docs/oats-local.schema.json +4 -3
- package/docs/official-catalog.md +5 -5
- package/docs/packages.md +14 -14
- package/docs/release-lane.md +225 -11
- package/docs/release-notes/v0.44.0.md +1 -1
- package/docs/release-notes/v0.52.0.md +933 -0
- package/docs/release-notes/v0.53.0.md +1274 -0
- package/docs/schedules.md +97 -4
- package/docs/souls-and-instances.md +332 -40
- package/docs/tui.md +584 -0
- package/docs/upgrading.md +298 -0
- package/docs/workspaces.md +3 -3
- package/lib/automations.mjs +22 -22
- package/lib/claim.mjs +278 -49
- package/lib/config-data.mjs +4 -1
- package/lib/core.mjs +1282 -289
- package/lib/errors.mjs +170 -0
- package/lib/harness-trust-write.mjs +68 -27
- package/lib/harness-trust.mjs +34 -16
- package/lib/instance-events.mjs +19 -1
- package/lib/instance-git.mjs +39 -3
- package/lib/instance-inspect.mjs +45 -17
- package/lib/instance-lifecycle.mjs +306 -57
- package/lib/instance-resolution.mjs +59 -6
- package/lib/launch-preference.mjs +236 -9
- package/lib/launch-prompt-completion.mjs +7 -43
- package/lib/launch-prompt-evidence.mjs +14 -7
- package/lib/launch-prompt-fixtures/README.md +86 -152
- package/lib/launch-prompt-fixtures/dev-channel-confirmation.json +50 -0
- package/lib/launch-prompt-fixtures.mjs +122 -109
- package/lib/launch-prompt-transport.mjs +2 -56
- package/lib/launch-prompts.mjs +102 -100
- package/lib/local-edit.mjs +118 -0
- package/lib/packages.mjs +13 -4
- package/lib/pi-bridge.mjs +308 -0
- package/lib/refused-text.mjs +11 -0
- package/lib/remote.mjs +190 -25
- package/lib/resolve.mjs +2 -1
- package/lib/retained-after-retire.mjs +2 -2
- package/lib/retire-output.mjs +12 -1
- package/lib/schedule-host.mjs +125 -22
- package/lib/schedule.mjs +73 -24
- package/lib/shell-word.mjs +13 -0
- package/lib/soul-launch-verbs.mjs +153 -0
- package/lib/stable-node.mjs +62 -0
- package/lib/system-tools.mjs +39 -0
- package/lib/teams-verbs.mjs +18 -46
- package/lib/tmux-server-scope.mjs +62 -0
- package/lib/triggers.mjs +4 -4
- package/lib/workspace.mjs +54 -30
- package/lib/worktree-hooks.mjs +98 -20
- package/lib/worktree.mjs +83 -24
- package/package-catalog.json +4 -4
- package/package.json +8 -2
- package/packages/client/attach-exit.mjs +25 -0
- package/packages/client/capability-show-contract.mjs +230 -0
- package/packages/client/capability-warnings-contract.mjs +57 -0
- package/packages/client/cli-adapter.mjs +561 -0
- package/packages/client/cli-environment.mjs +53 -0
- package/packages/client/cli-locator.mjs +253 -0
- package/packages/client/cli-probe-contract.mjs +47 -0
- package/packages/client/client-terms.mjs +60 -0
- package/packages/client/deployment-contract.mjs +72 -0
- package/packages/client/deployment-data.mjs +483 -0
- package/packages/client/deployment-facts.mjs +95 -0
- package/packages/client/deployment-label.mjs +76 -0
- package/packages/client/deployment-observer.mjs +89 -0
- package/packages/client/deployment-panel.mjs +180 -0
- package/packages/client/deployment-read-cli.mjs +57 -0
- package/packages/client/display-text.mjs +50 -0
- package/packages/client/harness-names.mjs +30 -0
- package/packages/client/inspect-contract.mjs +62 -0
- package/packages/client/instance-acts.mjs +90 -0
- package/packages/client/instance-admission.mjs +45 -0
- package/packages/client/instance-events-contract.mjs +76 -0
- package/packages/client/instance-git-contract.mjs +80 -0
- package/packages/client/instance-presentation.mjs +86 -0
- package/packages/client/instance-tree.mjs +462 -0
- package/packages/client/kernel-environment.mjs +11 -0
- package/packages/client/kernel-lines.mjs +31 -0
- package/packages/client/kernel-made.mjs +23 -0
- package/packages/client/launch-contract.mjs +51 -0
- package/packages/client/launch-prompt-outcome.mjs +200 -0
- package/packages/client/lifecycle-cli.mjs +61 -0
- package/packages/client/lifecycle-contract.mjs +413 -0
- package/packages/client/liveness-main.mjs +10 -0
- package/packages/client/liveness.mjs +48 -0
- package/packages/client/machine-contract.mjs +123 -0
- package/packages/client/own-codes.mjs +31 -0
- package/packages/client/own-environment.mjs +22 -0
- package/packages/client/panel-views.mjs +293 -0
- package/packages/client/readiness-contract.mjs +174 -0
- package/packages/client/refresh-loop.mjs +52 -0
- package/packages/client/remote-address.mjs +151 -0
- package/packages/client/remote-identity-memory.mjs +94 -0
- package/packages/client/remote-roster.mjs +153 -0
- package/packages/client/roster-sections.mjs +80 -0
- package/packages/client/session-attach.mjs +175 -0
- package/packages/client/spawn-apply-cli.mjs +104 -0
- package/packages/client/spawn-apply-contract.mjs +195 -0
- package/packages/client/spawn-decision.mjs +46 -0
- package/packages/client/spawn-messages.mjs +142 -0
- package/packages/client/spawn-preview-cli.mjs +38 -0
- package/packages/client/spawn-preview-contract.mjs +318 -0
- package/packages/client/team-members.mjs +41 -0
- package/packages/client/team-rows.mjs +45 -0
- package/packages/client/terminal-contract.mjs +57 -0
- package/packages/client/terminal-exec.mjs +21 -0
- package/packages/client/tmux-status.mjs +66 -0
- package/packages/client/waiting-on-you.mjs +88 -0
- package/packages/client/workspace-admission.mjs +45 -0
- package/packages/client/workspace-choices.mjs +95 -0
- package/packages/client/workspace-cli.mjs +142 -0
- package/packages/client/workspace-views.mjs +183 -0
- package/packages/record/README.md +21 -0
- package/packages/record/bin/setup.mjs +108 -15
- package/packages/tui/README.md +64 -0
- package/packages/tui/bin/tui.mjs +7 -0
- package/packages/tui/lib/actions.mjs +44 -0
- package/packages/tui/lib/client.mjs +35 -0
- package/packages/tui/lib/config.mjs +151 -0
- package/packages/tui/lib/main.mjs +176 -0
- package/packages/tui/lib/model.mjs +392 -0
- package/packages/tui/lib/read.mjs +473 -0
- package/packages/tui/lib/store.mjs +364 -0
- package/packages/tui/lib/term/keys.mjs +367 -0
- package/packages/tui/lib/term/screen.mjs +134 -0
- package/packages/tui/lib/term/style.mjs +43 -0
- package/packages/tui/lib/term/text.mjs +109 -0
- package/packages/tui/lib/term/tty.mjs +178 -0
- package/packages/tui/lib/term/width.mjs +124 -0
- package/packages/tui/lib/views/detail.mjs +46 -0
- package/packages/tui/lib/views/frame.mjs +256 -0
- package/packages/tui/lib/views/help.mjs +140 -0
- package/packages/tui/lib/views/instances.mjs +137 -0
- package/packages/tui/lib/views/scroll.mjs +19 -0
- package/packages/tui/lib/views/switcher.mjs +97 -0
- package/packages/tui/package.json +8 -0
- package/skills/oats-getting-started/SKILL.md +30 -23
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +0 -77
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/max-bypass-source.json +0 -88
- package/lib/launch-prompt-fixtures/structural-completion.json +0 -205
- 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
|
|
505
|
-
node-pty ABI + a headless run of the bundled backend
|
|
506
|
-
collector from `app.asar
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
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
|
-
|
|
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.
|
|
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
|
-
|
|
621
|
-
|
|
622
|
-
|
|
623
|
-
|
|
624
|
-
|
|
625
|
-
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
|
|
629
|
-
|
|
630
|
-
|
|
631
|
-
|
|
632
|
-
|
|
633
|
-
|
|
634
|
-
|
|
635
|
-
|
|
636
|
-
|
|
637
|
-
|
|
638
|
-
|
|
639
|
-
|
|
640
|
-
|
|
641
|
-
|
|
642
|
-
|
|
643
|
-
|
|
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
|
|
648
|
-
|
|
649
|
-
post-launch lineage commit and compensate a failed anchor write. That
|
|
650
|
-
timing, not overwrite behavior:
|
|
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
|
|
654
|
-
`blocked: unexpected prompt`. Status `incomplete` means the audit could
|
|
655
|
-
completed, including a possible key followed by an audit failure or failure
|
|
656
|
-
retain
|
|
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
|
|
675
|
-
|
|
676
|
-
|
|
677
|
-
|
|
678
|
-
|
|
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
|
|
760
|
+
This section also covers mandatory completion evidence.
|
|
686
761
|
|
|
687
|
-
|
|
688
|
-
|
|
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
|
|
692
|
-
geometry change or readiness claim. Evidence
|
|
693
|
-
[
|
|
694
|
-
|
|
695
|
-
|
|
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"
|
|
715
|
-
`outcome:"blocked", recognition:"unmatched"
|
|
716
|
-
`outcome:"completed", recognition:"
|
|
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
|
|
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.
|
|
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
|
package/docs/first-team.md
CHANGED
|
@@ -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.
|
|
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
|
|
package/docs/harness-trust.md
CHANGED
|
@@ -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
|
-
|
|
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.
|