@awebai/oats 0.55.1 → 0.56.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 (78) hide show
  1. package/bin/oats.mjs +78 -62
  2. package/docs/capabilities.md +67 -3
  3. package/docs/design/2026-09-23-workspace-module-contracts.md +27 -3
  4. package/docs/desktop-cli-api.md +317 -35
  5. package/docs/desktop-instance-start.md +105 -12
  6. package/docs/desktop.md +54 -7
  7. package/docs/execution-targets.md +184 -9
  8. package/docs/harness-trust.md +128 -11
  9. package/docs/implementation.md +54 -7
  10. package/docs/integrations.md +1 -1
  11. package/docs/knowledge.md +35 -16
  12. package/docs/official-catalog.md +3 -3
  13. package/docs/packages.md +12 -12
  14. package/docs/release-lane.md +26 -1
  15. package/docs/release-notes/v0.56.0.md +699 -0
  16. package/docs/servers.md +21 -5
  17. package/docs/souls-and-instances.md +8 -4
  18. package/docs/tui.md +99 -26
  19. package/docs/upgrading.md +4 -1
  20. package/docs/workspaces.md +26 -6
  21. package/lib/automations.mjs +3 -4
  22. package/lib/bounded-read.mjs +18 -0
  23. package/lib/capability-show.mjs +13 -2
  24. package/lib/claim.mjs +3 -4
  25. package/lib/core.mjs +480 -152
  26. package/lib/errors.mjs +39 -0
  27. package/lib/harness-trust-write.mjs +119 -40
  28. package/lib/harness-trust.mjs +31 -18
  29. package/lib/instance-inspect.mjs +160 -11
  30. package/lib/instance-lifecycle.mjs +47 -30
  31. package/lib/packages.mjs +8 -5
  32. package/lib/pi-bridge.mjs +18 -19
  33. package/lib/remote.mjs +88 -51
  34. package/lib/retire-output.mjs +9 -4
  35. package/lib/schedule.mjs +3 -4
  36. package/lib/servers.mjs +39 -6
  37. package/lib/session-viewer.mjs +25 -1
  38. package/lib/triggers.mjs +3 -4
  39. package/lib/workspace.mjs +6 -6
  40. package/lib/worktree.mjs +10 -6
  41. package/lib/write-through-private-file.mjs +26 -0
  42. package/package-catalog.json +2 -2
  43. package/package.json +1 -1
  44. package/packages/client/cli-adapter.mjs +108 -13
  45. package/packages/client/cli-locator.mjs +16 -14
  46. package/packages/client/deployment-panel.mjs +4 -3
  47. package/packages/client/display-text.mjs +2 -1
  48. package/packages/client/instance-events-contract.mjs +4 -3
  49. package/packages/client/instance-lifecycle.mjs +228 -0
  50. package/packages/client/instance-presentation.mjs +9 -0
  51. package/packages/client/instance-tree.mjs +10 -8
  52. package/packages/client/kernel-lines.mjs +3 -3
  53. package/packages/client/launch-contract.mjs +11 -0
  54. package/packages/client/lifecycle-cli.mjs +12 -6
  55. package/packages/client/lifecycle-confirmation.mjs +407 -0
  56. package/packages/client/lifecycle-contract.mjs +6 -2
  57. package/packages/client/own-codes.mjs +1 -0
  58. package/packages/client/panel-views.mjs +39 -2
  59. package/packages/client/readiness-contract.mjs +2 -2
  60. package/packages/client/remote-roster.mjs +50 -5
  61. package/packages/client/roster-sections.mjs +3 -3
  62. package/packages/client/session-start.mjs +98 -0
  63. package/packages/client/start-gate.mjs +46 -0
  64. package/packages/client/start-messages.mjs +17 -0
  65. package/packages/client/workspace-views.mjs +2 -2
  66. package/packages/tui/README.md +10 -6
  67. package/packages/tui/lib/actions.mjs +4 -2
  68. package/packages/tui/lib/client.mjs +5 -2
  69. package/packages/tui/lib/config.mjs +39 -9
  70. package/packages/tui/lib/main.mjs +83 -13
  71. package/packages/tui/lib/model.mjs +116 -11
  72. package/packages/tui/lib/open.mjs +45 -0
  73. package/packages/tui/lib/read.mjs +46 -10
  74. package/packages/tui/lib/store.mjs +64 -9
  75. package/packages/tui/lib/term/tty.mjs +71 -12
  76. package/packages/tui/lib/views/frame.mjs +115 -33
  77. package/packages/tui/lib/views/help.mjs +37 -8
  78. 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`, `--harness` or `--yolo`/`--no-yolo`.
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`. These features
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
- 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
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 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.
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
@@ -349,6 +377,18 @@ a row with what OATS reported, and a step that needs you says what to run
349
377
  where, with a copy button. **Check again** re-runs both. The Desktop never asks
