@awebai/oats 0.57.0 → 0.58.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 (60) hide show
  1. package/bin/oats.mjs +24 -11
  2. package/docs/configuration.md +19 -28
  3. package/docs/desktop-cli-api.md +38 -15
  4. package/docs/desktop.md +14 -0
  5. package/docs/execution-targets.md +10 -1
  6. package/docs/implementation.md +7 -1
  7. package/docs/integrations.md +3 -1
  8. package/docs/official-catalog.md +1 -1
  9. package/docs/packages.md +5 -5
  10. package/docs/release-notes/v0.57.1.md +275 -0
  11. package/docs/release-notes/v0.58.0.md +107 -0
  12. package/docs/servers.md +18 -0
  13. package/docs/souls-and-instances.md +9 -0
  14. package/docs/tui.md +224 -87
  15. package/docs/workspaces.md +1 -1
  16. package/lib/core.mjs +11 -4
  17. package/lib/session-viewer.mjs +29 -4
  18. package/package-catalog.json +1 -1
  19. package/package.json +1 -1
  20. package/packages/client/cli-adapter.mjs +9 -7
  21. package/packages/client/cli-locator.mjs +2 -2
  22. package/packages/client/composed-gate.mjs +34 -0
  23. package/packages/client/inspect-boundary.mjs +157 -0
  24. package/packages/client/inspect-cache.mjs +86 -0
  25. package/packages/client/keyed-catalog.mjs +132 -0
  26. package/packages/client/launch-view.mjs +46 -0
  27. package/packages/client/panel-views.mjs +1 -1
  28. package/packages/client/session-attach.mjs +7 -5
  29. package/packages/client/soul-catalog.mjs +77 -0
  30. package/packages/client/soul-colors.mjs +31 -0
  31. package/packages/client/soul-facts.mjs +85 -0
  32. package/packages/client/soul-rows.mjs +48 -0
  33. package/packages/client/spawn-apply-cli.mjs +19 -8
  34. package/packages/client/spawn-apply.mjs +216 -0
  35. package/packages/client/spawn-messages.mjs +131 -85
  36. package/packages/client/spawn-preview-cli.mjs +2 -1
  37. package/packages/client/spawn-preview-contract.mjs +3 -0
  38. package/packages/client/spawn-preview-facts.mjs +119 -0
  39. package/packages/client/spawn-preview.mjs +164 -0
  40. package/packages/client/spawn-transaction.mjs +136 -0
  41. package/packages/record/lib/directory-identity.mjs +14 -0
  42. package/packages/record/lib/native-history.mjs +6 -5
  43. package/packages/tui/README.md +32 -11
  44. package/packages/tui/lib/actions.mjs +10 -1
  45. package/packages/tui/lib/config.mjs +9 -14
  46. package/packages/tui/lib/main.mjs +165 -57
  47. package/packages/tui/lib/model.mjs +28 -24
  48. package/packages/tui/lib/panel.mjs +1019 -0
  49. package/packages/tui/lib/read.mjs +5 -14
  50. package/packages/tui/lib/store.mjs +77 -30
  51. package/packages/tui/lib/term/capture.mjs +260 -0
  52. package/packages/tui/lib/term/screen.mjs +44 -8
  53. package/packages/tui/lib/term/style.mjs +78 -6
  54. package/packages/tui/lib/term/text.mjs +24 -4
  55. package/packages/tui/lib/term/through.mjs +213 -0
  56. package/packages/tui/lib/term/tty.mjs +7 -60
  57. package/packages/tui/lib/views/frame.mjs +126 -40
  58. package/packages/tui/lib/views/help.mjs +12 -10
  59. package/skills/oats-getting-started/SKILL.md +3 -2
  60. package/packages/tui/lib/open.mjs +0 -45
package/docs/tui.md CHANGED
@@ -78,7 +78,7 @@ runs.
78
78
 
79
79
  ```
80
80
  oats acme-platform +1 machine 4 running 1 needs input 2 stopped
81
- 1 Instances 2 Souls 3 Capabilities read 14:03:27
81
+ Instances Souls Capabilities read 14:03:27
82
82
  ──────────────────────────────────────────────┬─────────────────────────────────────────────────
83
83
  This machine │ api-lead
84
84
  ▾ ● backend-lead claude │ soul tech-lead
@@ -91,7 +91,7 @@ runs.
91
91
  │
92
92
  ○ reviewer-api stopped │
93
93
  ──────────────────────────────────────────────┴─────────────────────────────────────────────────
94
- / filter Tab detail r refresh w workspaces ? help q quit
94
+ / filter Tab detail r refresh w workspaces 1-3 views ? help q quit
95
95
  ```
96
96
 
97
97
  - **The header** has the workspace's name, then what the view holds of
@@ -102,10 +102,14 @@ runs.
102
102
  every row of the view: instances running, instances that need input,
