@awebai/oats 0.55.1 → 0.57.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/bin/oats.mjs +96 -72
- package/docs/capabilities.md +67 -3
- package/docs/design/2026-09-23-workspace-module-contracts.md +27 -3
- package/docs/desktop-cli-api.md +375 -37
- package/docs/desktop-instance-start.md +105 -12
- package/docs/desktop.md +65 -11
- package/docs/execution-targets.md +184 -9
- package/docs/harness-trust.md +128 -11
- package/docs/implementation.md +153 -11
- package/docs/integrations.md +5 -3
- package/docs/knowledge.md +117 -43
- package/docs/official-catalog.md +3 -3
- package/docs/packages.md +12 -12
- package/docs/release-lane.md +26 -1
- package/docs/release-notes/v0.56.0.md +699 -0
- package/docs/release-notes/v0.57.0.md +283 -0
- package/docs/schedules.md +8 -3
- package/docs/servers.md +21 -5
- package/docs/souls-and-instances.md +134 -19
- package/docs/tui.md +215 -31
- package/docs/upgrading.md +4 -1
- package/docs/workspaces.md +26 -6
- package/lib/automations.mjs +3 -4
- package/lib/bounded-read.mjs +18 -0
- package/lib/capability-show.mjs +13 -2
- package/lib/claim.mjs +3 -4
- package/lib/core.mjs +919 -278
- package/lib/errors.mjs +39 -0
- package/lib/harness-trust-write.mjs +119 -40
- package/lib/harness-trust.mjs +31 -18
- package/lib/instance-inspect.mjs +160 -11
- package/lib/instance-lifecycle.mjs +90 -37
- package/lib/packages.mjs +8 -5
- package/lib/pi-bridge.mjs +18 -19
- package/lib/remote.mjs +88 -51
- package/lib/retire-output.mjs +9 -4
- package/lib/schedule.mjs +3 -4
- package/lib/servers.mjs +39 -6
- package/lib/session-viewer.mjs +25 -1
- package/lib/triggers.mjs +3 -4
- package/lib/workspace.mjs +6 -6
- package/lib/worktree.mjs +33 -8
- package/lib/write-through-private-file.mjs +26 -0
- package/package-catalog.json +2 -2
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +108 -13
- package/packages/client/cli-locator.mjs +16 -14
- package/packages/client/deployment-panel.mjs +4 -3
- package/packages/client/display-text.mjs +2 -1
- package/packages/client/instance-events-contract.mjs +4 -3
- package/packages/client/instance-lifecycle.mjs +235 -0
- package/packages/client/instance-presentation.mjs +9 -0
- package/packages/client/instance-tree.mjs +10 -8
- package/packages/client/kernel-lines.mjs +3 -3
- package/packages/client/launch-contract.mjs +11 -0
- package/packages/client/launch-prompt-outcome.mjs +1 -1
- package/packages/client/lifecycle-cli.mjs +12 -6
- package/packages/client/lifecycle-confirmation.mjs +407 -0
- package/packages/client/lifecycle-contract.mjs +6 -2
- package/packages/client/own-codes.mjs +1 -0
- package/packages/client/panel-views.mjs +39 -2
- package/packages/client/readiness-contract.mjs +2 -2
- package/packages/client/remote-roster.mjs +50 -5
- package/packages/client/roster-sections.mjs +3 -3
- package/packages/client/session-start.mjs +98 -0
- package/packages/client/start-gate.mjs +46 -0
- package/packages/client/start-messages.mjs +17 -0
- package/packages/client/workspace-views.mjs +2 -2
- package/packages/tui/README.md +21 -8
- package/packages/tui/lib/actions.mjs +11 -2
- package/packages/tui/lib/client.mjs +9 -2
- package/packages/tui/lib/config.mjs +39 -9
- package/packages/tui/lib/main.mjs +168 -20
- package/packages/tui/lib/model.mjs +315 -13
- package/packages/tui/lib/open.mjs +45 -0
- package/packages/tui/lib/read.mjs +171 -16
- package/packages/tui/lib/store.mjs +171 -10
- package/packages/tui/lib/term/tty.mjs +71 -12
- package/packages/tui/lib/views/act.mjs +85 -0
- package/packages/tui/lib/views/frame.mjs +145 -33
- package/packages/tui/lib/views/help.mjs +46 -11
- package/skills/oats-getting-started/SKILL.md +6 -3
|
@@ -13,6 +13,34 @@ The Start/Restart dialog names the existing instance, harness and host. Choose
|
|
|
13
13
|
a named launch configuration or keep the recorded launch. Without a selected
|
|
14
14
|
configuration, the harness can also be changed directly. A named configuration
|
|
15
15
|
fixes its harness; model and permission choices can override its defaults.
|
|
16
|
+
|
|
17
|
+
The Launch configuration list's second entry is **No launch configuration (the
|
|
18
|
+
harness as installed)**. It asks for the bare harness: the harness itself, with
|
|
19
|
+
no configuration's executable, arguments or environment, and without the
|
|
20
|
+
default configuration the host declares for that harness. The Harness list
|
|
21
|
+
stays usable with it. Alone, with "Keep recorded harness", it starts the
|
|
22
|
+
recorded harness bare; beside a picked harness, that one. It sends the word the
|
|
23
|
+
kernel reads as no configuration, `--launch-config none`, from one constant
|
|
24
|
+
(`LAUNCH_CONFIG_NONE`, `packages/client/launch-contract.mjs`) and never from a
|
|
25
|
+
row of the list: a row whose name is the word, or is not a string at all, is
|
|
26
|
+
not drawn as a configuration. Preview invocation sends the same choice.
|
|
27
|
+
|
|
28
|
+
The entry is offered only where the kernel that would answer the start is
|
|
29
|
+
known to read the word. The server says so in a key of its own on the list
|
|
30
|
+
answer of `POST /api/launch-configs`, `noneKnown`: `launchConfigNoneKnown`
|
|
31
|
+
(the same module) over the answering kernel's own feature list
|
|
32
|
+
(`answeringFeatures`, `packages/client/lifecycle-contract.mjs`). For an
|
|
33
|
+
instance on this computer that is this computer's kernel, which lists
|
|
34
|
+
`launch-config`. For an instance on a server it is the host's list, as the
|
|
35
|
+
roster relays it; a host that reports no list (before 0.49.0), or one this
|
|
36
|
+
computer's CLI does not relay, is unknown, and unknown is not offered. The
|
|
37
|
+
start route adds no refusal of its own for the word: this computer's kernel
|
|
38
|
+
asks the host at the call and sends nothing to one that does not list
|
|
39
|
+
`launch-config`. When the list is read again, the entry stays selected only
|
|
40
|
+
while it is still offered: a save selects the saved configuration, a remove
|
|
41
|
+
the recorded launch, and a read cut short by a start and repeated keeps the
|
|
42
|
+
entry, or falls back to the recorded launch when it is no longer offered.
|
|
43
|
+
|
|
16
44
|
Enter a model or leave the field blank to use the selected launch's default.
|
|
17
45
|
An old harness's model is not carried to a different harness. Available local model
|
|
18
46
|
suggestions are advisory; a model ID can also be typed. Start uses the saved
|
|
@@ -72,6 +100,28 @@ reader into its creation receipt, and the notice is the same
|
|
|
72
100
|
(`packages/desktop/docs/desktop-spawn-preview.md`, A spawn where Claude Code
|
|
73
101
|
ignored the channel option).
|
|
74
102
|
|
|
103
|
+
When OATS refuses a start or a restart with `E_LAUNCH_CONFIG_AMBIGUOUS` (the
|
|
104
|
+
start names a harness and no configuration, several configurations are declared
|
|
105
|
+
for that harness, and none is the default), the dialog says it in its own
|
|
106
|
+
words. Its status reads: "More than one launch configuration is declared for
|
|
107
|
+
the chosen harness, and none is the default. Choose one under Launch
|
|
108
|
+
configuration, or choose "No launch configuration" to run the harness as
|
|
109
|
+
installed." Under it stands OATS's message as one line, "OATS says:
|
|
110
|
+
`<message>`", through the display filter: whole, or "[withheld]" with no
|
|
111
|
+
name before it when the message is withheld, and no line when there is no
|
|
112
|
+
message (`kernelLines`, `packages/client/kernel-lines.mjs`). The message
|
|
113
|
+
quoted is the answer's own (`answered`, set by the page's transport in
|
|
114
|
+
`packages/desktop/renderer/views/common.mjs`), never the transport's stand-in
|
|
115
|
+
for an answer without one, such as "HTTP 409". The
|
|
116
|
+
sentence is chosen by the code alone (`startRefusalSentence`,
|
|
117
|
+
`packages/client/start-messages.mjs`); no part of OATS's message is read to
|
|
118
|
+
choose it. It names the dialog's two controls and no machine, so it is the
|
|
119
|
+
same for an instance on this computer and on a server. A **Preview
|
|
120
|
+
invocation** refused with that code reads the same sentence, then "Preview
|
|
121
|
+
only. No agent was started or stopped.", with OATS's line under it. Every
|
|
122
|
+
other refusal of a start, a restart or a preview reads as before: the answer's
|
|
123
|
+
message as the status.
|
|
124
|
+
|
|
75
125
|
If an ordinary Start dialog finds the instance already running, its action becomes
|
|
76
126
|
**Open terminal**. A failed or timed-out start requires **Refresh status** before
|
|
77
127
|
another attempt, because the launch may have succeeded before the reply was
|
|
@@ -106,19 +156,59 @@ Use the server's workspace to manage configurations defined on that server.
|
|
|
106
156
|
Desktop sends `POST /api/start/<instance>?ws=…&home=…` (and `server=…` for a
|
|
107
157
|
remote instance). The backend resolves that exact roster identity and calls
|
|
108
158
|
`oats session start --home <absolute-home> [--server <id>] [--model <model>] --json`.
|
|
109
|
-
Launch choices add `--launch-config
|
|
159
|
+
Launch choices add `--launch-config` (a configuration's name, or `none` for
|
|
160
|
+
the bare harness), `--harness` or `--yolo`/`--no-yolo`.
|
|
110
161
|
Restart uses `POST /api/restart/<instance>?ws=…&home=…` and the single kernel
|
|
111
162
|
command `oats session restart` with the same selectors and choices.
|
|
112
163
|
Configuration inspection and editing use `POST /api/launch-configs?ws=…`,
|
|
113
|
-
routed through `oats launch-config list/set/remove/preview`.
|
|
164
|
+
routed through `oats launch-config list/set/remove/preview`. A refusal on that
|
|
165
|
+
route answers its code and the first 300 characters of its message; for
|
|
166
|
+
`E_LAUNCH_CONFIG_AMBIGUOUS` alone it answers the display filter's line over
|
|
167
|
+
OATS's message as it came (`displayLine`, `packages/client/display-text.mjs`):
|
|
168
|
+
withheld whole, or folded and bounded at `MAX_DISPLAY_LINE`, so the line the
|
|
169
|
+
dialog shows under its sentence is not cut short and nothing withheld survives
|
|
170
|
+
a cut. It answers an empty message when OATS gave none, never the stand-in text
|
|
171
|
+
a refusal without a message is given. These features
|
|
114
172
|
require the CLI's `launch-config` and `session-restart` capabilities; old
|
|
115
173
|
clients/hosts receive an update explanation instead of unsupported arguments.
|
|
116
174
|
The installed CLI must advertise `session-start`; remote starting also needs
|
|
117
175
|
the remote operation. The execution host checks the actual saved session
|
|
118
176
|
before launch. Desktop does not scaffold a home or execute a launcher itself.
|
|
119
177
|
|
|
120
|
-
|
|
121
|
-
`
|
|
178
|
+
The start rule is decided once, in the shared home
|
|
179
|
+
(`packages/client/session-start.mjs`), and the dialog and the route decide
|
|
180
|
+
through the same gate, so the dialog never sends a start it has refused. The
|
|
181
|
+
route reads the row again and checks the home, which the dialog cannot, so it
|
|
182
|
+
may still refuse one the dialog sent. The gate is a module of its own
|
|
183
|
+
(`start-gate.mjs`, re-exported by `session-start.mjs`) because the dialog's
|
|
184
|
+
page loads no Node builtin. `startGate` gives the first rule that
|
|
185
|
+
refuses a row, in this order, each with its code and sentence: the row is no
|
|
186
|
+
longer in the roster (`not-in-roster`); it is running and this is not a restart
|
|
187
|
+
(`already-running`: the dialog offers Open terminal instead); its state is not
|
|
188
|
+
known stopped and this is not a restart of a running row (`state-unknown`:
|
|
189
|
+
unknown is not stopped); a server's row the kernel does not report addressable
|
|
190
|
+
(`E_SNAPSHOT_UNKNOWN`); no accepted CLI or no `session-start`
|
|
191
|
+
(`cli-unavailable`, `unsupported-start-option`; a server's row:
|
|
192
|
+
`unsupported-remote-operation`); a restart without `session-restart`; a
|
|
193
|
+
launch choice (a configuration, the bare harness's `none` among them, a
|
|
194
|
+
harness or yolo) without `launch-config` (a server's row: also on the host).
|
|
195
|
+
`verifiedLocalHome` is the home check of a row on this computer: the exact
|
|
196
|
+
home its deployment's kernel reported for it, canonicalizing to
|
|
197
|
+
`…/instances/<name>` inside that deployment's canonical directory. `startInstance` runs the gate, the
|
|
198
|
+
home check (`E_HOME_UNVERIFIED`), then the CLI call (`cliStart`, with its wait),
|
|
199
|
+
and says whether the CLI ran. A failed start is `refused`, nothing was
|
|
200
|
+
started: every refusal of the gate and the home check, and the kernel's
|
|
201
|
+
`E_SESSION_START_BUSY` and `E_SESSION_RUNNING` (`STARTED_NOTHING_CODES`); or
|
|
202
|
+
`uncertain`: anything else, `E_START_UNCONFIRMED` included, and `E_CLI_FAILED`
|
|
203
|
+
when the call to the CLI fails on its way. Either way the
|
|
204
|
+
dialog reads the row again before it offers another start. A second client
|
|
205
|
+
takes the rule from the stable surface (`test/client-boundary.test.mjs`); the
|
|
206
|
+
CLI call is not on it.
|
|
207
|
+
|
|
208
|
+
A start that worked answers the kernel's result, whole. A refusal before the
|
|
209
|
+
CLI ran answers `{error, code}`: the rule's sentence and its code. A failed
|
|
210
|
+
start answers `{error, code}`: the kernel's message through the display filter
|
|
211
|
+
(`displayLine`), and its code. When
|
|
122
212
|
the code is `E_SPAWN_INCOMPLETE` and its details hold a launch-prompt outcome
|
|
123
213
|
for the instance the route resolved, the answer also carries `incomplete`: the
|
|
124
214
|
details decoded by `retainedSpawnDetails`
|
|
@@ -130,14 +220,17 @@ places that list the keys an error carries (`apiJson` and `httpError` in
|
|
|
130
220
|
In the app, main's `api` proxy waits 70 seconds for a start or a restart (the
|
|
131
221
|
route class `instance-start` of `api-url.mjs`, answered for exactly the paths
|
|
132
222
|
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
|
|
134
|
-
|
|
135
|
-
and a test holds the two together, so the dialog shows the kernel's
|
|
136
|
-
the
|
|
137
|
-
|
|
138
|
-
A client never ends a start. The
|
|
139
|
-
|
|
140
|
-
|
|
223
|
+
a launch prompt for 30 seconds before it answers what it kept, and the route
|
|
224
|
+
waits 60 seconds for the CLI call (`cliStart`): the proxy must outlast that
|
|
225
|
+
wait, and a test holds the two together, so the dialog shows the kernel's
|
|
226
|
+
outcome, or the end of the wait, and never the proxy's.
|
|
227
|
+
|
|
228
|
+
A client never ends a start. The CLI call runs in a process session of its own
|
|
229
|
+
with no deadline. When the route's wait ends first, it answers
|
|
230
|
+
`E_START_UNCONFIRMED`, and the dialog says, in the Desktop's own words: "OATS
|
|
231
|
+
didn't confirm the start. It may still be running: check the roster before you
|
|
232
|
+
start it again." The start goes on, and the roster shows its result. When the
|
|
233
|
+
proxy gives up, or a window closes, the call runs to its own end.
|
|
141
234
|
|
|
142
235
|
Status collection reads each instance's recorded tmux socket and session,
|
|
143
236
|
with one query per socket per collection. A launcher shell with a harness
|
package/docs/desktop.md
CHANGED
|
@@ -17,6 +17,11 @@ Download the installer for your platform from the
|
|
|
17
17
|
| macOS x64 (Intel) | DMG + ZIP | ad-hoc signed — see below |
|
|
18
18
|
| Linux x64 | AppImage + DEB | requires `tmux` |
|
|
19
19
|
|
|
20
|
+
On Linux the installers need glibc 2.34 or later (for example Ubuntu 22.04,
|
|
21
|
+
Debian 12, RHEL 9 or later). That is what their files ask of the system, read
|
|
22
|
+
from each build, which fails if a file needs more; it is not a list of systems
|
|
23
|
+
the app was tested on.
|
|
24
|
+
|
|
20
25
|
Windows and Linux arm64 are not supported.
|
|
21
26
|
|
|
22
27
|
Verify downloads against the release's `SHA256SUMS.txt`. GitHub
|
|
@@ -219,6 +224,29 @@ more than about a minute is not yet supported from the Desktop; use the CLI on
|
|
|
219
224
|
the server. Every dropdown in the app has the
|
|
220
225
|
same themed look, and its open list follows the light or dark theme.
|
|
221
226
|
|
|
227
|
+
## Stopping and retiring
|
|
228
|
+
|
|
229
|
+
The Desktop runs one stop or retire at a time for its own requests. Another
|
|
230
|
+
program using OATS at the same time, such as the `oats` command or the
|
|
231
|
+
terminal client, is held off by OATS itself: from OATS 0.52.0, a stop and a
|
|
232
|
+
retire of one instance refuse each other before doing anything. A start does
|
|
233
|
+
not yet see a retire in progress.
|
|
234
|
+
|
|
235
|
+
If the Desktop's backend restarts while a confirmation is open, its plan is
|
|
236
|
+
gone: Stop or Retire then answers that the plan expired, and Review again
|
|
237
|
+
reads a new one.
|
|
238
|
+
|
|
239
|
+
A stop, retire or start runs in a process of its own, so closing the Desktop
|
|
240
|
+
does not interrupt it. If a stop or retire takes longer than ten minutes, the
|
|
241
|
+
dialog stops waiting and says the result is not confirmed; it keeps running,
|
|
242
|
+
and Check again reads its result. If a start or restart takes longer than 60
|
|
243
|
+
seconds, the Start dialog stops waiting and says the start is not confirmed;
|
|
244
|
+
the start keeps running, and the roster shows its result.
|
|
245
|
+
|
|
246
|
+
With an OATS older than 0.52.0, after an interrupted stop the instance can be
|
|
247
|
+
started and then cannot be stopped while `.oats-stop-pending.json` exists in
|
|
248
|
+
its home.
|
|
249
|
+
|
|
222
250
|
## One workspace, several machines
|
|
223
251
|
|
|
224
252
|
The switcher lists each workspace once, however many deployments it has: the
|
|
@@ -325,10 +353,17 @@ join** says who else may join it. Both are read from the workspace's committed
|
|
|
325
353
|
`souls:`; a team nobody may join yet says so. The address (the team on the
|
|
326
354
|
messaging provider) and the members running in it follow.
|
|
327
355
|
|
|
328
|
-
The **Setup** tab's List view
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
356
|
+
The **Setup** tab's List view is one column. Under the workspace's name, one
|
|
357
|
+
line counts its members (and those that need attention), its packages and the
|
|
358
|
+
state of the lock. The next line says where the workspace is declared. An
|
|
359
|
+
**Overview** says that the workspace's **host**, the repository that holds
|
|
360
|
+
`oats-workspace.yaml`, defines the workspace: its member repositories and its
|
|
361
|
+
packages. **For developers** (folded) explains how a repository becomes a
|
|
362
|
+
member and what each member state means. Then **Shared through Git** lists
|
|
363
|
+
what the workspace declares (Members, with the host first and tagged
|
|
364
|
+
**Host**, Packages and Defaults). **This computer** lists what is not shared:
|
|
365
|
+
this deployment's settings, lock, CLI and instances, the member clones, and
|
|
366
|
+
the machines that run the workspace.
|
|
332
367
|
|
|
333
368
|
## A workspace's machines
|
|
334
369
|
|
|
@@ -349,6 +384,18 @@ a row with what OATS reported, and a step that needs you says what to run
|
|
|
349
384
|
where, with a copy button. **Check again** re-runs both. The Desktop never asks
|
|
350
385
|
for a password or key, and never runs anything over ssh itself.
|
|
351
386
|
|
|
387
|
+
**Which machines the Desktop reads.** One roster read serves every window. With
|
|
388
|
+
an OATS CLI that lists the `roster-workspace-key` feature, it reads only the
|
|
389
|
+
machines of the workspaces your windows show: those registered for one of
|
|
390
|
+
them, those whose workspace is not known yet, and those known only from a
|
|
391
|
+
saved route. A machine registered for a workspace no window shows is not
|
|
392
|
+
contacted, so a machine that is switched off no longer slows every window's
|
|
393
|
+
roster. Opening a window on another workspace reads its machines at once. Until
|
|
394
|
+
it does, that workspace's machines are shown as they were last read, marked
|
|
395
|
+
stale, and the switcher still lists them, not counted live. The read covers every machine again while a window
|
|
396
|
+
shows the switcher, and on the first read after the Desktop starts. With an
|
|
397
|
+
older CLI, every registered machine is read, as before.
|
|
398
|
+
|
|
352
399
|
## Instances on servers
|
|
353
400
|
|
|
354
401
|
Every instance a registered server reports shows in its workspace's roster, whoever spawned it. You
|
|
@@ -371,7 +418,9 @@ what a part of the panel needs, that part names the server and says which OATS t
|
|
|
371
418
|
than showing nothing. A row that can't be opened says why on the row:
|
|
372
419
|
Herdr no longer supported, gone from <server>, not reachable on <server>, or <server> not reached.
|
|
373
420
|
For an instance a server no longer lists, the reason names the command that removes it from this
|
|
374
|
-
computer (`oats server forget <server> --instance <name>`)
|
|
421
|
+
computer (`oats server forget <server> --instance <name>`), and the row offers **Forget…**, in its
|
|
422
|
+
actions menu and in the context panel, which runs that command for that row after a confirmation.
|
|
423
|
+
Only this computer's saved route goes; nothing changes on the server, and the roster is read again.
|
|
375
424
|
|
|
376
425
|
## Remote terminals
|
|
377
426
|
|
|
@@ -467,8 +516,9 @@ unknown or unreported harness shows "?". Sources and licences are in
|
|
|
467
516
|
Do not expose it: it can type into your agent terminals.
|
|
468
517
|
- The app never imports framework code from a checkout and accepts no
|
|
469
518
|
framework-root environment override; deployments are read with an
|
|
470
|
-
app-owned read-only reader.
|
|
471
|
-
|
|
519
|
+
app-owned read-only reader. Lifecycle actions run the installed `oats` CLI
|
|
520
|
+
by its absolute path, never through a shell: reads with `execFile`, and a
|
|
521
|
+
stop, retire or start as a process in its own session.
|
|
472
522
|
- Task text for spawns travels via an owner-only (0600) tempfile, never
|
|
473
523
|
argv. A local start or restart launches only in the server-verified
|
|
474
524
|
instance home. A provider operation on an instance (its harvest included)
|
|
@@ -484,6 +534,7 @@ unknown or unreported harness shows "?". Sources and licences are in
|
|
|
484
534
|
| Symptom | Cause / fix |
|
|
485
535
|
| --- | --- |
|
|
486
536
|
| "Compatible oats CLI required" card | No CLI, or a version outside the range the card itself states. Copy the card's install command, or **Choose oats…** to point at the right binary; **Retry** re-probes. Spawn is disabled until a compatible CLI is verified. |
|
|
537
|
+
| "This Desktop is older than the installed oats CLI" card | The CLI found is a released version above the range this Desktop works with, usually because the CLI was updated first. Install OATS Desktop of the version the card names; the card offers no npm command, since installing the CLI this Desktop pins would downgrade it. Reads and terminals keep working meanwhile; **Choose oats…** points at another, compatible CLI and **Retry** re-probes. |
|
|
487
538
|
| Spawn disabled, no card | The probe hasn't settled yet (transient, resolves in ms). If it persists, the backend is unreachable — restart the app. |
|
|
488
539
|
| Terminals fail to open ("could not attach") | tmux missing, or no live session for that instance. Install tmux (`tmux -V`); check `tmux -L oats ls` (the OATS tmux server, where instances run) and `tmux ls` (your default server, where an instance started by an earlier kernel may still be). |
|
|
489
540
|
| Can't select/copy text in a terminal tab | A plain drag selects, and copying is a separate step: ⌘C / Edit › Copy (macOS), Ctrl+Shift+C (Linux/Windows) or right-click › Copy ([Copy from a terminal](#copy-from-a-terminal)). A drag selects only what is on screen: wheel up first for older output. In `oats session attach` in your own terminal, hold **Option** (iTerm2, Ghostty, Terminal.app) or **Shift** while dragging. |
|
|
@@ -502,12 +553,15 @@ Developer docs live in [`packages/desktop/README.md`](../packages/desktop/README
|
|
|
502
553
|
certificate auto-discovery disabled) and
|
|
503
554
|
`npm run dist:smoke` verifies the packed artifact. Build/release CI uses the
|
|
504
555
|
marked build-verify mode on every leg (inventory + strict codesign
|
|
505
|
-
verification
|
|
506
|
-
|
|
507
|
-
`
|
|
556
|
+
verification on macOS + on Linux the glibc floor, every ELF file of the DEB
|
|
557
|
+
and the AppImage read against the version the Install section states, held in
|
|
558
|
+
`packages/desktop/scripts/linux-floor.json` + node-pty ABI + a headless run of
|
|
559
|
+
the bundled backend, of its liveness collector and of every module main
|
|
560
|
+
imports, from `app.asar` and the `client/` directory beside it, no GUI
|
|
561
|
+
launch). The Linux leg then runs the
|
|
508
562
|
smoke once more with its launch phase, under a virtual display; no macOS leg
|
|
509
563
|
launches the window. A local interactive run may also exercise the launch
|
|
510
564
|
phase. The headless run starts the backend as the app does, checks that it
|
|
511
565
|
answers and that it exits when its stdin closes, and runs the collector once;
|
|
512
566
|
it does not exercise the GUI or, on Linux, the AppImage's launcher and
|
|
513
|
-
runtime.
|
|
567
|
+
runtime (the glibc floor runs the runtime only to unpack the AppImage).
|
|
@@ -104,7 +104,7 @@ other than the one the window is on.
|
|
|
104
104
|
|---|---|---|
|
|
105
105
|
| each agent window it creates | `window-style default`, `window-active-style default`, `cursor-colour default` | that window (`set-option -w`), by window id |
|
|
106
106
|
| each agent window, and the `hq` window of a session it creates | `window-size latest`, `aggressive-resize on` | that window |
|
|
107
|
-
| the pane of each window it launches a harness in, and a pane it respawns in place | no `COLORFGBG` in the pane's environment | that pane's command |
|
|
107
|
+
| the pane of each window it launches a harness in, and a pane it respawns in place | no `COLORFGBG` in the pane's environment, and none of the variables the launch removes ([a declared name is the provider's](capabilities.md#a-declared-name-is-the-providers)) | that pane's command |
|
|
108
108
|
|
|
109
109
|
So an agent pane takes the colours of the terminal that views it, whatever
|
|
110
110
|
the server's own defaults say, and on tmux 3.1 or later the window follows
|
|
@@ -200,7 +200,11 @@ global environment. A pane gets its session's environment over that (the
|
|
|
200
200
|
variables tmux's `update-environment` names, taken from whoever created the
|
|
201
201
|
session, and anything set on the session with `set-environment -t`), plus
|
|
202
202
|
what the launch command sets (`OATS_INSTANCE`, `OATS_INSTANCE_HOME`, the
|
|
203
|
-
capabilities' and the launch configuration's variables)
|
|
203
|
+
capabilities' and the launch configuration's variables), less what the
|
|
204
|
+
launch removes: a variable one of its capabilities declares and its hooks
|
|
205
|
+
leave out is not inherited from the session or the server
|
|
206
|
+
([a declared name is the provider's](capabilities.md#a-declared-name-is-the-providers)).
|
|
207
|
+
**A pane's
|
|
204
208
|
environment is its session's, `PATH` included, whoever creates its window**:
|
|
205
209
|
an instance, the Desktop or an operator's shell. The tmux client that creates
|
|
206
210
|
the window (or respawns the pane, in a restart in place) runs with only
|
|
@@ -220,6 +224,13 @@ first. So:
|
|
|
220
224
|
- The rest of the ambient environment follows the server's first creator,
|
|
221
225
|
and a server that already runs keeps what it started with. Creating a
|
|
222
226
|
session or a window on it changes nothing global.
|
|
227
|
+
- No window inherits another instance's launch environment through the
|
|
228
|
+
session or the server: OATS creates a session with no `-e` and sets no
|
|
229
|
+
instance's variables on it, and each window carries its instance's
|
|
230
|
+
variables on its own command. A value that reached the server's or a
|
|
231
|
+
session's environment some other way (a server started from inside an
|
|
232
|
+
instance's pane, a `set-environment`) stays there, and reaches a launch
|
|
233
|
+
only when none of that launch's capabilities declares the name.
|
|
223
234
|
|
|
224
235
|
**The harness is looked up where its pane looks it up.** A launch whose
|
|
225
236
|
executable is a bare name (the harness's own, or a launch configuration's
|
|
@@ -254,7 +265,10 @@ environment the server will be created with (your login environment, or its
|
|
|
254
265
|
fallback, below) for its first check, never this process's `PATH`. A recorded executable (a start that reuses the home's launch) is
|
|
255
266
|
kept as it is: it then runs with its pane's environment, but it is not looked
|
|
256
267
|
up again. A `--no-launch` spawn, and a preview with no server running, look
|
|
257
|
-
the harness up on the process's own `PATH`, as before
|
|
268
|
+
the harness up on the process's own `PATH`, as before, and the harness
|
|
269
|
+
packages such a spawn records (`composition.materialized.harnessPackages`)
|
|
270
|
+
are the ones found from the calling process; a preview says so
|
|
271
|
+
([below](#no-prediction)).
|
|
258
272
|
|
|
259
273
|
A session's `PATH` can be in four states, and the lookup tells them apart:
|
|
260
274
|
no entry (the server's `PATH` is used), a value, even an empty one (used as
|
|
@@ -271,6 +285,157 @@ remedies: declare the executable's absolute path in the launch configuration,
|
|
|
271
285
|
set `PATH` in the launch configuration, or start the server from your own
|
|
272
286
|
shell. It never prints a `PATH`'s contents.
|
|
273
287
|
|
|
288
|
+
<a id="the-checks-read-the-pane"></a>
|
|
289
|
+
**Every check of a launch reads the environment its pane will have.** The
|
|
290
|
+
lookup above is one of them. The others read the account the harness will
|
|
291
|
+
run with: the folder-trust check (the file that harness reads its trusted
|
|
292
|
+
folders from), the harness package check
|
|
293
|
+
([capabilities.md](capabilities.md#manifest), the probe and the command
|
|
294
|
+
its refusal names), the `harness-trust` item of `oats readiness`, a
|
|
295
|
+
preview's items, and `oats harness trust`. They read five names, each by
|
|
296
|
+
the same precedence and each with where it was read from: `PATH`, `HOME`,
|
|
297
|
+
and the variable that moves a harness's folder (`CLAUDE_CONFIG_DIR`,
|
|
298
|
+
`CODEX_HOME`, `PI_CODING_AGENT_DIR`), called its selector here.
|
|
299
|
+
|
|
300
|
+
1. The launch configuration's `env`: a literal, or a `fromEnv` reference,
|
|
301
|
+
which is resolved on this host from the process that runs the command, by
|
|
302
|
+
design. The pane's command line applies it, so nothing of tmux is read
|
|
303
|
+
for that name.
|
|
304
|
+
2. A selector the launch removes: one of its capabilities declares it and
|
|
305
|
+
their hooks leave it out
|
|
306
|
+
([a declared name is the provider's](capabilities.md#a-declared-name-is-the-providers)).
|
|
307
|
+
It reads as not set, whatever the session or the server holds. This is
|
|
308
|
+
known once the hooks have answered: the checks of a start, a spawn's
|
|
309
|
+
checks on the session it gets, its folder-trust check, and readiness.
|
|
310
|
+
3. When a server runs: the session's entry, and the server's global one only
|
|
311
|
+
when the session has no entry for that name. Both are read with the
|
|
312
|
+
strict reader below, in one `show-environment` each for all five names,
|
|
313
|
+
and only when a check needs a name that rows 1 and 2 do not decide.
|
|
314
|
+
4. When this spawn or start starts the server: the environment the server is
|
|
315
|
+
created with (your login environment, or its fallback, below).
|
|
316
|
+
|
|
317
|
+
None of them reads the calling process's value in place of the pane's. The
|
|
318
|
+
folder-trust check and the package check once read the process's own `HOME`
|
|
319
|
+
and selector, so a spawn from a shell or an instance with another account
|
|
320
|
+
than the server's checked one account and launched with another
|
|
321
|
+
([#993](https://github.com/awebai/oats/issues/993)).
|
|
322
|
+
|
|
323
|
+
- **"Not set" is an answer for a selector.** No entry in the session or the
|
|
324
|
+
server, or a session that clears it (`unset NAME;`, and the server's is
|
|
325
|
+
then not used, as tmux does), means the harness reads its default folder
|
|
326
|
+
under the pane's `HOME`: the checks read that file, and the package
|
|
327
|
+
check's command starts with no selector. An empty selector counts as not
|
|
328
|
+
set. A relative one read from tmux is read against the home, the pane's
|
|
329
|
+
working directory. For `PATH` and `HOME`, no entry anywhere and a clear
|
|
330
|
+
are problems, as for the lookup.
|
|
331
|
+
- **A name that cannot be read is never replaced.** The read failed, the
|
|
332
|
+
strict reader left the value out (it holds a `$`, a line break or a
|
|
333
|
+
character tmux prints encoded), or `PATH` or `HOME` is cleared or
|
|
334
|
+
missing. Two behaviours:
|
|
335
|
+
- **The package check refuses** with `E_RUNTIME_ENDPOINT_UNKNOWN`, before
|
|
336
|
+
it probes anything: `cannot verify the harness packages this <harness>
|
|
337
|
+
launch requires: <which name, read from where, and why not>. The probe
|
|
338
|
+
runs with the <NAME> the launch's pane will have, never with this
|
|
339
|
+
process's in its place; nothing was probed. To make it readable: set
|
|
340
|
+
<NAME> in the launch configuration (env), or <what would make it
|
|
341
|
+
readable in tmux>`. It needs `PATH`, `HOME` and the launching
|
|
342
|
+
harness's selector; a selector of another harness refuses nothing. It
|
|
343
|
+
reads nothing, and so refuses nothing, when no requirement applies to
|
|
344
|
+
the launch. A lookup that already refused a `PATH` is the one refusal
|
|
345
|
+
of that read: the package check does not refuse it again.
|
|
346
|
+
The probe runs the executable the lookup selected, by its full path,
|
|
347
|
+
never the harness's name looked up a second time: the command runs in
|
|
348
|
+
its own directory, not the pane's. For the same reason the probe is
|
|
349
|
+
given the pane's `PATH` as the pane reads it, a relative entry (and an
|
|
350
|
+
empty one) resolved against the pane's working directory, the home.
|
|
351
|
+
The command a refusal names keeps the harness's name as declared.
|
|
352
|
+
- **The folder-trust check only warns**: `<harness> folder trust: the
|
|
353
|
+
configuration file this launch will read could not be established
|
|
354
|
+
(<why, and what would make it readable>); nothing is said about its
|
|
355
|
+
trust`. A codex launch then does not trust its home from a file nobody
|
|
356
|
+
read (a codex launch under `yolo` trusts its home whatever a file says,
|
|
357
|
+
and is not affected).
|
|
358
|
+
- **A spawn judges again on the session it gets.** Like the lookup, the
|
|
359
|
+
package check and the folder-trust check run before anything is created,
|
|
360
|
+
on the pane the spawn expects, and again once the session exists (another
|
|
361
|
+
creator may have won the race to create the server, with another
|
|
362
|
+
account). The package check probes again only when `PATH`, `HOME` or
|
|
363
|
+
the selector differ from what it judged, or the lookup found the harness
|
|
364
|
+
at another path there; a requirement that does not hold
|
|
365
|
+
there refuses the spawn, which is rolled back as any failed launch is. The
|
|
366
|
+
folder-trust warning and the codex trust of the home follow the session
|
|
367
|
+
the spawn got. A start that creates its session makes the first check
|
|
368
|
+
only; a start that reuses its recorded pane reads that pane.
|
|
369
|
+
- **A warning names where the file comes from** when the pane's environment
|
|
370
|
+
is established: `claude folder trust is not established in <file> (the
|
|
371
|
+
CLAUDE_CONFIG_DIR of tmux session <name>): oats harness trust --dir
|
|
372
|
+
<deployment>`, or `(under the global HOME of the OATS tmux server
|
|
373
|
+
(<socket>))`, or the launch configuration's.
|
|
374
|
+
- **Through `oats spawn` the refusal's code is `E_RUNTIME_ENDPOINT_UNKNOWN`**,
|
|
375
|
+
with the same message, as at `oats session start` and `restart` (feature
|
|
376
|
+
`spawn-kernel-codes`, [#1047](https://github.com/awebai/oats/issues/1047));
|
|
377
|
+
a kernel without the feature answers `E_SPAWN_FAILED`.
|
|
378
|
+
- **One limit.** A spawn's package check runs before the spawn hooks, so it
|
|
379
|
+
does not know a selector a capability's hook sets for the launch
|
|
380
|
+
([#1041](https://github.com/awebai/oats/issues/1041)); a start's does.
|
|
381
|
+
For the same reason it does not know which declared selector the launch
|
|
382
|
+
will remove (row 2), and reads the pane's in its place; the spawn's check
|
|
383
|
+
on the session it gets does. The folder-trust check does not read the
|
|
384
|
+
capabilities' variables.
|
|
385
|
+
|
|
386
|
+
<a id="no-prediction"></a>
|
|
387
|
+
**When no pane can be predicted, the check says what it read instead.** No
|
|
388
|
+
server runs and the command only reads (a preview, `oats readiness`, `oats
|
|
389
|
+
harness trust`: none of them starts your login shell to find out); the
|
|
390
|
+
command has no tmux on its `PATH` to ask with; a preview could not read the
|
|
391
|
+
server; a start's session was refused; the spawn launches nothing
|
|
392
|
+
(`--no-launch`). The checks then read the launch
|
|
393
|
+
configuration's value when it sets one, else the calling process's, and say
|
|
394
|
+
so, for `PATH` too:
|
|
395
|
+
|
|
396
|
+
```
|
|
397
|
+
the pane's environment is not established until a spawn starts the OATS tmux server (none runs); read instead: this process's PATH
|
|
398
|
+
```
|
|
399
|
+
|
|
400
|
+
- **A command that writes does not take a failed read for "none runs".**
|
|
401
|
+
When tmux is there and could not say whether the server runs (its
|
|
402
|
+
`list-sessions` refused or cut off), a preview and
|
|
403
|
+
`oats readiness` answer as above, with `the pane's environment is not
|
|
404
|
+
established: this process could not read the OATS tmux server; read
|
|
405
|
+
instead: …`. `oats harness trust` refuses instead
|
|
406
|
+
(`E_RUNTIME_ENDPOINT_UNKNOWN`, nothing written): a server may run under
|
|
407
|
+
another account, and the command would write the wrong file
|
|
408
|
+
([harness-trust.md](harness-trust.md)). A command with no tmux on its
|
|
409
|
+
`PATH` makes no read at all: no prediction, for the writer as for the
|
|
410
|
+
others, with `the pane's environment is not established: this process has
|
|
411
|
+
no tmux on its PATH to read the OATS tmux server with; read instead: …`.
|
|
412
|
+
- A preview carries that sentence in the `executable` item's `detail`, in
|
|
413
|
+
the `harness-packages` item's when a requirement was probed, and a spawn
|
|
414
|
+
preview in `warnings`, in one line that names the checks (`the harness
|
|
415
|
+
lookup: …`, `the harness lookup, the harness package check: …`). The
|
|
416
|
+
package check does not refuse on that alone.
|
|
417
|
+
- The `harness-trust` item of `oats readiness` is then `unknown`, with
|
|
418
|
+
the sentence in `reason`: in the warning, in place of where the file comes
|
|
419
|
+
from, when the calling process's file does not establish trust; and when it
|
|
420
|
+
does, `<harness> folder trust is established in <file>; that file is this
|
|
421
|
+
process's, not known to be the one a launch will read: <the sentence>`. The item is optional,
|
|
422
|
+
as before, and `ready` does not change with it. A launch configuration
|
|
423
|
+
that sets the selector is read as before (`pass` or `fail`). When the
|
|
424
|
+
server runs and the read fails, the item is `unknown` with the "could not
|
|
425
|
+
be established" sentence above, and `file` is null.
|
|
426
|
+
- **A spawn that launches nothing says it only where it already says
|
|
427
|
+
something.** Its checks read the calling process by design, and the start
|
|
428
|
+
that follows checks again on its own session. When its checks pass it says
|
|
429
|
+
nothing. A folder-trust warning says whose file it read, where an
|
|
430
|
+
established one says where the file comes from: `claude folder trust is
|
|
431
|
+
not established in <file> (the pane's environment is not established: this
|
|
432
|
+
spawn launches nothing (--no-launch), and a start reads its own session's;
|
|
433
|
+
read instead: this process's CLAUDE_CONFIG_DIR (not set), this process's
|
|
434
|
+
HOME): oats harness trust --dir <deployment>`. A refusal for a missing
|
|
435
|
+
package ends with `The account this probe read is not known to be the
|
|
436
|
+
launch's: <the same sentence, naming PATH, HOME and the selector>`; a
|
|
437
|
+
preview's refusal with no server running does too.
|
|
438
|
+
|
|
274
439
|
Who starts the `oats` server, after an install, a reboot or its last session
|
|
275
440
|
ending, decides that ambient environment.
|
|
276
441
|
|
|
@@ -461,9 +626,10 @@ that triggered it), and `oats schedule run-now` typed inside an instance.
|
|
|
461
626
|
included. A restart that reuses the pane the home already has runs its tmux
|
|
462
627
|
client with the same environment; where and whether the pane is reused does
|
|
463
628
|
not change.
|
|
464
|
-
- **It is refused** (`E_RUNTIME_ENDPOINT_UNKNOWN
|
|
465
|
-
|
|
466
|
-
on the `oats` server, its login
|
|
629
|
+
- **It is refused** (`E_RUNTIME_ENDPOINT_UNKNOWN`, by `oats spawn` too, with
|
|
630
|
+
the same message; before 0.56.0 a spawn reported it as `E_SPAWN_FAILED`)
|
|
631
|
+
when the session does not exist on the `oats` server, its login
|
|
632
|
+
environment is not what the server gets
|
|
467
633
|
(the server runs, or the login environment could not be read), and there is
|
|
468
634
|
no source to read: the home records no
|
|
469
635
|
tmux server (it was never launched), its receipt cannot be used, or its
|
|
@@ -912,6 +1078,14 @@ oats session attach --home /abs/home --detach-key 'C-\'
|
|
|
912
1078
|
session linked to the agent's window alone.
|
|
913
1079
|
Closing the viewer leaves the agent running.
|
|
914
1080
|
|
|
1081
|
+
On tmux 3.2 and later the viewer's tmux client asks for synchronized
|
|
1082
|
+
output (`tmux -T sync`, for that client alone): tmux wraps each redraw in
|
|
1083
|
+
DEC mode 2026, so a terminal that receives a redraw in two pieces does not
|
|
1084
|
+
paint the half-drawn state, such as a cursor flickering while you type. A
|
|
1085
|
+
terminal without the mode ignores it. Before 3.2, or when `tmux -V` gives
|
|
1086
|
+
no version it can read, the client starts as before. A routed attach
|
|
1087
|
+
(`--server`) runs the same viewer on the host, so the host's tmux decides.
|
|
1088
|
+
|
|
915
1089
|
**Leaving the viewer.** Without `--detach-key` there is no keyboard exit:
|
|
916
1090
|
every key goes to the agent, the tmux prefix included. Close the terminal.
|
|
917
1091
|
With `--detach-key <key>` (`--detach-key=<key>` is the same; feature
|
|
@@ -1047,9 +1221,10 @@ Unattended execution never implies yolo.
|
|
|
1047
1221
|
|
|
1048
1222
|
Use `oats harness trust --dir <deployment> --harness claude|codex|all --plan`,
|
|
1049
1223
|
then the same command without `--plan`, on the execution host. It covers the ambient
|
|
1050
|
-
configuration file
|
|
1051
|
-
|
|
1052
|
-
|
|
1224
|
+
configuration file (the one a launch with no launch configuration reads,
|
|
1225
|
+
[by the pane's environment](#the-checks-read-the-pane)) and each launch
|
|
1226
|
+
configuration's `CLAUDE_CONFIG_DIR` / `CODEX_HOME`; launch-time checks read
|
|
1227
|
+
the file the launch's own environment selects. This is the explicit
|
|
1053
1228
|
operator-only native-config write path; spawn/start/retire remain read-only with
|
|
1054
1229
|
respect to native trust. See [native trust](harness-trust.md) for qualified formats,
|
|
1055
1230
|
Git-boundary limits, audit evidence and partial-failure recovery. Root trust does
|