350
378
  for a password or key, and never runs anything over ssh itself.
351
379
 
380
+ **Which machines the Desktop reads.** One roster read serves every window. With
381
+ an OATS CLI that lists the `roster-workspace-key` feature, it reads only the
382
+ machines of the workspaces your windows show: those registered for one of
383
+ them, those whose workspace is not known yet, and those known only from a
384
+ saved route. A machine registered for a workspace no window shows is not
385
+ contacted, so a machine that is switched off no longer slows every window's
386
+ roster. Opening a window on another workspace reads its machines at once. Until
387
+ it does, that workspace's machines are shown as they were last read, marked
388
+ stale, and the switcher still lists them, not counted live. The read covers every machine again while a window
389
+ shows the switcher, and on the first read after the Desktop starts. With an
390
+ older CLI, every registered machine is read, as before.
391
+
352
392
  ## Instances on servers
353
393
 
354
394
  Every instance a registered server reports shows in its workspace's roster, whoever spawned it. You
@@ -371,7 +411,9 @@ what a part of the panel needs, that part names the server and says which OATS t
371
411
  than showing nothing. A row that can't be opened says why on the row:
372
412
  Herdr no longer supported, gone from <server>, not reachable on <server>, or <server> not reached.
373
413
  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>`).
414
+ computer (`oats server forget <server> --instance <name>`), and the row offers **Forget…**, in its
415
+ actions menu and in the context panel, which runs that command for that row after a confirmation.
416
+ Only this computer's saved route goes; nothing changes on the server, and the roster is read again.
375
417
 
376
418
  ## Remote terminals
377
419
 
@@ -467,8 +509,9 @@ unknown or unreported harness shows "?". Sources and licences are in
467
509
  Do not expose it: it can type into your agent terminals.
468
510
  - The app never imports framework code from a checkout and accepts no
469
511
  framework-root environment override; deployments are read with an
470
- app-owned read-only reader. All lifecycle mutations go through the
471
- installed CLI via `execFile` with an absolute binary — never a shell.
512
+ app-owned read-only reader. Lifecycle actions run the installed `oats` CLI
513
+ by its absolute path, never through a shell: reads with `execFile`, and a
514
+ stop, retire or start as a process in its own session.
472
515
  - Task text for spawns travels via an owner-only (0600) tempfile, never
473
516
  argv. A local start or restart launches only in the server-verified
474
517
  instance home. A provider operation on an instance (its harvest included)
@@ -484,6 +527,7 @@ unknown or unreported harness shows "?". Sources and licences are in
484
527
  | Symptom | Cause / fix |
485
528
  | --- | --- |
486
529
  | "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. |
530
+ | "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
531
  | 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
532
  | 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
533
  | 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 +546,15 @@ Developer docs live in [`packages/desktop/README.md`](../packages/desktop/README
502
546
  certificate auto-discovery disabled) and
503
547
  `npm run dist:smoke` verifies the packed artifact. Build/release CI uses the
504
548
  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
549
+ verification on macOS + on Linux the glibc floor, every ELF file of the DEB
550
+ and the AppImage read against the version the Install section states, held in
551
+ `packages/desktop/scripts/linux-floor.json` + node-pty ABI + a headless run of
552
+ the bundled backend, of its liveness collector and of every module main
553
+ imports, from `app.asar` and the `client/` directory beside it, no GUI
554
+ launch). The Linux leg then runs the
508
555
  smoke once more with its launch phase, under a virtual display; no macOS leg
509
556
  launches the window. A local interactive run may also exercise the launch
510
557
  phase. The headless run starts the backend as the app does, checks that it
511
558
  answers and that it exits when its stdin closes, and runs the collector once;
512
559
  it does not exercise the GUI or, on Linux, the AppImage's launcher and
513
- runtime.
560
+ 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). **A pane's
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`; `oats spawn` reports it
465
- as `E_SPAWN_FAILED` with the same message) when the session does not exist
466
- on the `oats` server, its login environment is not what the server gets
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 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
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