103
103
  stopped, state unknown, and rows the kernel reported that were withheld (a
104
104
  home outside its soul's directory, or one reported twice). A count of zero
105
- is left out. The second row names the views; `2 Souls` and
106
- `3 Capabilities` are dim because they cannot be opened yet. On the right
107
- is the time of the read of this machine that the screen shows: it moves
108
- with every read.
105
+ is left out. The second row names the views, `Instances Souls
106
+ Capabilities`: the open one is drawn in reverse video, and `Souls` and
107
+ `Capabilities` are dim because they cannot be opened yet. Their keys,
108
+ `1`, `2` and `3`, are not drawn beside the names: the help names each,
109
+ and the footer names the three as one hint, `1-3 views`, which a narrow
110
+ footer gives up right after the acts. `2` and `3` say what to run
111
+ instead. On the right is the time of the read
112
+ of this machine that the screen shows: it moves with every read.
109
113
  - **The list** is the roster the Desktop draws: the same groups in the same
110
114
  order, from the same code. An instance that others were spawned from
111
115
  comes first, and the ones below it are indented under it; instances
@@ -127,29 +131,9 @@ runs.
127
131
  branch, team, parent, when it last started, and its home. From 80
128
132
  columns up it stands beside the list; on a narrower terminal `Tab` opens
129
133
  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]`.
134
+ - **Opening an agent.** `Enter` on an instance that runs opens its terminal
135
+ beside the list, where the detail was: see
136
+ [Open an agent's terminal](#open-an-agents-terminal).
153
137
 
154
138
  **A view of more than one deployment** (this machine and another, or two
155
139
  deployments on one machine) is one list, grouped as the Desktop groups it:
@@ -238,6 +222,81 @@ The next read that succeeds shows the machines as they then report.
238
222
  Names are cut by terminal cells with `…` (`...` in ASCII) when they do not
239
223
  fit; the detail shows them whole.
240
224
 
225
+ ## Open an agent's terminal
226
+
227
+ ```
228
+ oats acme-platform 2 running
229
+ Instances Souls Capabilities read 14:03:27
230
+ ──────────────────────────────────────┬─────────────────────────────────────────
231
+ > ● backend-lead claude │ backend-lead
232
+ ● docs-writer claude │$ make docs
233
+ │Building the reference...
234
+ │
235
+ ──────────────────────────────────────┴─────────────────────────────────────────
236
+ C-\ back to the list
237
+ ```
238
+
239
+ - **`Enter` on an instance that runs** opens its terminal on the right of
240
+ the body, where the detail was, with the list on the left. Its top row
241
+ names the agent (and `on <machine>` for one of another machine); under it
242
+ is the agent's screen, as the agent draws it, in its own colours.
243
+ - **The terminal has the focus.** What you type, what you paste and every
244
+ key go to the agent exactly as typed, `Ctrl+C`, `Ctrl+Z`, `Esc` and `q`
245
+ among them, but for **the back key** (`Ctrl+\` unless
246
+ [`tui.json`](#change-the-keys-tuijson) names another). The back key gives
247
+ the focus to the list. While the terminal has the focus the footer names
248
+ only that key: `C-\ back to the list`. A back key inside a paste is
249
+ pasted, not taken.
250
+ - **With the list focused** the terminal stays open, and the agent's screen
251
+ is still drawn as it changes. The footer names the keys for it:
252
+ `Enter focus terminal` on its row, `z zoom` and `c close terminal`.
253
+ - `Enter` on the open terminal's row gives it the focus again.
254
+ - `z` gives it the focus and the whole body: the header and the footer
255
+ stay, the list is hidden. The back key brings the list back beside it.
256
+ - `c` closes it: the agent keeps running, and the right side is the
257
+ detail again.
258
+ - `Tab` shows the detail in its place until `Tab` or `Esc`. Nothing of
259
+ the terminal is drawn meanwhile, and its screen is read afresh when it
260
+ shows again.
261
+ - **One terminal is open at a time.** `Enter` on another instance that runs
262
+ closes the open one and opens that one.
263
+ - **Under 80 columns** the terminal is always shown with the whole body
264
+ when it has the focus. With the list focused the list is shown alone; the
265
+ terminal stays open, unseen, and `Enter focus terminal` in the footer
266
+ shows it again. Beside the list the terminal is never narrower than 40
267
+ columns.
268
+ - **A terminal also closes by itself** when its viewer ends: the agent's
269
+ window ended, its session went away, or the link to its machine dropped.
270
+ It closes within a second of that (tmux tells `oats tui` of a viewer's
271
+ end once a second), or a second more when tmux took a moment more to
272
+ have the viewer's exit status: once tmux has reported the viewer ended,
273
+ `oats tui` waits ten seconds at most for that status, and closes the
274
+ terminal without it when it has not come. The instances are then read again at once, and one line above the panes
275
+ says what happened: that it could not be opened, that the connection to
276
+ its machine ended, or that the viewer ended without saying why. What the
277
+ viewer printed on its error output stands under that line in quotation
278
+ marks, without saying who printed it: OATS, tmux and ssh all can. When
279
+ the viewer ended cleanly there is no line, and a terminal you closed
280
+ yourself says nothing. **A terminal is never opened again by itself**:
281
+ `Enter` opens it.
282
+ - **`Enter` on an instance that cannot be opened** opens nothing and says
283
+ why: it does not run, whether it runs is not known, or the detail's
284
+ reason holds it. An agent on another machine is asked first whether it
285
+ can be opened (`Esc` gives that up); a machine whose OATS cannot open its
286
+ sessions is said then.
287
+ - **No scrollback but the viewer's own, and no mouse.** The panel shows
288
+ what the agent's window shows now; what has scrolled away is reached as
289
+ the agent's own terminal reaches it.
290
+ - **How it works.** The terminal is the kernel's own viewer,
291
+ `oats session attach`, run in a pane of a tmux server private to this run
292
+ of `oats tui`: its socket is in a directory of the run's own (mode 0700,
293
+ under the system's temporary directory), it reads no tmux configuration
294
+ of yours, and it has no prefix key, no key binding and no status line.
295
+ `oats tui` reads that pane's screen when tmux says it changed, never on a
296
+ timer: an idle terminal costs no frame. Inside tmux nothing changes: the
297
+ agent opens in the TUI's panel, and `oats tui` makes no window and no
298
+ split in your tmux.
299
+
241
300
  ## The switcher
242
301
 
243
302
  `w` opens the switcher: what this run can show, over the whole body of the
@@ -406,8 +465,12 @@ The exit status never depends on it.
406
465
  | `/` | filter |
407
466
  | `r` | read now |
408
467
  | `1` | the Instances view |
468
+ | `2`, `3` | the Souls and Capabilities views: not in this version, so a line says what to run instead |
409
469
  | `w` | opens [the switcher](#the-switcher) |
410
- | `Enter` | in the list of instances, opens the selected agent's terminal; in the switcher, opens the selected row; in a confirmation, presses the button with the focus |
470
+ | `Enter` | in the list of instances, opens the selected agent's terminal beside the list, or gives it the focus when it is the open one; in the switcher, opens the selected row; in a confirmation, presses the button with the focus |
471
+ | `z` | gives the open terminal the focus and the whole body |
472
+ | `c` | closes the open terminal; the agent keeps running |
473
+ | `Ctrl+\` | while a terminal has the focus, the back key: the focus goes to the list ([`tui.json`](#change-the-keys-tuijson) can name another) |
411
474
  | `X`, `D`, `S`, `R` | stop, retire, start, restart the selected agent, [after a confirmation](#stopping-starting-restarting-and-retiring) |
412
475
  | `Left`/`Right`, `Tab`/`Shift+Tab` | in a confirmation, move between its buttons |
413
476
  | `Space` | in a confirmation, switches the plan's choice |
@@ -427,8 +490,9 @@ where it is, and the list returns to it at the next key that moves it.
427
490
 
428
491
  The help screen is generated from the table the program acts on, so it
429
492
  always lists the keys that work, with the marks and with what this version
430
- does not do. The movement keys scroll it. While `oats tui` has the screen,
431
- `Ctrl+\` does nothing.
493
+ does not do. The movement keys scroll it. While a terminal has the focus
494
+ the table's keys are the agent's: the back key alone is the TUI's. With the
495
+ list focused the back key does nothing.
432
496
 
433
497
  **The filter.** `/` opens a field on the last row. What you type narrows the
434
498
  list to the instances whose name, soul or repository contains it, with the
@@ -462,10 +526,12 @@ never writes it. With no file the keys are the ones above.
462
526
  do not name keeps its keys.
463
527
  - The actions are `up`, `down`, `top`, `bottom`, `page-up`, `page-down`,
464
528
  `collapse`, `expand`, `detail`, `filter`, `refresh`, `instances`,
465
- `workspaces`, `open`, `help`, `close`, `quit`, `suspend` and `redraw`.
466
- `workspaces` (`w`) opens the switcher and `open` (`enter`) opens the
467
- selected agent's terminal in the list of instances and the selected row
468
- in the switcher. In an open filter field `Enter` keeps the filter,
529
+ `souls`, `capabilities`, `workspaces`, `open`, `zoom`, `close-terminal`,
530
+ `stop`, `retire`, `start`, `restart`, `help`, `close`, `quit`, `suspend`
531
+ and `redraw`. `workspaces` (`w`) opens the switcher and `open` (`enter`)
532
+ opens the selected agent's terminal in the list of instances and the
533
+ selected row in the switcher. `zoom` (`z`) and `close-terminal` (`c`) act
534
+ on the open terminal. In an open filter field `Enter` keeps the filter,
469
535
  whatever key `open` has.
470
536
  - A key is written as the help shows it, in lower case: `q`, `G`, `?`,
471
537
  `space`, `enter`, `tab`, `escape`, `backspace`, `up`, `pageup`, `f5`,
@@ -474,12 +540,15 @@ never writes it. With no file the keys are the ones above.
474
540
  and `Ctrl+M` as `backspace`, `tab` and `enter`, so those four are not
475
541
  keys of their own.
476
542
  - `ascii: true` is `--ascii`.
477
- - `open.detachKey` is the key that leaves an agent's terminal, written as
478
- `oats session attach --detach-key` takes it: `C-\` when you name none.
479
- [Execution targets](execution-targets.md) has the keys that can be chosen.
480
- `oats tui` does not check it: a key OATS refuses is said when you open an
481
- agent. A key that tmux's copy mode binds leaves the viewer once that mode
482
- is left.
543
+ - `open.detachKey` is **the back key**: the key that takes the focus from
544
+ an agent's terminal back to the list, `C-\` when you name none. It is
545
+ `oats tui`'s own and never reaches the agent or the kernel. It is one of
546
+ these, written as shown: `C-` with a letter but `h`, `i` and `m` (a
547
+ terminal sends those as `Backspace`, `Tab` and `Enter`) or one of `\`
548
+ `]` `^` `_`; `M-` with a lower-case letter or a digit; or `F1` to `F12`,
549
+ alone or with one of `C-`, `M-`, `S-` (`C-F5`). These are the keys a
550
+ `tui.json` written for an earlier version could name, with the same
551
+ meaning for the key.
483
552
 
484
553
  **A file it cannot honour stops the start.** Each problem is one line on
485
554
  stderr, the status is 1 and nothing is drawn; it resolves no conflict and
@@ -492,9 +561,7 @@ guesses nothing. It refuses:
492
561
  | is not one JSON object | `it is not valid JSON`, `it is not one JSON object` |
493
562
  | 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` |
