@awebai/oats 0.55.0 → 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 (81) 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 +2 -2
  11. package/docs/knowledge.md +35 -16
  12. package/docs/official-catalog.md +4 -4
  13. package/docs/packages.md +14 -14
  14. package/docs/release-lane.md +26 -1
  15. package/docs/release-notes/v0.55.1.md +45 -0
  16. package/docs/release-notes/v0.56.0.md +699 -0
  17. package/docs/servers.md +21 -5
  18. package/docs/souls-and-instances.md +8 -4
  19. package/docs/tui.md +99 -26
  20. package/docs/upgrading.md +4 -1
  21. package/docs/workspaces.md +26 -6
  22. package/lib/automations.mjs +3 -4
  23. package/lib/bounded-read.mjs +18 -0
  24. package/lib/capability-show.mjs +13 -2
  25. package/lib/claim.mjs +3 -4
  26. package/lib/core.mjs +480 -152
  27. package/lib/errors.mjs +39 -0
  28. package/lib/harness-trust-write.mjs +119 -40
  29. package/lib/harness-trust.mjs +31 -18
  30. package/lib/instance-inspect.mjs +160 -11
  31. package/lib/instance-lifecycle.mjs +47 -30
  32. package/lib/packages.mjs +8 -5
  33. package/lib/pi-bridge.mjs +18 -19
  34. package/lib/remote.mjs +88 -51
  35. package/lib/retire-output.mjs +9 -4
  36. package/lib/schedule.mjs +3 -4
  37. package/lib/servers.mjs +39 -6
  38. package/lib/session-viewer.mjs +25 -1
  39. package/lib/triggers.mjs +3 -4
  40. package/lib/workspace.mjs +6 -6
  41. package/lib/worktree.mjs +10 -6
  42. package/lib/write-through-private-file.mjs +26 -0
  43. package/package-catalog.json +3 -3
  44. package/package.json +1 -1
  45. package/packages/client/cli-adapter.mjs +108 -13
  46. package/packages/client/cli-locator.mjs +16 -14
  47. package/packages/client/deployment-panel.mjs +4 -3
  48. package/packages/client/display-text.mjs +2 -1
  49. package/packages/client/instance-events-contract.mjs +4 -3
  50. package/packages/client/instance-lifecycle.mjs +228 -0
  51. package/packages/client/instance-presentation.mjs +9 -0
  52. package/packages/client/instance-tree.mjs +10 -8
  53. package/packages/client/kernel-lines.mjs +3 -3
  54. package/packages/client/launch-contract.mjs +11 -0
  55. package/packages/client/lifecycle-cli.mjs +12 -6
  56. package/packages/client/lifecycle-confirmation.mjs +407 -0
  57. package/packages/client/lifecycle-contract.mjs +6 -2
  58. package/packages/client/own-codes.mjs +1 -0
  59. package/packages/client/panel-views.mjs +39 -2
  60. package/packages/client/readiness-contract.mjs +2 -2
  61. package/packages/client/remote-roster.mjs +50 -5
  62. package/packages/client/roster-sections.mjs +3 -3
  63. package/packages/client/session-start.mjs +98 -0
  64. package/packages/client/start-gate.mjs +46 -0
  65. package/packages/client/start-messages.mjs +17 -0
  66. package/packages/client/workspace-views.mjs +2 -2
  67. package/packages/record/README.md +4 -0
  68. package/packages/record/bin/recall.mjs +3 -2
  69. package/packages/tui/README.md +10 -6
  70. package/packages/tui/lib/actions.mjs +4 -2
  71. package/packages/tui/lib/client.mjs +5 -2
  72. package/packages/tui/lib/config.mjs +39 -9
  73. package/packages/tui/lib/main.mjs +83 -13
  74. package/packages/tui/lib/model.mjs +116 -11
  75. package/packages/tui/lib/open.mjs +45 -0
  76. package/packages/tui/lib/read.mjs +46 -10
  77. package/packages/tui/lib/store.mjs +64 -9
  78. package/packages/tui/lib/term/tty.mjs +71 -12
  79. package/packages/tui/lib/views/frame.mjs +115 -33
  80. package/packages/tui/lib/views/help.mjs +37 -8
  81. package/skills/oats-getting-started/SKILL.md +6 -3
package/docs/servers.md CHANGED
@@ -217,7 +217,7 @@ sent as text or on stdin, never as paths.
217
217
 
218
218
  | Command | Where it runs | The server must advertise |
219
219
  |---|---|---|
220
- | `spawn` | registered workspace | the requested harness, backend and yolo option; `launch-config` for `--launch-config`; `schedule` for a wake schedule |
220
+ | `spawn` | registered workspace | the requested harness, backend and yolo option; `launch-config` for `--launch-config`; `schedule` for a wake schedule; `spawn-preview-2` for `--preview` |
221
221
  | `status` | registered workspace | |
222
222
  | `retire` | the instance's home | `retire-home` to retire by exact home |
223
223
  | `session inspect`, `session attach` | the instance's home | `session`; `session-attach-detach-key` for `attach --detach-key` |
@@ -226,7 +226,7 @@ sent as text or on stdin, never as paths.
226
226
  | `okf harvest --instance <name>` | the saved home | `harvest` |
227
227
  | `schedule ...` | registered workspace | `schedule` |
228
228
  | `launch-config list\|set\|remove\|preview` | `--dir`, the instance's home, or the registered workspace | `launch-config` |
229
- | `inspect`, `operation run` | `--dir`, the instance's home, or the registered workspace | `operations`; `inspect --instructions` also `soul-composed-instructions` |
229
+ | `inspect`, `operation run` | `--dir`, the instance's home, or the registered workspace | `operations`; `inspect --instructions` also `soul-composed-instructions`, `inspect --skills` also `soul-skills` |
230
230
  | `readiness` | the instance's home, `--dir`, or the registered workspace | `readiness` (`readinessApi: 2`) |
231
231
  | `instance events` | the instance's home | `instance-events-2` (`eventsApi: 2`) |
232
232
  | `instance git`, `instance diff` | the instance's home; the Git runs there | `instance-git` (`instanceGitApi: 1`) |
@@ -239,6 +239,17 @@ checked against the harness it would use (the flag, or the soul's default as
239
239
  the remote roster reports it). A host that advertises no harness list is
240
240
  assumed to run only pi and claude, on tmux, with no launch options.
241
241
 
242
+ **A routed preview.** `oats spawn <soul> --server <id> --preview` runs the
243
+ spawn's checks here (`E_ROUTE_CHANGED`, `E_ROUTE_EXISTS`, the harness and
244
+ options), then asks the server's kernel for its preview. It prints the local
245
+ preview's line with the server named (`preview <soul> → <instance> on <id> …;
246
+ nothing was created`), and saves no route or other state on this machine. Its
247
+ `--json` result is the server's preview plus `server` and `target`. When a
248
+ saved route already holds the previewed name for another home, a warning says
249
+ a spawn would save no route. A server that does not advertise
250
+ `spawn-preview-2` is refused (`E_REMOTE_INCOMPATIBLE`) before the spawn is
251
+ sent, since an older kernel might spawn for real.
252
+
242
253
  **Addressing an instance.** Instance commands (`retire`, the `session`
243
254
  commands, `inspect`, `operation`, `launch-config`) reach any instance on the
244
255
  server, whoever spawned it, by `--home </remote/home>` or by name
@@ -338,7 +349,12 @@ capped by `--budget` (default 45 s, the deadline of the whole answer), and a
338
349
  group that fails or does not answer in time reports its own `E_SSH`, so a
339
350
  host that is switched off never hides the others. The groups keep their
340
351
  registration order whatever order their probes finish in. `--server <id>`
341
- narrows it.
352
+ narrows it. `--workspace-key <key>` (0.56.0, repeatable) narrows it to the
353
+ groups that can belong to those workspaces: a registration recorded for one
354
+ of them, a registration whose workspace is not known yet, and a group of
355
+ saved routes only, whose workspace is unknown; a registration recorded for
356
+ another workspace is not probed at all
357
+ ([the flag](desktop-cli-api.md#roster-workspace-key)).
342
358
 
343
359
  The group's `probe` also relays the host's kernel features (0.49.0,
344
360
  `probe.features`): the top-level `features` of the same `status --json`
@@ -353,8 +369,8 @@ instance's saved home on the server and relays its envelope.
353
369
  ## What this machine keeps
354
370
 
355
371
  A **saved route** per remote instance, under `~/.oats/remote/<server>/`,
356
- written at spawn: the ssh host, workspace, oats path and PATH prefix, and the
357
- remote home. Retire, harvest and session commands use
372
+ written at spawn (never by a preview): the ssh host, workspace, oats path and
373
+ PATH prefix, and the remote home. Retire, harvest and session commands use
358
374
  the saved route, not the current registration, so editing or removing a
359
375
  registration never orphans a remote home. The route is removed when the
360
376
  remote kernel reports the home gone.
@@ -231,8 +231,9 @@ operation and partial-failure recovery.
231
231
  to a Git root. An intervening repository can prevent deployment-root inheritance;
232
232
  the command does not automatically trust another root. The native field is
233
233
  `projects["<deployment>"].hasTrustDialogAccepted` in `~/.claude.json`
234
- (`$CLAUDE_CONFIG_DIR/.claude.json` when the launch's environment, host or
235
- launch configuration, sets it).
234
+ (`$CLAUDE_CONFIG_DIR/.claude.json` when the launch's environment sets it:
235
+ its launch configuration, else its tmux pane's, never the calling
236
+ process's in its place).
236
237
  - **Codex** applies only an exact entry: a trusted parent does not cover the
237
238
  folders below it. The explicit deployment-root command records
238
239
  `[projects."<deployment>"] trust_level = "trusted"` in
@@ -247,11 +248,14 @@ operation and partial-failure recovery.
247
248
 
248
249
  When the file a claude or codex launch reads does not trust the deployment,
249
250
  the spawn says so (text and `--json` `warnings`): `<harness> folder trust is