494
563
  | has a member of `open` other than `detachKey` | `unknown member … of open; open has detachKey` |
495
- | gives `open.detachKey` something that is not 1 to 16 printable ASCII characters | `open.detachKey must be 1 to 16 printable ASCII characters` |
496
- | gives `open.detachKey` a value that begins with `-` | `open.detachKey cannot begin with -` |
497
- | 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` |
564
+ | gives `open.detachKey` anything but one of the keys above | `open.detachKey must be one key: …`, with the keys it can be |
498
565
  | names `open-workspace`, the action's name before it became `open` | `open-workspace is called open now; rename it` |
499
566
  | names an action that does not exist | `unknown action …`, with the list of actions |
500
567
  | gives an action something that is not a list of strings | `… must be a list of key ids` |
@@ -552,16 +619,61 @@ with the Desktop (`packages/client/`).
552
619
  `oats-local.yaml`. An entry that is a link is not followed. When a folder
553
620
  is opened, that one directory is asked again.
554
621
  - **Opening an agent runs one more command,** `oats session attach --home
555
- <home> --detach-key <key>`, by the same kernel, with your terminal as its
556
- terminal. For an agent on another machine `oats session inspect --server
557
- <id> --home <home> --json` is asked first (20 seconds), then `oats session
558
- attach --server <id> --home <home> --detach-key <key>`. Nothing is read
559
- while the agent has the terminal, and the return reads at once.
622
+ <home>`, by the same kernel, in a pane of the run's private tmux server
623
+ ([above](#open-an-agents-terminal)), with no key of its own. For an agent
624
+ on another machine `oats session inspect --server <id> --home <home>
625
+ --json` is asked first (20 seconds), then `oats session attach --server
626
+ <id> --home <home>`. The reads go on while a terminal is open, and the end
627
+ of a viewer reads at once.
628
+ - **The private tmux server** is `tmux` found on `PATH`, 3.2 or later. It
629
+ is started at the first open of a run, with `-f /dev/null` and the
630
+ environment's `TMUX` and `TMUX_PANE` removed, and its socket in the run's
631
+ own directory. The control client that `oats tui` keeps for the run
632
+ starts it, with `exit-unattached` set in the same command. Its first window is a keeper: it
633
+ watches `alive`, a FIFO in the run's directory (0600, made with the
634
+ system's `mkfifo`) that `oats tui` holds open for writing until it ends.
635
+ When `oats tui` is gone, whatever ended it and at any moment, the keeper
636
+ kills the server. The keeper needs two things from the base system,
637
+ found on `PATH` like `tmux`.
638
+ - **`mkfifo`** makes `alive`. Without it an open is refused: the line
639
+ says the terminal could not be opened, with what was said under it.
640
+ - **A way to tell that the server is still its parent.** The keeper reads
641
+ that from `/proc` where the system has one (Linux), and otherwise asks
642
+ `ps -o ppid= -p` (macOS). With neither (no `/proc`, and no `ps` or one
643
+ that refuses `-p`, like BusyBox's), the keeper kills nothing. A normal
644
+ end is not affected. An `oats tui` killed with SIGKILL can then leave
645
+ its private server running, with the open terminal's viewer still
646
+ attached to the agent, until you end it with `tmux -S
647
+ <run directory>/tmux kill-server`. The next run's sweep leaves that
648
+ directory alone while its socket answers.
649
+
650
+ Each open is a window of the server, whose process is the viewer itself,
651
+ with no shell between them. It is closed with `kill-pane`, which hangs up
652
+ the viewer's terminal: the viewer gets SIGHUP at once and removes its own
653
+ session on the agents' server. The viewer's error output goes to a file
654
+ of the run's directory (0600), read back when it ends and deleted. Its
655
+ exit status is the one tmux keeps for a pane whose process ended
656
+ (`remain-on-exit`), which the server reports to `oats tui` within a
657
+ second; `oats tui` then closes that pane. tmux can report a pane ended
658
+ before it has that status (3.4 does, when the viewer's terminal hangs up a
659
+ moment before its process is reaped): `oats tui` then waits for the
660
+ status, which follows at the next report, for ten seconds at most (2.5
661
+ on tmux 3.2, which never says which signal ended a pane). A pane whose
662
+ status has not come by then is taken as ended without one, and closed:
663
+ the terminal closes with the line that the viewer ended without saying
664
+ why. What the terminal
665
+ shows is captured into `capture` in that directory, which the server
666
+ writes and `oats tui` reads back, so nothing an agent prints passes
667
+ through the stream on which `oats tui` reads the server's answers. An
668
+ answer the server would never give ends that stream, and the open
669
+ terminal closes with it. The server is ended
670
+ on every way out a process can handle. At its start a run also removes
671
+ what a run that is gone left (below), and nothing else: it signals
672
+ nothing.
560
673
  - **Every read runs in a session of its own** and is ended when the TUI
561
674
  ends, on every way out a process can handle (for SIGKILL see
562
- [below](#what-it-changes-in-your-terminal-and-restores)). The viewer
563
- shares your terminal, and is ended first when `oats tui` is ended while an
564
- agent has the terminal. A read that was
675
+ [below](#what-it-changes-in-your-terminal-and-restores)). An open
676
+ terminal's viewer ends with the private server. A read that was
565
677
  running when the TUI is suspended is dropped, not shown: its answer could
566
678
  arrive cut. That holds for the read of the other machines too. The return
567
679
  reads again.
@@ -582,7 +694,14 @@ with the Desktop (`packages/client/`).
582
694
  apply's answer for 10 minutes and for a start's for 60 seconds; then it
583
695
  says so, and the change goes on.
584
696
  - It runs no other command that changes a deployment or a registration, and
585
- it writes no other file.
697
+ it writes no other file but the private server's: its socket `tmux`, the
698
+ keeper's FIFO `alive`, `capture` (the open terminal's screen, which the
699
+ server writes there for `oats tui` to read), and `owner.json` (`{ "tool":
700
+ "oats-tui", "pid": …, "started": … }`), which lets a later run tell a
701
+ directory a run that is gone left. A run that ends normally removes all
702
+ four. A later run removes such a directory, these four files included, when its `pid` is not alive
703
+ and its socket answers no tmux; it looks only at directories named `oats-tui-*` in the
704
+ system's temporary directory, yours, of mode 0700, holding that file.
586
705
 
587
706
  ## What this version does not do
588
707
 
@@ -612,7 +731,8 @@ version:
612
731
  names the machine (`on garnet`) and carries the time.
613
732
  - Souls and Capabilities, when they come, are this machine's.
614
733
  - There is no sorting and no mouse, and a deployment's heading cannot be
615
- folded.
734
+ folded. An open terminal has no scrollback but the viewer's own.
735
+ - One terminal is open at a time; tabs of several come in a later version.
616
736
  - With an OATS older than 0.52.0, after an interrupted stop the instance can
617
737
  be started and then cannot be stopped while `.oats-stop-pending.json` exists
618
738
  in its home.
@@ -630,6 +750,17 @@ This is the complete list. On start, in this order:
630
750
  On the way out, the reverse: bracketed paste off, autowrap on, the style
631
751
  reset (`CSI 0m`), the cursor shown, the alternate screen left, raw mode off.
632
752
 
753
+ While it draws:
754
+
755
+ - **every frame is one synchronized update**: it begins with
756
+ `CSI ?2026h` and ends with `CSI ?2026l`, so a terminal that knows the
757
+ mode shows the frame whole and one that does not ignores it. The mode is
758
+ set and reset inside each frame and is never left on; a frame with
759
+ nothing to change writes nothing;
760
+ - **while an agent's terminal has the focus the cursor is shown**
761
+ (`CSI ?25h`) where the agent's is, when the agent shows one, and hidden
762
+ again (`CSI ?25l`) when the focus leaves it.
763
+
633
764
  Two of these have a reason worth stating:
634
765
 
635
766
  - **Autowrap is off** so that no row can wrap when your terminal and the
@@ -656,15 +787,11 @@ It stops the whole foreground process group, as a `Ctrl+Z` does for any
656
787
  other program, so `oats tui` started through a wrapper (`sh -c`, `npx`)
657
788
  suspends as one job.
658
789
 
659
- **While an agent has the terminal** `oats tui` has put the terminal back in
660
- full, as for a suspend, and draws nothing. The viewer is OATS's own: it sets
661
- what it needs, the mouse for scrolling among it, and puts that back when it
662
- ends. Then `oats tui` sets its modes again. A SIGQUIT does not end
663
- `oats tui` while an agent has the terminal (a second `Ctrl+\`, pressed as the
664
- viewer leaves, is that signal). SIGINT, SIGTERM and SIGHUP end the viewer
665
- first and then `oats tui`, with the status of the table above. A viewer
666
- that has not ended 3 seconds after it was asked, or at a second signal, is
667
- left as it is, and `oats tui` ends without it.
790
+ **While an agent's terminal is open** the terminal stays `oats tui`'s: the
791
+ viewer draws into the private server's pane, never into your terminal, and
792
+ `oats tui` draws what that pane shows. Every way out in the table above ends
793
+ the private server and with it the viewer, with that status. A suspend
794
+ leaves the server and its viewer running; `fg` draws the terminal afresh.
668
795
 
669
796
  `Ctrl+C` is the quit key: in raw mode the terminal sends it as a byte, not as
670
797
  a signal, so it answers 0. A SIGINT sent from outside (`kill -INT`) answers
@@ -677,20 +804,28 @@ on tmux 3.7c, `reset` brought back the cursor and autowrap, and the pane
677
804
  stayed in the alternate screen until `tput rmcup`. Nothing else is left in
678
805
  tmux: `oats tui` creates no session, window, option or key binding.
679
806
  Nor can it end a read after SIGKILL: nothing of the TUI runs any more, so a
680
- read that was in flight runs to its own end. After a SIGKILL while an agent
681
- has the terminal, the viewer still has it: leave it with the key and you are
682
- in your shell.
807
+ read that was in flight runs to its own end. An open terminal's private
808
+ server is ended by its keeper as soon as `oats tui` is gone, so the viewer's
809
+ terminal hangs up and the viewer removes its own session. A stopped `oats tui`
810
+ (`Ctrl+Z`, SIGSTOP) still holds the keeper's FIFO, so its server is left
811
+ alone. The next run removes the directory that is left, with its `tmux`,
812
+ `alive`, `capture` and `owner.json`.
683
813
 
684
814
  ## What it never does
685
815
 
686
816
  - It switches on **no mouse reporting, no focus reporting, no keyboard
687
- protocol, no keypad or cursor-key mode and no synchronized output**.
817
+ protocol and no keypad or cursor-key mode**, and leaves no synchronized
818
+ update on between frames.
688
819
  - It writes **no window title, no clipboard sequence, no bell**, and no query
689
820
  that expects the terminal to reply.
690
- - It uses **only your terminal's own sixteen colours** and bold, dim,
691
- underline and reverse: no 256-colour or RGB value and no background fill,
692
- so your theme stays the theme. With `NO_COLOR` set and not empty it uses no
693
- colour at all. Nothing is told by colour alone.
821
+ - **Its own words and marks use only your terminal's own sixteen colours**
822
+ and bold, dim, underline and reverse: no 256-colour or RGB value and no
823
+ background fill, so your theme stays the theme. An open terminal shows
824
+ the agent's screen in the agent's own colours (256-colour and RGB
825
+ included) and attributes: those are the agent's. With `NO_COLOR` set and
826
+ not empty it uses no colour at all, the agent's included; the agent's
827
+ bold, underline, reverse and the like stay. Nothing is told by colour
828
+ alone.
694
829
  - It draws its rules and marks in UTF-8 when `LC_ALL`, else `LC_CTYPE`, else
695
830
  `LANG` names UTF-8, and in ASCII otherwise or with `--ascii`. No icon font,
696
831
  no emoji. When the locale is not UTF-8, a character outside ASCII in text
@@ -706,23 +841,25 @@ in your shell.
706
841
  shared home's (`packages/client/`), and the TUI writes none of its own
707
842
  for a speaker. They never stand before a withheld text: a reason that is
708
843
  withheld is `[withheld]` alone.
709
- - It changes nothing in tmux itself: no option, key binding, server,
710
- session, window or pane. Its probe only lists panes. An agent's own
711
- session is started, ended or restarted only by the kernel's commands of
712
- an act you confirmed
844
+ - It changes nothing in your tmux or the agents': no option, key binding,
845
+ server, session, window or pane. Its probe only lists panes. An agent's
846
+ own session is started, ended or restarted only by the kernel's commands
847
+ of an act you confirmed
713
848
  ([above](#stopping-starting-restarting-and-retiring)), and an agent's
714
849
  terminal is opened by `oats session attach`, which makes its own viewer
715
- session on the agents' tmux server and removes it; `oats tui` builds no
716
- viewer and runs no tmux command for either.
717
- - It starts no daemon, opens no socket and writes no file but the output of
718
- a change, in its own directory ([above](#what-it-reads-and-what-it-runs)).
719
- The processes it starts are the reads above, when you open an agent the
720
- viewer, and the acts you confirm. No read and no viewer outlives it on
721
- every way out a process can handle, except a viewer that does not end
722
- when asked (see [above](#what-it-changes-in-your-terminal-and-restores));
723
- after SIGKILL a read in flight runs to its own end, and a viewer stays
724
- until you leave it. An act you confirmed is never ended by `oats tui`: it
725
- runs to its own end.
850
+ session on the agents' tmux server and removes it. The one tmux server
851
+ `oats tui` runs is its own private one
852
+ ([above](#open-an-agents-terminal)), and it never looks at another's
853
+ socket but to ask whether a dead run's still answers.
854
+ - It starts no daemon, and writes no file but the output of a change and
855
+ its private server's own, in its own directory
856
+ ([above](#what-it-reads-and-what-it-runs)). The processes it starts are
857
+ the reads above, when you open an agent its private tmux server and the
858
+ viewer in it, and the acts you confirm. No read, server or viewer
859
+ outlives it on every way out a process can handle; after SIGKILL a read
860
+ in flight runs to its own end, and the private server and its viewer end
861
+ by themselves. An act you confirmed is never ended by `oats tui`: it runs
862
+ to its own end.
726
863
 
727
864
  ## Errors
728
865
 
@@ -54,7 +54,7 @@ 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.2 # bare version → resolves through the official catalog
57
+ oats.framework: v1.12.0 # bare version → resolves through the official catalog
58
58
  oats.okf: v5.2.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
 
package/lib/core.mjs CHANGED
@@ -43,6 +43,7 @@ import { recordLocalInput } from "./local-inputs.mjs";
43
43
  import { createHash, randomUUID } from "node:crypto";
44
44
  import { fileURLToPath } from "node:url";
45
45
  import { initializeNativeHistory, prepareNativeStart } from "../packages/record/lib/native-history.mjs";
46
+ import { sameDirectory } from "../packages/record/lib/directory-identity.mjs";
46
47
  import { noteRuntimeName } from "./deprecation.mjs";
47
48
  import { attachSessionTarget, requireDetachKey } from "./session-viewer.mjs";
48
49
  import { inspectSessionTarget, inputSessionTarget } from "./session-input.mjs";
@@ -1442,8 +1443,9 @@ export const HARNESS_PACKAGE_MANAGERS = {
1442
1443
  list: (env = process.env, opts = {}) => {
1443
1444
  let out;
1444
1445
  try {
1446
+ // DISABLE_TELEMETRY: this listing alone skips Claude's telemetry flush at exit (~0.4 s), same answer; never a launch's (it turns channels off).
1445
1447
  out = probeExecFile(HARNESS_PACKAGE_MANAGERS.claude.bin(opts), ["plugin", "list", "--json"],
1446
- { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 60000, env });
1448
+ { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 60000, env: { ...env, DISABLE_TELEMETRY: "1" } });
1447
1449
  } catch { return []; }
1448
1450
  let rows;
1449
1451
  try { rows = JSON.parse(out); } catch { return []; }
@@ -5468,6 +5470,12 @@ function directoryIdentity(path) {
5468
5470
  const st = lstatSync(path);
5469
5471
  return { dev: st.dev, ino: st.ino };
5470
5472
  }
5473
+ /** A directory-mode root as the spawn baseline records it: its identity and its birth time,
5474
+ * a decimal string of ns (JSON holds no BigInt), which sameDirectory reads on darwin. */
5475
+ function directoryRootIdentity(path) {
5476
+ const st = lstatSync(path, { bigint: true });
5477
+ return { dev: Number(st.dev), ino: Number(st.ino), birthtimeNs: String(st.birthtimeNs) };
5478
+ }
5471
5479
 
5472
5480
  // Read independently of mutable instance bytes, BEFORE realpath(home), hooks,
5473
5481
  // lock creation or backend observation. A metadata mode edit cannot disable it.
@@ -5481,8 +5489,7 @@ function sessionDirectoryGuard(home) {
5481
5489
  if (baseline.version !== RETIRE_BASELINE_VERSION || !receiptRecordsHome(baseline, receiptHomeIdentity(home))) throw oatsError("E_WORK_INSPECTION_FAILED", "invalid independent directory home authority");
5482
5490
  assertDirectoryRoots(home, expected);
5483
5491
  for (const [name, path] of [["home", home], ["work", join(home, "work")]]) {
5484
- const actual = directoryIdentity(path), recorded = baseline.directoryRoots?.[name];
5485
- if (!recorded || actual.dev !== recorded.dev || actual.ino !== recorded.ino) throw oatsError("E_WORK_INSPECTION_FAILED", `directory ${name} was exchanged; restore the owned root before retrying start`);
5492
+ if (!sameDirectory(baseline.directoryRoots?.[name], directoryRootIdentity(path))) throw oatsError("E_WORK_INSPECTION_FAILED", `directory ${name} was exchanged; restore the owned root before retrying start`);
5486
5493
  }
5487
5494
  }
5488
5495
  let meta;
@@ -6426,7 +6433,7 @@ function writeRetirementBaseline(home, work, mode, capabilities, runtime, { excl
6426
6433
  version: RETIRE_BASELINE_VERSION,
6427
6434
  digestVersion: BASELINE_DIGEST_VERSION,
6428
6435
  ...(incarnationId ? { incarnationId, executionBinding } : {}),
6429
- ...(mode === "directory" ? { directoryWork: true, directoryRoots: { home: directoryIdentity(home), work: directoryIdentity(work) } } : {}),
6436
+ ...(mode === "directory" ? { directoryWork: true, directoryRoots: { home: directoryRootIdentity(home), work: directoryRootIdentity(work) } } : {}),
6430
6437
  home: canonicalHomePath(home),
6431
6438
  homeFingerprint: storedTreeDigest(home, BASELINE_DIGEST_VERSION, { excludeRoot: resolveHomeExclusions(home, disposableHome).excludeRoot, instanceHome: true }),
6432
6439
  disposableReceipts,
@@ -54,8 +54,12 @@ export function prepareSessionViewer(target, { exec = execFileSync, detachKey }
54
54
  if (!inspectSessionTarget(target, { exec }).present) throw new Error("session no longer exists");
55
55
  // UTF-8 mode (-u) like the shared session helper: a service without a
56
56
  // UTF-8 locale (launchd) otherwise mangles tmux output.
57
+ // Each call in a session and process group of its own (`detached`): a hang-up, termination or
58
+ // interrupt sent to the attach's group (a pty hang-up once a wrapping shell has died, a C-c)
59
+ // must not kill a call in flight, the cleanup's kill-session first of all (#1243). The client the
60
+ // attach spawns is not one of these: it stays in the terminal's foreground group.
57
61
  const run = (args) => exec("tmux", ["-u", "-S", target.socket, ...args], {
58
- encoding: "utf8", timeout: 10000, stdio: ["ignore", "pipe", "pipe"],
62
+ encoding: "utf8", timeout: 10000, stdio: ["ignore", "pipe", "pipe"], detached: true,
59
63
  }).trim();
60
64
  const viewer = `oatsview-${process.pid}-${randomUUID().slice(0, 8)}`;
61
65
  // A keyed viewer reads a table of its own, named as its session: a binding in the locked table
@@ -80,6 +84,10 @@ export function prepareSessionViewer(target, { exec = execFileSync, detachKey }
80
84
  // Session-scoped on the temporary viewer: the agents' own session and
81
85
  // the operator's tmux settings are untouched.
82
86
  run(["set-option", "-t", viewer, "status", "off"]);
87
+ // When the agent's window ends (a retire), the viewer has no window left and tmux destroys it.
88
+ // The viewer's client must then leave, not be moved: under an operator's `detach-on-destroy off`
89
+ // tmux would switch it to another session, another agent's terminal (#1237).
90
+ run(["set-option", "-t", viewer, "detach-on-destroy", "on"]);
83
91
  run(["unbind-key", "-a", "-q", "-T", table]);
84
92
  for (const binding of MOUSE_BINDINGS) run(["bind-key", "-T", table, ...binding]);
85
93
  // The key is its own argv element, after the grammar admitted it.
@@ -126,17 +134,32 @@ function holdQuit() {
126
134
  * SESSION_DETACHED_EXIT when `detachKey` was given and ended the attach. */
127
135
  export async function attachSessionTarget(target, { detachKey } = {}) {
128
136
  if (detachKey !== undefined) { requireDetachKey(detachKey); holdQuit(); }
129
- const viewer = prepareSessionViewer(target, { detachKey });
137
+ // HUP, TERM and INT are held from before the viewer session exists until its cleanup has
138
+ // finished: one that arrives in between, early or late, finds a listener and not the default
139
+ // action, which would end Node with the session left on the agents' server (#1243). Node runs
140
+ // the listener only between synchronous runs, so it may find no viewer yet, or no client.
141
+ let viewer = null;
130
142
  let child;
143
+ let stopped = false;
131
144
  let quit = false;
132
- const stop = () => { viewer.cleanup(); child?.kill(); };
145
+ const stop = () => { stopped = true; viewer?.cleanup(); child?.kill(); };
133
146
  const signals = ["SIGHUP", "SIGTERM", "SIGINT"];
134
147
  for (const sig of signals) process.on(sig, stop);
148
+ // A preparation that fails has already removed what it made.
149
+ try { viewer = prepareSessionViewer(target, { detachKey }); }
150
+ catch (e) { for (const sig of signals) process.removeListener(sig, stop); throw e; }
135
151
  // Until the client has exited, a QUIT stops the attach as the other signals do, with status 1.
136
152
  // Unless the key's binding has already run: then the client is on its way out, the QUIT is the
137
153
  // key pressed again, and the attach ends as a detach.
138
154
  if (detachKey !== undefined) onQuit = () => { if (viewer.detached()) return; quit = true; stop(); };
139
155
  try {
156
+ // A signal received during the synchronous preparation is dispatched only in a poll phase of
157
+ // the event loop. Two setImmediate hops run at least one, wherever this attach was called
158
+ // from, so such a signal stops the attach here, before a client takes the terminal: one loop
159
+ // turn per attach. Stopped by then, the viewer ended without the key, and with no client to
160
+ // set the marker a keyed viewer answers 0 too; a QUIT answers 1, as it does with a client.
161
+ for (let hop = 0; hop < 2; hop++) await new Promise((resolve) => setImmediate(resolve));
162
+ if (stopped) return quit ? 1 : 0;
140
163
  const code = await new Promise((resolve, reject) => {
141
164
  child = spawn(viewer.binary, viewer.args, { env: viewer.env, stdio: "inherit" });
142
165
  child.once("error", reject);
@@ -148,7 +171,9 @@ export async function attachSessionTarget(target, { detachKey } = {}) {
148
171
  // The client has exited (or never started): a QUIT from here on changes nothing. One that
149
172
  // arrives during the calls below waits for them, so cleanup completes and the status stands.
150
173
  onQuit = null;
151
- for (const sig of signals) process.removeListener(sig, stop);
152
174
  viewer.cleanup();
175
+ // Only now: a HUP, TERM or INT that arrived during the cleanup was taken by the listener, and
176
+ // its calls, in groups of their own, ran to the end. The status stands.
177
+ for (const sig of signals) process.removeListener(sig, stop);
153
178
  }
154
179
  }
@@ -43,7 +43,7 @@
43
43
  },
44
44
  "oats.framework": {
45
45
  "url": "https://github.com/awebai/oats.git",
46
- "ref": "oats-framework/v1.10.2",
46
+ "ref": "oats-framework/v1.12.0",
47
47
  "path": "oats-package"
48
48
  }
49
49
  },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@awebai/oats",
3
- "version": "0.57.0",
3
+ "version": "0.58.0",
4
4
  "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
5
5
  "keywords": [
6
6
  "agents",