250
- not established in <file>: oats harness trust --dir <deployment>`. A missing
251
+ not established in <file> (<where the launch gets that file from>): oats
252
+ harness trust --dir <deployment>`. A missing
251
253
  entry does not prove a prompt, so it does not say the session will stop.
252
254
  `oats readiness` reports the same in `checks.configured` (code
253
255
  `harness-trust`, not required), and a passing item naming the file when trust
254
- is established.
256
+ is established. When the file cannot be established, or no pane exists to
257
+ read it from, both say that instead
258
+ ([launch-time checks](harness-trust.md#launch-time-checks-and-readiness)).
255
259
 
256
260
  [The development-channel confirmation](configuration.md#the-development-channel-confirmation)
257
261
  does not cover folder-trust prompts, and never writes trust settings.
package/docs/tui.md CHANGED
@@ -12,12 +12,13 @@ install.
12
12
  `oats tui` is marked **preview**. That means:
13
13
 
14
14
  - **This version shows a workspace's instances, on this machine and on the
15
- other machines registered on this machine, in one list, and changes
16
- nothing.** The registered machines are the ones `oats server list` names.
17
- It follows the instances as they start, stop and wait for you. It cannot
18
- open an agent's terminal, stop, start, restart or retire one, spawn one,
19
- or add, check or remove a machine: [what it does not do
20
- yet](#what-this-version-does-not-do) names the `oats` command for each.
15
+ other machines registered on this machine, in one list, and opens an
16
+ agent's terminal. It changes nothing in a deployment.** The registered
17
+ machines are the ones `oats server list` names. It follows the instances
18
+ as they start, stop and wait for you. It cannot stop, start, restart or
19
+ retire an agent, spawn one, or add, check or remove a machine: [what it
20
+ does not do yet](#what-this-version-does-not-do) names the `oats` command
21
+ for each.
21
22
  - **Its screens and its configuration file may change without notice** while
22
23
  it is a preview.
23
24
  - **It leaves preview when three things hold:** the readers it shares with
@@ -126,6 +127,29 @@ runs.
126
127
  branch, team, parent, when it last started, and its home. From 80
127
128
  columns up it stands beside the list; on a narrower terminal `Tab` opens
128
129
  it as a page.
130
+ - **Opening an agent.** `Enter` on an instance that runs gives your terminal
131
+ to that agent's own terminal, through `oats session attach`: you see what
132
+ the agent shows, and what you type goes to it. `Ctrl+\` brings `oats tui`
133
+ back, and the agent keeps running. The key is yours to change
134
+ ([`tui.json`](#change-the-keys-tuijson)), and the footer names it whenever
135
+ `Enter` would open.
136
+ - Inside tmux the agent opens in the same pane. `oats tui` makes no window
137
+ and no split.
138
+ - After the return the instances are read again at once, and one line
139
+ says what happened: that you left and the agent keeps running, that it
140
+ could not be opened, or that the connection to its machine ended. When
141
+ the agent's own terminal ended while you were in it, you are back with
142
+ no line: the list shows the agent as it now is.
143
+ - What `oats session attach` printed when it failed stands under that line
144
+ in quotation marks. It is not said who printed it: OATS, tmux and ssh
145
+ all can.
146
+ - `Enter` on an instance that cannot be opened opens nothing and says why:
147
+ it does not run, whether it runs is not known, the detail's reason holds
148
+ it, or its machine's OATS is older than 0.51.0 and has no key to leave a
149
+ viewer.
150
+ - For each time you open an agent, one line of tmux's own stays on your
151
+ screen and is there after you quit: `[detached (from session …)]`, or
152
+ `[exited]`.
129
153
 
130
154
  **A view of more than one deployment** (this machine and another, or two
131
155
  deployments on one machine) is one list, grouped as the Desktop groups it:
@@ -295,7 +319,7 @@ nothing open.
295
319
  | `r` | read now |
296
320
  | `1` | the Instances view |
297
321
  | `w` | opens [the switcher](#the-switcher) |
298
- | `Enter` | in the switcher, opens the selected row |
322
+ | `Enter` | in the list of instances, opens the selected agent's terminal; in the switcher, opens the selected row |
299
323
  | `?` | opens the help; `?` again closes it |
300
324
  | `Esc` | closes, in this order: the help, the filter field, a kept filter, then the detail or the switcher |
301
325
  | `q`, `Ctrl+C` | quits, with status 0 (a SIGINT from outside answers 130) |
@@ -310,10 +334,10 @@ the list has none), it scrolls the list instead, so the rows after the last
310
334
  instance can always be read, however many they are. The selection stays
311
335
  where it is, and the list returns to it at the next key that moves it.
312
336
 
313
- In the list of instances `Enter` does nothing. The help screen is generated
314
- from the table the program acts on, so it always lists the keys that work,
315
- with the marks and with what this version does not do. The movement keys
316
- scroll it. `Ctrl+\` does nothing.
337
+ The help screen is generated from the table the program acts on, so it
338
+ always lists the keys that work, with the marks and with what this version
339
+ does not do. The movement keys scroll it. While `oats tui` has the screen,
340
+ `Ctrl+\` does nothing.
317
341
 
318
342
  **The filter.** `/` opens a field on the last row. What you type narrows the
319
343
  list to the instances whose name, soul or repository contains it, with the
@@ -339,7 +363,7 @@ an absolute path, else `~/.config/oats/tui.json`, once, at the start. It
339
363
  never writes it. With no file the keys are the ones above.
340
364
 
341
365
  ```json
342
- { "keys": { "quit": ["q"], "refresh": ["r", "f5"], "suspend": [] }, "ascii": false }
366
+ { "keys": { "quit": ["q"], "refresh": ["r", "f5"], "suspend": [] }, "ascii": false, "open": { "detachKey": "F12" } }
343
367
  ```
344
368
 
345
369
  - `keys.<action>` is the list of keys of that action. It **replaces** the
@@ -347,10 +371,11 @@ never writes it. With no file the keys are the ones above.
347
371
  do not name keeps its keys.
348
372
  - The actions are `up`, `down`, `top`, `bottom`, `page-up`, `page-down`,
349
373
  `collapse`, `expand`, `detail`, `filter`, `refresh`, `instances`,
350
- `workspaces`, `open-workspace`, `help`, `close`, `quit`, `suspend` and
351
- `redraw`. `workspaces` (`w`) opens the switcher and `open-workspace`
352
- (`enter`) opens its selected row. In an open filter field `Enter` keeps
353
- the filter, whatever key `open-workspace` has.
374
+ `workspaces`, `open`, `help`, `close`, `quit`, `suspend` and `redraw`.
375
+ `workspaces` (`w`) opens the switcher and `open` (`enter`) opens the
376
+ selected agent's terminal in the list of instances and the selected row
377
+ in the switcher. In an open filter field `Enter` keeps the filter,
378
+ whatever key `open` has.
354
379
  - A key is written as the help shows it, in lower case: `q`, `G`, `?`,
355
380
  `space`, `enter`, `tab`, `escape`, `backspace`, `up`, `pageup`, `f5`,
356
381
  `ctrl+c`, `alt+x`, `shift+tab`, `ctrl+alt+up`. Modifiers come in the order
@@ -358,6 +383,12 @@ never writes it. With no file the keys are the ones above.
358
383
  and `Ctrl+M` as `backspace`, `tab` and `enter`, so those four are not
359
384
  keys of their own.
360
385
  - `ascii: true` is `--ascii`.
386
+ - `open.detachKey` is the key that leaves an agent's terminal, written as
387
+ `oats session attach --detach-key` takes it: `C-\` when you name none.
388
+ [Execution targets](execution-targets.md) has the keys that can be chosen.
389
+ `oats tui` does not check it: a key OATS refuses is said when you open an
390
+ agent. A key that tmux's copy mode binds leaves the viewer once that mode
391
+ is left.
361
392
 
362
393
  **A file it cannot honour stops the start.** Each problem is one line on
363
394
  stderr, the status is 1 and nothing is drawn; it resolves no conflict and
@@ -368,7 +399,12 @@ guesses nothing. It refuses:
368
399
  | is not a regular file (a link to one is read), or cannot be read | `it is not a regular file`, `it cannot be read` |
369
400
  | is larger than 64 KiB | `it is larger than 64 KiB` |
370
401
  | is not one JSON object | `it is not valid JSON`, `it is not one JSON object` |
371
- | has a setting other than `keys` and `ascii`, or one of the wrong kind | `unknown setting …`, `keys must be an object`, `ascii must be true or false` |
402
+ | has a setting other than `keys`, `ascii` and `open`, or one of the wrong kind | `unknown setting …`, `keys must be an object`, `ascii must be true or false`, `open must be an object` |
403
+ | has a member of `open` other than `detachKey` | `unknown member … of open; open has detachKey` |
404
+ | gives `open.detachKey` something that is not 1 to 16 printable ASCII characters | `open.detachKey must be 1 to 16 printable ASCII characters` |
405
+ | gives `open.detachKey` a value that begins with `-` | `open.detachKey cannot begin with -` |
406
+ | gives `open.detachKey` a value the help would draw as another key (a run of spaces, a space at an end) | `open.detachKey is a key the help cannot name` |
407
+ | names `open-workspace`, the action's name before it became `open` | `open-workspace is called open now; rename it` |
372
408
  | names an action that does not exist | `unknown action …`, with the list of actions |
373
409
  | gives an action something that is not a list of strings | `… must be a list of key ids` |
374
410
  | has a string that is not a key | `the key … of … is not a key id` |
@@ -424,20 +460,27 @@ with the Desktop (`packages/client/`).
424
460
  listed: at most 200, and each directory among them is asked for a regular
425
461
  `oats-local.yaml`. An entry that is a link is not followed. When a folder
426
462
  is opened, that one directory is asked again.
427
- - **Every child runs in a session of its own** and is ended when the TUI
463
+ - **Opening an agent runs one more command,** `oats session attach --home
464
+ <home> --detach-key <key>`, by the same kernel, with your terminal as its
465
+ terminal. For an agent on another machine `oats session inspect --server
466
+ <id> --home <home> --json` is asked first (20 seconds), then `oats session
467
+ attach --server <id> --home <home> --detach-key <key>`. Nothing is read
468
+ while the agent has the terminal, and the return reads at once.
469
+ - **Every read runs in a session of its own** and is ended when the TUI
428
470
  ends, on every way out a process can handle (for SIGKILL see
429
- [below](#what-it-changes-in-your-terminal-and-restores)). A read that was
471
+ [below](#what-it-changes-in-your-terminal-and-restores)). The viewer
472
+ shares your terminal, and is ended first when `oats tui` is ended while an
473
+ agent has the terminal. A read that was
430
474
  running when the TUI is suspended is dropped, not shown: its answer could
431
475
  arrive cut. That holds for the read of the other machines too. The return
432
476
  reads again.
433
- - It reads only. It runs no command that changes a deployment or a
434
- registration, and it writes no file.
477
+ - It runs no command that changes a deployment or a registration, and it
478
+ writes no file.
435
479
 
436
480
  ## What this version does not do
437
481
 
438
482
  | To | Run |
439
483
  |---|---|
440
- | open an agent's terminal | `oats session attach --home <home>` (the detail shows the home) |
441
484
  | stop an agent | `oats instance stop <instance>` |
442
485
  | start or restart an agent | `oats session start --home <home>` |
443
486
  | retire an agent | `oats retire <instance>` |
@@ -447,6 +490,7 @@ with the Desktop (`packages/client/`).
447
490
  | check a machine | `oats server check <id>` |
448
491
  | remove a machine | `oats server remove <id>` |
449
492
  | open a deployment outside `~/Agents` | `oats tui --dir <path>` |
493
+ | open an agent in a tmux window or split of its own | `oats session attach --home <home>` in that window (the detail shows the home) |
450
494
 
451
495
  The help screen (`?`) names the same commands. What else holds for this
452
496
  version:
@@ -464,6 +508,9 @@ version:
464
508
  - Souls and Capabilities, when they come, are this machine's.
465
509
  - There is no sorting and no mouse, and a deployment's heading cannot be
466
510
  folded.
511
+ - With an OATS older than 0.52.0, after an interrupted stop the instance can
512
+ be started and then cannot be stopped while `.oats-stop-pending.json` exists
513
+ in its home.
467
514
 
468
515
  ## What it changes in your terminal, and restores
469
516
 
@@ -504,6 +551,16 @@ It stops the whole foreground process group, as a `Ctrl+Z` does for any
504
551
  other program, so `oats tui` started through a wrapper (`sh -c`, `npx`)
505
552
  suspends as one job.
506
553
 
554
+ **While an agent has the terminal** `oats tui` has put the terminal back in
555
+ full, as for a suspend, and draws nothing. The viewer is OATS's own: it sets
556
+ what it needs, the mouse for scrolling among it, and puts that back when it
557
+ ends. Then `oats tui` sets its modes again. A SIGQUIT does not end
558
+ `oats tui` while an agent has the terminal (a second `Ctrl+\`, pressed as the
559
+ viewer leaves, is that signal). SIGINT, SIGTERM and SIGHUP end the viewer
560
+ first and then `oats tui`, with the status of the table above. A viewer
561
+ that has not ended 3 seconds after it was asked, or at a second signal, is
562
+ left as it is, and `oats tui` ends without it.
563
+
507
564
  `Ctrl+C` is the quit key: in raw mode the terminal sends it as a byte, not as
508
565
  a signal, so it answers 0. A SIGINT sent from outside (`kill -INT`) answers
509
566
  130. A script that wraps `oats tui` meets that difference.
@@ -515,7 +572,9 @@ on tmux 3.7c, `reset` brought back the cursor and autowrap, and the pane
515
572
  stayed in the alternate screen until `tput rmcup`. Nothing else is left in
516
573
  tmux: `oats tui` creates no session, window, option or key binding.
517
574
  Nor can it end a read after SIGKILL: nothing of the TUI runs any more, so a
518
- read that was in flight runs to its own end. It only reads.
575
+ read that was in flight runs to its own end. After a SIGKILL while an agent
576
+ has the terminal, the viewer still has it: leave it with the key and you are
577
+ in your shell.
519
578
 
520
579
  ## What it never does
521
580
 
@@ -543,10 +602,16 @@ read that was in flight runs to its own end. It only reads.
543
602
  for a speaker. They never stand before a withheld text: a reason that is
544
603
  withheld is `[withheld]` alone.
545
604
  - It changes nothing in tmux: no option, key binding, server, session,
546
- window or pane. Its probe only lists panes.
605
+ window or pane. Its probe only lists panes. An agent's terminal is opened
606
+ by `oats session attach`, which makes its own viewer session on the
607
+ agents' tmux server and removes it; `oats tui` builds no viewer and runs
608
+ no tmux command for it.
547
609
  - It starts no daemon, opens no socket and writes no file. The processes it
548
- starts are the reads above, and none outlives it on every way out a
549
- process can handle; after SIGKILL a read in flight runs to its own end.
610
+ starts are the reads above and, when you open an agent, the viewer; none
611
+ outlives it on every way out a process can handle, except a viewer that
612
+ does not end when asked (see
613
+ [above](#what-it-changes-in-your-terminal-and-restores)); after SIGKILL a
614
+ read in flight runs to its own end, and a viewer stays until you leave it.
550
615
 
551
616
  ## Errors
552
617
 
@@ -577,6 +642,14 @@ that is a bug worth reporting, with the terminal's name and `TERM`.
577
642
  Another machine is reached only through the kernel's own read
578
643
  (`oats server roster`): `oats tui` opens no connection of its own.
579
644
 
645
+ Opening an agent has been run in the automated tests only, in two private
646
+ tmux servers: one holds the agent's window, as a deployment records it, and
647
+ the other plays your terminal, with the real `oats tui` and the real
648
+ `oats session attach` in its pane. No real terminal emulator, no ssh and no
649
+ other machine reached for real were used: an agent of another machine is
650
+ opened in the tests from the kernel's answer handed to the client. So far no
651
+ person has opened an agent from `oats tui` in a real terminal.
652
+
580
653
  With a registered machine it has been run only against one that did not
581
654
  answer: the switcher lists it by its own name with the reason, and its view
582
655
  says that it was not reached. A machine that answers is drawn in the
package/docs/upgrading.md CHANGED
@@ -53,7 +53,10 @@ Without a terminal (a script, an agent's shell) it runs only with `--yes`.
53
53
  plan starts with that install, and the bridges move to that same version in
54
54
  the same run. So where the Desktop is installed, step 0 comes before such an
55
55
  `oats update` too: `oats update --check` shows whether the plan holds that
56
- install, and runs nothing.
56
+ install, and runs nothing. When that install is of another minor or major
57
+ version, the plan says so in one line under its steps, whether or not a
58
+ Desktop is installed: `OATS Desktop refuses a CLI newer than its own minor
59
+ version: if you use it, install OATS Desktop <version> first.`
57
60
 
58
61
  **`oats update` only moves forward.** It never installs an older CLI or an
59
62
  older bridge than the one in place:
@@ -54,8 +54,8 @@ members: # repo refs, NO @revision (E_WORKSPAC
54
54
  - git:github.com/acme/tools # a member that ALSO publishes a package (see below)
55
55
 
56
56
  packages: # the ONLY versioned things
57
- oats.framework: v1.10.0 # bare version → resolves through the official catalog
58
- oats.okf: v5.0.5
57
+ oats.framework: v1.10.1 # bare version → resolves through the official catalog
58
+ oats.okf: v5.1.0
59
59
  acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
60
60
 
61
61
  teams: # SHARED teams: the same provider team for everyone
@@ -161,6 +161,13 @@ Written by `oats sync`; the only persisted state at the deployment besides
161
161
 
162
162
  ## Repository references in diagnostics
163
163
 
164
+ Kernel call sites select the display context explicitly: `displayRepoRef`
165
+ for selected reference values, `displayDiagnosticText` for kernel-authored
166
+ diagnostic prose and `scrubGitLine` for Git's own lines. The entry points
167
+ share one private renderer; options on the first two cannot select Git-line
168
+ handling. The [development reference](implementation.md#remote-diagnostic-display)
169
+ documents their signatures and direct-module use.
170
+
164
171
  Selected repository references in diagnostics are display values. A selected
165
172
  original refused reference is shown verbatim when it is 1–256 characters long
166
173
  and contains only ASCII letters, digits, spaces, `.`, `_`, `/`, `+`, `-` and
@@ -188,10 +195,13 @@ A diagnostic field that explicitly carries a pinned source uses the same
188
195
  constructor with pinned-source context: a recognised reference followed by `@`
189
196
  and a validated 40-hex-character commit can retain that commit in its display.
190
197
  If either part cannot be recognised, the whole source is withheld: pinned
191
- sources have no bounded plain-value fallback. Rendering an already constructed
192
- pinned source does not change it. This context does not change default
193
- reference rendering or admit a new source form. Local/file reference semantics
194
- and operational external-source values remain unchanged.
198
+ sources have no bounded plain-value fallback. `displayRepoRef` selects this
199
+ context with `pinned: true` for a complete `<ref>@<commit>` value, or with
200
+ `pinned: { ref, commit }` for its original components; both forms validate
201
+ both parts strictly. Rendering an already constructed pinned source does not
202
+ change it. Ordinary reference rendering does not infer a pin or admit a new
203
+ source form. Local/file reference semantics and operational external-source
204
+ values remain unchanged.
195
205
 
196
206
  The same decision applies to the selected reference in error messages,
197
207
  `details.ref`, `details.url`, `details.value`, `provenance.value`, nested
@@ -315,6 +325,16 @@ its capabilities unresolvable (`E_NOT_A_MEMBER` / `E_MEMBERSHIP_UNCONFIRMED`).
315
325
  Reading the workspace repo *is* being in the workspace — a workspace's access
316
326
  control is Git's.
317
327
 
328
+ **Git version failures preserve the remote cache.** Partial caches need Git
329
+ 2.45 or later. A successfully parsed older version causes OATS to rebuild a
330
+ partial cache with whole trees. If the version command fails, times out or
331
+ returns an unparseable version, the read instead fails with
332
+ `E_REMOTE_UNREADABLE` and an existing reason (`unknown` for unparseable
333
+ output, `timeout` for a timeout). The partial cache, its fetch mode and its
334
+ commit pins are preserved, and a later read can retry the version probe.
335
+ This also applies to library reads without a session. A cache already using
336
+ whole trees stays in that mode when a later probe finds a newer Git.
337
+
318
338
  **Repo-owned capabilities.** `private: true` in a capability's `oats.json`
319
339
  makes it **repo-owned**: it is listed like any other capability (with
320
340
  `private: true`; the human table marks it "(repo-owned)"), and it is usable
@@ -33,12 +33,13 @@
33
33
  * `oats automations refresh`, which the tick runs as a child when the snapshot is ten minutes
34
34
  * old), one list per kind, and the tick reads it. The run state stays local. */
35
35
  import { spawnSync } from "node:child_process";
36
- import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
36
+ import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
37
37
  import { dirname, join } from "node:path";
38
38
  import { recordLocalInput } from "./local-inputs.mjs";
39
39
  import YAML from "yaml";
40
40
  import { parseConfigData } from "./config-data.mjs";
41
41
  import { editLocal } from "./local-edit.mjs";
42
+ import { writeThroughPrivateFile } from "./write-through-private-file.mjs";
42
43
 
43
44
  export const AUTOMATIONS_API = 1;
44
45
  export const SNAPSHOT_MAX_AGE_MS = 10 * 60_000;
@@ -231,9 +232,7 @@ export function readSnapshot(dep) {
231
232
  export function writeSnapshot(dep, snap) {
232
233
  const file = snapshotPath(dep);
233
234
  mkdirSync(dirname(file), { recursive: true });
234
- const tmp = `${file}.tmp-${process.pid}`;
235
- writeFileSync(tmp, JSON.stringify(snap, null, 2) + "\n");
236
- renameSync(tmp, file);
235
+ writeThroughPrivateFile(file, `${file}.tmp-${process.pid}`, JSON.stringify(snap, null, 2) + "\n");
237
236
  return file;
238
237
  }
239
238
  /** The snapshot document of one discovery: one list per kind (`triggers`, `schedules`). */
@@ -24,3 +24,21 @@ export function readPortableBytes(path, { missingCode = "resource-not-found", in
24
24
  return buffer.subarray(0, count);
25
25
  } finally { closeSync(fd); }
26
26
  }
27
+
28
+ /** At most `max` bytes from the start of a regular file, and its size, through one descriptor: lstat must find a
29
+ * regular file, the open refuses a symlink (O_NOFOLLOW) and never blocks on a FIFO swapped in meanwhile
30
+ * (O_NONBLOCK), and the opened file must be the one lstat found. → { bytes, size } */
31
+ export function readFileHead(path, max) {
32
+ const stat = lstatSync(path);
33
+ if (!stat.isFile()) throw oatsError("invalid-declaration", "not a regular file");
34
+ const fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
35
+ try {
36
+ const opened = fstatSync(fd);
37
+ if (!opened.isFile() || opened.dev !== stat.dev || opened.ino !== stat.ino) throw oatsError("integrity-drift", "the file changed during opening");
38
+ const want = Math.min(opened.size, max);
39
+ const buffer = Buffer.alloc(want);
40
+ let count = 0, size;
41
+ while (count < want && (size = readSync(fd, buffer, count, want - count, count)) > 0) count += size;
42
+ return { bytes: buffer.subarray(0, count), size: opened.size };
43
+ } finally { closeSync(fd); }
44
+ }
@@ -26,6 +26,7 @@ import { posix } from "node:path";
26
26
  import YAML from "yaml";
27
27
  import { oatsError } from "./errors.mjs";
28
28
  import { bindRemote } from "./packages.mjs";
29
+ import { FILE_BUDGET } from "./remote.mjs";
29
30
  import { locatedContractWarnings } from "./capability-contract.mjs";
30
31
  import { capabilitySkills, lockedCapability, lockedPackageCapabilities, manifestFilePath, memberRef, unsafeRelPath } from "./resolve.mjs";
31
32
  import { memberRowByKey } from "./workspace.mjs";
@@ -80,6 +81,9 @@ export function cutUtf8(text, limit) {
80
81
  return bytes.length <= limit ? text : bytes.subarray(0, cutAt(bytes, limit)).toString("utf8");
81
82
  }
82
83
 
84
+ /** Codepoint order of two strings: the order of their UTF-8 bytes, which a skill's files are listed in. */
85
+ export const compareCodepoints = (a, b) => Buffer.compare(Buffer.from(a, "utf8"), Buffer.from(b, "utf8"));
86
+
83
87
  const FRONT_MATTER_RE = /^---[ \t]*\r?\n(?:([\s\S]*?)\r?\n)?---[ \t]*(?:\r?\n|$)/;
84
88
  /** The `description` of a SKILL.md's leading `---` YAML front matter (a string only), cut to DESCRIPTION_LIMIT
85
89
  * bytes; null when there is no front matter, it does not parse, or the key is absent or not a string. */
@@ -103,6 +107,13 @@ function skillText(bytes) {
103
107
  if (decodeText(bytes).binary) return null;
104
108
  return new TextDecoder("utf-8", { ignoreBOM: true }).decode(bytes);
105
109
  }
110
+ /** A SKILL.md is read for its description up to this many bytes, the remote read budget (FILE_BUDGET). */
111
+ export const SKILL_DOC_BUDGET = FILE_BUDGET;
112
+ /** A SKILL.md's description from its bytes (`size`: the file's size): null for a file over SKILL_DOC_BUDGET, which
113
+ * is not read whole, or a binary one. `capabilities show` and `inspect --soul --skills` both describe by it. */
114
+ export function skillDocDescription(bytes, size = bytes.length) {
115
+ return size > SKILL_DOC_BUDGET ? null : skillDescription(skillText(bytes));
116
+ }
106
117
 
107
118
  /** The catalog row a show reads: rows named `name`, narrowed by `--member <repoKey>` (a member row of that
108
119
  * repository) or `--package <id>` (that package's row). 0 → E_CAPABILITY_UNKNOWN; >1 → E_CAPABILITY_AMBIGUOUS. */
@@ -202,8 +213,8 @@ export async function capabilityShow(source, { remote, remoteOptions }) {
202
213
  for (const skill of listed.skills) {
203
214
  let description = null;
204
215
  try {
205
- const { bytes } = await r.readRemoteFile(ref, commit, posix.join(dir, skill.path, "SKILL.md"));
206
- description = skillDescription(skillText(bytes));
216
+ const { bytes, size } = await r.readRemoteFile(ref, commit, posix.join(dir, skill.path, "SKILL.md"));
217
+ description = skillDocDescription(bytes, size);
207
218
  } catch (e) { if (!isOatsError(e)) throw e; }
208
219
  skills.push({ name: skill.name, path: skill.path, description, files: skill.files, filesTruncated: skill.filesTruncated });
209
220
  }
package/lib/claim.mjs CHANGED
@@ -93,10 +93,11 @@
93
93
  * owner (a home's lifecycle claim: `action`, the holder's verb).
94
94
  * It is in the record that is linked, so the claim is never
95
95
  * seen without it; the owner's four fields win over it */
96
- import { linkSync, lstatSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
96
+ import { linkSync, lstatSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
97
97
  import { randomBytes } from "node:crypto";
98
98
  import { isStartToken, processLiveness, processStart } from "./worktree-hooks.mjs";
99
99
  import { NOTHING_ELSE, afterEndedSteps, asKernelError, nothingAfter } from "./errors.mjs";
100
+ import { writeThroughPrivateFile } from "./write-through-private-file.mjs";
100
101
 
101
102
  export const CLAIM_WAIT_MS = 3000;
102
103
  const CLAIM_MAX_DEPTH = 8;
@@ -337,9 +338,7 @@ export function releaseClaim(path, me) {
337
338
  /** Record (or, with null, clear) a step of the holding `me` in its claim `path`, for a takeover to
338
339
  * end (`endHolderStep`). Only the live holder writes its claim. */
339
340
  export function recordInClaim(path, me, step) {
340
- const tmp = `${path}.tmp-${process.pid}-${me.nonce}`;
341
- writeFileSync(tmp, JSON.stringify({ ...me, ...(step ?? {}) }) + "\n", { mode: 0o600 });
342
- renameSync(tmp, path);
341
+ writeThroughPrivateFile(path, `${path}.tmp-${process.pid}-${me.nonce}`, JSON.stringify({ ...me, ...(step ?? {}) }) + "\n", 0o600);
343
342
  }
344
343
 
345
344
  /** Remove the claim `path` when its holder is verifiably gone, through the takeover above, and