@awebai/oats 0.58.0 → 0.59.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 (53) hide show
  1. package/bin/oats.mjs +1 -1
  2. package/docs/desktop-cli-api.md +68 -3
  3. package/docs/desktop.md +30 -3
  4. package/docs/execution-targets.md +11 -0
  5. package/docs/implementation.md +2 -0
  6. package/docs/integrations.md +2 -2
  7. package/docs/knowledge.md +4 -4
  8. package/docs/official-catalog.md +4 -4
  9. package/docs/packages.md +14 -14
  10. package/docs/release-notes/v0.59.0.md +288 -0
  11. package/docs/servers.md +4 -1
  12. package/docs/souls-and-instances.md +21 -0
  13. package/docs/tui.md +644 -118
  14. package/docs/workspaces.md +2 -2
  15. package/lib/core.mjs +216 -42
  16. package/lib/read-ahead-worker.mjs +119 -0
  17. package/lib/read-ahead.mjs +115 -0
  18. package/lib/retire-state.mjs +33 -0
  19. package/lib/servers.mjs +9 -1
  20. package/lib/session-input.mjs +14 -4
  21. package/package-catalog.json +3 -3
  22. package/package.json +1 -1
  23. package/packages/client/cli-locator.mjs +2 -2
  24. package/packages/client/deployment-data.mjs +4 -0
  25. package/packages/client/deployment-panel.mjs +3 -0
  26. package/packages/client/instance-acts.mjs +23 -8
  27. package/packages/client/instance-presentation.mjs +3 -2
  28. package/packages/client/instance-tree.mjs +84 -39
  29. package/packages/client/lifecycle-confirmation.mjs +9 -3
  30. package/packages/client/remote-roster.mjs +4 -1
  31. package/packages/client/retire-in-flight.mjs +65 -0
  32. package/packages/client/retire-state.mjs +30 -0
  33. package/packages/client/spawn-apply.mjs +13 -4
  34. package/packages/tui/README.md +23 -10
  35. package/packages/tui/lib/actions.mjs +63 -5
  36. package/packages/tui/lib/client.mjs +12 -1
  37. package/packages/tui/lib/config.mjs +7 -2
  38. package/packages/tui/lib/main.mjs +315 -82
  39. package/packages/tui/lib/model.mjs +523 -56
  40. package/packages/tui/lib/panel.mjs +436 -125
  41. package/packages/tui/lib/read.mjs +52 -26
  42. package/packages/tui/lib/store.mjs +908 -65
  43. package/packages/tui/lib/term/keys.mjs +9 -2
  44. package/packages/tui/lib/term/text.mjs +4 -0
  45. package/packages/tui/lib/term/through.mjs +12 -1
  46. package/packages/tui/lib/views/frame.mjs +394 -95
  47. package/packages/tui/lib/views/help.mjs +54 -13
  48. package/packages/tui/lib/views/instances.mjs +43 -25
  49. package/packages/tui/lib/views/palette.mjs +61 -0
  50. package/packages/tui/lib/views/souls.mjs +268 -0
  51. package/packages/tui/lib/views/spawn.mjs +299 -0
  52. package/packages/tui/lib/views/split.mjs +29 -0
  53. package/skills/oats-getting-started/SKILL.md +2 -2
package/docs/tui.md CHANGED
@@ -12,12 +12,14 @@ 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, opens an agent's
16
- terminal, and stops, starts, restarts and retires an agent after a
17
- confirmation.** The registered machines are the ones `oats server list`
18
- names. It follows the instances as they start, stop and wait for you. It
19
- cannot spawn an agent, start one with another harness or model, or add,
20
- check or remove a machine: [what it does not do
15
+ other machines registered on this machine, in one list, opens agents'
16
+ terminals as tabs, in one group or two ([Splits](#splits)), spawns an agent
17
+ on this machine, and stops, starts, restarts
18
+ and retires an agent after a confirmation.** The registered machines are
19
+ the ones `oats server list` names. It follows the instances as they
20
+ start, stop and wait for you. It cannot spawn an agent on another machine
21
+ or with another harness, model or task, start one with another harness or
22
+ model, or add, check or remove a machine: [what it does not do
21
23
  yet](#what-this-version-does-not-do) names the `oats` command for each.
22
24
  - **Its screens and its configuration file may change without notice** while
23
25
  it is a preview.
@@ -77,24 +79,24 @@ runs.
77
79
  ## What it shows
78
80
 
79
81
  ```
80
- oats acme-platform +1 machine 4 running 1 needs input 2 stopped
81
- Instances Souls Capabilities read 14:03:27
82
- ──────────────────────────────────────────────┬─────────────────────────────────────────────────
83
- This machine │ api-lead
84
- ▾ ● backend-lead claude │ soul tech-lead
85
- ● backend-dev-auth claude !│ machine garnet
86
- │ state running
87
- ○ docs-writer stopped │ harness claude, claude-opus-5-5 (soul)
88
- garnet read 14:03:21 │ work worktree, agents/api-lead
89
- >▾ ● api-lead claude │ home …agents/tech-lead/instances/api-lead
90
- ● api-dev-export claude │
91
- │
92
- ○ reviewer-api stopped │
93
- ──────────────────────────────────────────────┴─────────────────────────────────────────────────
94
- / filter Tab detail r refresh w workspaces 1-3 views ? help q quit
82
+ fixture 3 stopped
83
+ Instances Souls Capabilities read 20:02:02
84
+ ──────────────────────────────────────┬─────────────────────────────────────────
85
+ > ■ dev ·2 │ dev
86
+ ■ reviewer ·1 │ dev fixture soul.
87
+ │ from ws
88
+ │ works works in directory
89
+ │ harness
90
+ │ Harness Pi
91
+ │ Model Pi's default model
92
+ │ Chosen by no preference set: the
93
+ │ host default
94
+ │ instances here
95
+ │ ○ alpha ○ beta
96
+ │ i shows them in the Instances view.
95
97
  ```
96
98
 
97
- - **The header** has the workspace's name, then what the view holds of
99
+ - **The header** starts with the workspace's name, then what the view holds of
98
100
  other machines, then the counts. Beside a deployment of this machine the
99
101
  other machines are counted: `+1 machine`, `+2 machines`. A view that holds
100
102
  no deployment of this machine names its one machine, `on garnet`, or
@@ -103,19 +105,34 @@ runs.
103
105
  stopped, state unknown, and rows the kernel reported that were withheld (a
104
106
  home outside its soul's directory, or one reported twice). A count of zero
105
107
  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.
108
+ Capabilities`, the open one drawn in reverse video. `1`, `2` and `3`
109
+ open them in the list, and [the leader](#the-leader) then `1`, `2` or `3`
110
+ from anywhere; the leader's hint, [the palette](#the-palette) and the
111
+ help name those keys. [The Souls view](#the-souls-view) lists the open
112
+ workspace's souls; the Capabilities view says what it will hold and what
113
+ to run until then, `oats capabilities`. On the right is the time of the
114
+ read of this machine that the screen shows: it moves with every read.
115
+ - **The footer** is one row of keys from the first column, with no rule
116
+ above it. It names `C-\ commands` first, in every focus: the leader,
117
+ which reaches every action. Then come the actions that apply now, as many
118
+ as fit, `help` and `quit` last; a narrow footer gives the others up first.
119
+ While the leader waits for its key the row is the leader's hint.
113
120
  - **The list** is the roster the Desktop draws: the same groups in the same
114
- order, from the same code. An instance that others were spawned from
115
- comes first, and the ones below it are indented under it; instances
116
- related to no other follow, after an empty row.
117
- - **Each row** has a mark for its state, the name, then the harness when it
118
- runs, else its state in a word, then `!` when it needs input.
121
+ order, from the same code. It is in name order, by each group's top
122
+ instance, so starting or stopping an instance moves nothing. An instance
123
+ that others were spawned from has them indented under it, and keeps its
124
+ place when it gains or loses one. An empty row stands between each run
125
+ of instances related to no other and the group before or after it. The
126
+ indent alone says which instance is under which: no mark is drawn for
127
+ it. A row whose instances are folded away (`h`) says how many after its
128
+ name: `+1`.
129
+ - **Each row** is the mark of its state and the name, then `!` at the
130
+ right when it needs input. The harness and the state in words are in
131
+ the detail. A row has a word, dim, only where its mark cannot say it: the
132
+ state of a home a spawn or a retire holds (`Retire didn't finish`), or
133
+ the shared words for why an instance cannot be reached or opened:
134
+ `gone from garnet`, `garnet not reached`, `not reachable on garnet`,
135
+ `Herdr no longer supported`, `state unknown`.
119
136
  - **The detail** shows the selected instance: its soul, its state, and
120
137
  under it the reason when there is one, after the words that say who gave
121
138
  it: `OATS says:` for a kernel (this machine's, or the instance's
@@ -132,8 +149,8 @@ runs.
132
149
  columns up it stands beside the list; on a narrower terminal `Tab` opens
133
150
  it as a page.
134
151
  - **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).
152
+ beside the list, where the detail was, as a tab: see
153
+ [Open an agent's terminal](#open-an-agents-terminal) and [Tabs](#tabs).
137
154
 
138
155
  **A view of more than one deployment** (this machine and another, or two
139
156
  deployments on one machine) is one list, grouped as the Desktop groups it:
@@ -143,14 +160,22 @@ deployments on one machine) is one list, grouped as the Desktop groups it:
143
160
  with the end of the deployment's path when one machine holds two of the
144
161
  view. A heading cannot be selected or folded: the movement keys pass over
145
162
  it. A view of one deployment has no heading.
146
- - **A machine that answered carries the time its rows were read** on its
147
- heading, at the right: `read 14:03:21`. A row of another machine shows
148
- what its host reported at that time.
163
+ - **A machine's heading is its name.** When its rows were read at another
164
+ time than the one in the header, that time stands at the right of the
165
+ heading: `read 14:03:21`. A row of another machine shows what its host
166
+ reported at that time.
149
167
  - **A deployment that is not live carries its state and a short reason**
150
168
  on its heading, and no time: `garnet remembered Not reached`. The rows
151
169
  a machine last reported are kept when it is not reached, and each of them
152
- reads `unknown`, with the `?` mark, in the list and in the detail:
153
- nothing reads as stopped, or as running, that is only not reached.
170
+ reads `garnet not reached`, with the `?` mark, in the list and in the
171
+ detail: nothing reads as stopped, or as running, that is only not
172
+ reached.
173
+ - **An instance gone from its machine** is one this computer keeps a route
174
+ to, which its machine no longer has. It reads `gone from garnet`, with
175
+ the `?` mark, in the list and in the detail. The detail says so in a
176
+ sentence, with the command that removes it from this computer:
177
+ `oats server forget <id> --instance <name>`. It cannot be opened,
178
+ and `Enter` says why in the same sentence.
154
179
  - **A deployment that is not live and has no rows** is named after the
155
180
  others: the machine, the deployment's path, its state and the short
156
181
  reason on one row, and the whole reason on the rows under it.
@@ -164,7 +189,7 @@ deployments on one machine) is one list, grouped as the Desktop groups it:
164
189
  follows it.
165
190
 
166
191
  **A view that holds no deployment of this machine** says so in its header:
167
- `oats other on garnet` for one machine, `2 machines` after the name for
192
+ `other on garnet` for one machine, `2 machines` after the name for
168
193
  two or more. The time in the header is then the time the machines' rows
169
194
  were read. A view of one machine has no heading, so its state, when it is
170
195
  not live, is said above the list with the reason, as for a deployment of
@@ -185,8 +210,8 @@ in its workspace for the rest of the run, also while it is not reached.
185
210
  | `○` | `-` | stopped |
186
211
  | `◌` | `~` | stopped, with a shell left in its terminal |
187
212
  | `?` | `?` | state unknown: the kernel or the terminal probe could not tell, or the instance's machine was not reached |
188
- | `◆` | `#` | held by a spawn or a retire that is not finished |
189
- | `▾` `▸` | `v` `>` | has instances below it: shown, folded away |
213
+ | `◆` | `#` | held by a spawn or a retire: under way (Retiring…), failed or not finished ([below](#held-rows)) |
214
+ | `+n` | `+n` | after a name: n instances folded away below it |
190
215
  | `!` | `!` | needs input |
191
216
  | `!N` | `!N` | N instances folded away below it need input |
192
217
  | `>` | `>` | the selected row (also drawn in reverse video), and the pane the movement keys act on |
@@ -194,6 +219,25 @@ in its workspace for the rest of the run, also while it is not reached.
194
219
 
195
220
  Every state has a mark of its own shape, so nothing is told by colour alone.
196
221
 
222
+ <a id="held-rows"></a>**A held row** says in its word what holds it, by the
223
+ Desktop's rule:
224
+
225
+ - `Setting up worktree…`: a spawn is running its worktree setup.
226
+ - `Spawn didn't finish`: a spawn left the home for a retire to clean up.
227
+ - `Retiring…`: a retire is in progress, never shown as a failure. OATS
228
+ reports it running, or cannot tell whether the process holding it still
229
+ runs; or the instance's OATS does not report a retire's state yet and
230
+ the instance has a retire pending; or this `oats tui` sent the retire and
231
+ has not read the list since its answer. A retire the kernel refused, or
232
+ whose plan had changed, runs nothing: the row reads as the list says at
233
+ once.
234
+ - `Retire failed`: a self-retire's completion recorded an error. The detail
235
+ gives its reason after `OATS says:`, in OATS's words with its code,
236
+ through the display filter. With a code and no message, the reason is
237
+ its code after `OATS says:`, the same way.
238
+ - `Retire didn't finish`: a scheduled completion is gone and left no
239
+ outcome.
240
+
197
241
  **When a read fails,** what the view then shows is one rule, shared with the
198
242
  Desktop, and `oats tui` decides none of it. Depending on the failure the
199
243
  last rows stay as they were; or they stay and are marked `stale`, with the
@@ -215,63 +259,75 @@ on whether that read has succeeded before in this run:
215
259
  | The read failed | The view shows |
216
260
  |---|---|
217
261
  | before it ever succeeded in this run | after the list and an empty row, the row `Other machines were not read.` and under it the failure: `Remote roster unavailable: <message>`, or the kernel's own message when it answered with an error |
218
- | after it succeeded once | each machine keeps its place and its heading, with its state and a short reason in place of the time; its rows are kept and read `unknown` |
262
+ | after it succeeded once | each machine keeps its place and its heading, with its state and a short reason in place of the time; its rows are kept and read `<machine> not reached` |
219
263
 
220
264
  The next read that succeeds shows the machines as they then report.
221
265
 
222
266
  Names are cut by terminal cells with `…` (`...` in ASCII) when they do not
223
- fit; the detail shows them whole.
267
+ fit; the detail shows them whole. The TUI's own words end the same way:
268
+ **Retiring…** reads `Retiring...` in ASCII.
224
269
 
225
270
  ## Open an agent's terminal
226
271
 
227
272
  ```
228
- oats acme-platform 2 running
273
+ acme-platform 2 running
229
274
  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
275
+ ──────────────────────────────┬─────────────────────────────────────────────────
276
+ > ● backend-lead │ backend-lead
277
+ ● docs-writer │$ make docs
278
+ │Building the reference...
279
+ │
280
+ │
281
+ C-\ commands C-\ C-\ back to the list
237
282
  ```
238
283
 
239
284
  - **`Enter` on an instance that runs** opens its terminal on the right of
240
285
  the body, where the detail was, with the list on the left. Its top row
241
286
  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.
287
+ is the agent's screen, as the agent draws it, in its own colours. While a
288
+ terminal is open the list keeps 30 columns at most, also while the
289
+ detail stands in the terminal's place, and a name longer than its row is
290
+ cut with `…` (`...` in ASCII).
243
291
  - **The terminal has the focus.** What you type, what you paste and every
244
292
  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.
293
+ among them, but for **[the leader](#the-leader)** (`Ctrl+\` unless
294
+ [`tui.json`](#change-the-keys-tuijson) names another), the one key the
295
+ TUI takes from the agent. The leader twice gives the focus to the list;
296
+ the leader then another key does what that key does from anywhere. While
297
+ the terminal has the focus the footer names it, and the leader twice:
298
+ `C-\ commands C-\ C-\ back to the list`. A leader inside a bracketed
299
+ paste is pasted, not taken.
250
300
  - **With the list focused** the terminal stays open, and the agent's screen
251
301
  is still drawn as it changes. The footer names the keys for it:
252
302
  `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.
303
+ - `Enter` on the shown terminal's row gives it the focus again.
254
304
  - `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.
305
+ stay, the list is hidden. The leader twice brings the list back beside
306
+ it, and the leader then `z` zooms it out and in without leaving it.
307
+ - `c` closes it: the agent keeps running. The tab beside it is shown;
308
+ with no other tab the right side is the detail again.
258
309
  - `Tab` shows the detail in its place until `Tab` or `Esc`. Nothing of
259
310
  the terminal is drawn meanwhile, and its screen is read afresh when it
260
311
  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.
312
+ - **Up to four terminals are open at a time, each a tab.** `Enter` on
313
+ another instance that runs opens its terminal in a new tab, and the
314
+ others stay open: see [Tabs](#tabs).
263
315
  - **Under 80 columns** the terminal is always shown with the whole body
264
316
  when it has the focus. With the list focused the list is shown alone; the
265
317
  terminal stays open, unseen, and `Enter focus terminal` in the footer
266
318
  shows it again. Beside the list the terminal is never narrower than 40
267
319
  columns.
268
- - **A terminal also closes by itself** when its viewer ends: the agent's
320
+ - **A terminal also closes by itself** when its viewer ends, shown or
321
+ hidden ([which tab is shown then](#tabs)): the agent's
269
322
  window ended, its session went away, or the link to its machine dropped.
270
323
  It closes within a second of that (tmux tells `oats tui` of a viewer's
271
324
  end once a second), or a second more when tmux took a moment more to
272
325
  have the viewer's exit status: once tmux has reported the viewer ended,
273
326
  `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
327
+ terminal without it when it has not come. A tmux built with libutempter
328
+ (Ubuntu's and Debian's are) can lose that status: while it waits,
329
+ `oats tui` has tmux look for it again once a second, so the terminal
330
+ still closes within a second or two with the line its status calls for. The instances are then read again at once, and one line above the panes
275
331
  says what happened: that it could not be opened, that the connection to
276
332
  its machine ended, or that the viewer ended without saying why. What the
277
333
  viewer printed on its error output stands under that line in quotation
@@ -281,7 +337,7 @@ fit; the detail shows them whole.
281
337
  `Enter` opens it.
282
338
  - **`Enter` on an instance that cannot be opened** opens nothing and says
283
339
  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
340
+ reason holds it (an instance gone from its machine, say). An agent on another machine is asked first whether it
285
341
  can be opened (`Esc` gives that up); a machine whose OATS cannot open its
286
342
  sessions is said then.
287
343
  - **No scrollback but the viewer's own, and no mouse.** The panel shows
@@ -297,14 +353,238 @@ fit; the detail shows them whole.
297
353
  agent opens in the TUI's panel, and `oats tui` makes no window and no
298
354
  split in your tmux.
299
355
 
356
+ ## Tabs
357
+
358
+ ```
359
+ acme-platform 3 running
360
+ Instances Souls Capabilities read 14:03:27
361
+ ──────────────────────────────┬─────────────────────────────────────────────────
362
+ > ● backend-lead │ backend-lead docs-writer• qa-runner
363
+ ● docs-writer │$ make test
364
+ ● qa-runner │ok 41 of 41
365
+ │
366
+ │
367
+ C-\ commands C-\ C-\ back to the list
368
+ ```
369
+
370
+ Each terminal open in the panel is a tab, and the panel holds up to four.
371
+
372
+ - **The tab strip** is the panel's top row: each tab's agent, in the order
373
+ the tabs were opened. With one tab the row reads as
374
+ [above](#open-an-agents-terminal), the agent's name alone.
375
+ - **The shown tab** is the one whose screen the panel draws. Its name is
376
+ in reverse video while the terminal has the focus, and bold otherwise.
377
+ - **The other tabs are hidden**, their names plain. A hidden tab whose
378
+ agent wrote since it was last shown has `•` after its name (`*` in
379
+ ASCII); the mark goes when the tab is shown. A hidden tab's screen is
380
+ not read: only that its agent wrote.
381
+ - **An agent of another machine** reads `<name>`, then a dim
382
+ `on <machine>`.
383
+ - **A strip longer than its row is cut** in this order: the hidden tabs'
384
+ `on <machine>`, then the hidden tabs' names, each to an equal share of
385
+ what the shown tab leaves, with `…` (`...` in ASCII), then the shown
386
+ tab's `on <machine>`; then the hidden tabs farthest from the shown one
387
+ are left out of the row (they stay open). The shown tab's name stays
388
+ whole while the row can hold it.
389
+ - **Opening.** `Enter` on a row, an instance in
390
+ [the palette](#the-palette), the leader then `Up` or `Down`, and a
391
+ [spawn](#spawning-an-agent)'s new agent open a terminal the same way:
392
+ - an instance that has a tab: that tab is shown, with the focus in it;
393
+ - any other: a new tab, after the shown one, is shown with the focus in
394
+ it. The other tabs stay open.
395
+ - **One open at a time.** While a tab is starting, or an agent of another
396
+ machine is asked whether it can be opened, another open does nothing,
397
+ and neither does a key that shows another tab.
398
+ - **At four tabs nothing closes by itself.** The open does nothing, and
399
+ the line above the panes says `4 terminals are open; close one with C-\ w.`
400
+ (with your leader, when [`tui.json`](#change-the-keys-tuijson) names
401
+ another). A tab still starting, and an agent of another machine while
402
+ it is asked, hold a place among the four. An instance that cannot be
403
+ opened says why, as it does with no tab open.
404
+ - **Switching.** `[` and `]` in the Instances view, from the list or the
405
+ detail, show the tab before or after the shown one. The leader then
406
+ `Left` or `Right` does the same from any focus, and from another view
407
+ goes to the Instances view first.
408
+ - The strip does not wrap: on the first tab `[` does nothing, and on the
409
+ last `]`; the leader then `Left` or `Right` there leaves even the focus
410
+ where it was.
411
+ - The focus does not move: in the terminal it stays in the terminal,
412
+ zoomed or not, and in the list it stays in the list.
413
+ - **Showing a tab selects its instance's row** in the list and brings it
414
+ into view: a filter that hides the row is cleared, and an instance
415
+ folded over it is opened.
416
+ - **The palette** lists the instances most recently opened or shown first,
417
+ as the Desktop's does. When the first of them is the shown tab's, the
418
+ palette opens with the second selected, so the palette then `Enter` goes
419
+ back to the terminal shown before it.
420
+ - **Closing.** The leader then `w`, or `c` in the Instances view, closes the
421
+ shown tab: its agent keeps running. The tab to its right is shown, else
422
+ the one to its left.
423
+ - After the leader then `w` from a terminal, the tab shown next has the
424
+ focus, and is zoomed when the one closed was. After `c`, or the leader
425
+ then `w` from anywhere else, the terminal does not take the focus.
426
+ - Closing the last tab closes the panel: the right side is the detail
427
+ again, and the list has the focus.
428
+ - **A tab that closes by itself**, when its viewer ends, says so on the line
429
+ above the panes in the words [above](#open-an-agents-terminal), for that
430
+ tab's agent (no line when it ended cleanly).
431
+ - The shown tab: the tab to its right is shown, else the one to its left,
432
+ and the list takes the focus.
433
+ - A hidden tab: the shown tab and the focus stay as they were.
434
+ - **Zoom** (`z`, or the leader then `z`) gives the shown tab the whole body.
435
+ The strip stays its top row, and the other tabs stay open.
436
+ - **The tabs are the open workspace's.** Opening another workspace in
437
+ [the switcher](#the-switcher) closes them all, and so does the open
438
+ workspace no longer being listed; their agents keep running. Coming back
439
+ opens none of them again.
440
+
441
+ ## Splits
442
+
443
+ ```
444
+ acme-platform 3 running
445
+ Instances Souls Capabilities read 14:03:27
446
+ ──────────────────────────────┬─────────────────────────────────────────────────────────────────────────────────
447
+ ● backend-lead │ backend-lead docs-writer │ qa-runner
448
+ ● docs-writer │$ git log --oneline -2 │$ make test
449
+ > ● qa-runner │4be1c0d Fix the reader │ok 41 of 41
450
+ │9a03e7f Add the roster │
451
+ │ │
452
+ C-\ commands C-\ C-\ back to the list
453
+ ```
454
+
455
+ The panel can be split in two **groups**, side by side or one above the
456
+ other. Each group is a panel of [tabs](#tabs) of its own: a strip, a shown
457
+ tab and the marks of its hidden ones.
458
+
459
+ - **Splitting.** The leader then `|` splits the panel side by side, and the
460
+ leader then `-` one above the other; in the Instances view `|` and `-`
461
+ do the same without the leader. The tabs open stay in the first group
462
+ (left, or top). The second group starts empty and is the focused group.
463
+ - A split needs a tab open, and none starting.
464
+ - **There are at most two groups.** With two, the split keys do nothing,
465
+ and the line above the panes says `The panel has two groups already.`
466
+ - **Each group needs 40 columns side by side, and 8 rows one above the
467
+ other**, its strip counted. The panel beside the list then needs 81
468
+ columns (a terminal of 112), or 17 rows. A split that would leave a
469
+ group smaller does nothing, and the line says so:
470
+ `No room to split side by side: each group needs 40 columns.` or
471
+ `No room to split one above the other: each group needs 8 rows.`
472
+ - **What is drawn.** A rule separates the groups. Both groups' shown tabs
473
+ are drawn as their agents write; hidden tabs only set their marks.
474
+ - The focused group's strip is drawn as with one group: its shown tab in
475
+ reverse while its terminal has the focus, bold otherwise. The other
476
+ group's shown tab is bold, never in reverse, so one terminal at a time
477
+ reads as the one you type into.
478
+ - **An empty group** says `Enter on an agent opens it here`, in reverse
479
+ while it is the focused group, and the leader's keys to go to the other
480
+ group or to close it. It never takes keys: while it is the focused
481
+ group, the keys are the list's.
482
+ - A resize gives each group its share and reaches every tab's window in
483
+ it. **When the terminal becomes too small for both groups,** the split
484
+ stays and the focused group is drawn alone; the other group's shown tab
485
+ is not drawn, only marked, until there is room again.
486
+ - **Under 80 columns** the terminal's focus gives the whole body to both
487
+ groups, and the list's focus shows the list alone, as with one group.
488
+ - **Zoom** (`z`, or the leader then `z`) gives the focused group's shown
489
+ terminal the whole body, and the same key brings the split back. With
490
+ the empty group focused it does nothing.
491
+ - **Opening.** `Enter`, the palette, the leader then `Up`/`Down` and a
492
+ spawn open as with one group:
493
+ - an instance that has a tab, in either group: that tab is shown in its
494
+ group, and that group takes the focus;
495
+ - any other: a new tab in the focused group, after its shown tab, or as
496
+ the first tab of the empty group.
497
+ - **The four tabs are counted across both groups.** At four, the line
498
+ says `4 terminals are open; close one with C-\ w.` as with one group.
499
+ - **Moving between the groups.** The leader then `Tab` from a terminal goes
500
+ to the other group's shown terminal, or to the other group when it is
501
+ empty. From the list it goes to the focused group's terminal, or, with
502
+ the focused group empty, to the other group's. Showing a tab selects its
503
+ row in the list. `[`, `]` and the leader then `Left`/`Right` show the tab
504
+ before or after within the focused group only.
505
+ - **Moving a tab.** The leader then `m` moves the focused group's shown tab
506
+ to the other group, after that group's shown tab, and shows it there with
507
+ the focus. The group it leaves shows its neighbour, or stays, empty.
508
+ - **Closing.** Closing a tab (`c`, or the leader then `w`) shows its
509
+ neighbour in its group: the tab to its right, else the one to its left.
510
+ - **A group's last tab closed removes the group:** the other takes the
511
+ whole panel and the focus. When the other group was empty, the panel
512
+ closes, as when the last tab of the only group closes.
513
+ - The leader then `x` closes the focused group while it is empty: the
514
+ other takes the whole panel and is the focused group, and the keys stay
515
+ the list's. With tabs in the group, `x` does nothing.
516
+ - **A tab that closes by itself** shows its neighbour in its group. A
517
+ group's last tab closing by itself removes the group, and the list
518
+ takes the focus; when what is left is an empty group, the panel closes.
519
+ - **The palette** lists `Split right` and `Split down` while there is one
520
+ group, then `Move tab to the other group` while the focused group shows a
521
+ tab, or `Close the empty group` while it is empty.
522
+ - **Another workspace** closes every tab and the split.
523
+ - The split cannot be resized or nested, and is not kept from one run to
524
+ the next.
525
+
526
+ ## The Souls view
527
+
528
+ `2`, or the leader then `2`, shows the souls of the open workspace: the
529
+ ones `oats spawn` can make an instance of here, as the OATS Desktop lists
530
+ them, from the same code.
531
+
532
+ ```
533
+ acme-platform 2 running 1 stopped
534
+ Instances Souls Capabilities read 14:03:27
535
+ ──────────────────────────────────────┬─────────────────────────────────────────
536
+ > ■ dev ·2 │ dev
537
+ ■ ops ! │ Builds and ships the platform.
538
+ ■ reviewer ·1 │
539
+ │ from oats-core
540
+ │ works works in its own worktree
541
+ ```
542
+
543
+ - **A row** is the soul's colour mark (`■`, `#` in ASCII; its colour is the
544
+ Desktop's for that soul, uncoloured when it has none), its name, and a
545
+ count of its instances on this machine, `·2`. A soul a spawn here would
546
+ refuse is drawn dim, with `!` after its name. The list keys move, and `/`
547
+ filters by name, description or where the soul comes from.
548
+ - **The detail** beside it, top to bottom: the name and the description;
549
+ where it comes from (its member, or its package and version); where it
550
+ works; why a spawn here would be refused, when it would be; the harness
551
+ and model a spawn would use and where that choice is set (a launch
552
+ problem as the kernel reports it); its teams, the default first; its
553
+ capabilities; and its instances on this machine, eight at most and then
554
+ `+n`. `Enter` gives the detail the focus (under 80 columns it takes the
555
+ list's place), and the movement keys then scroll it.
556
+ - **`i`**, or `Enter` in the detail, shows that soul's instances in the
557
+ Instances view: an exact filter, shown where a kept filter stands in
558
+ the footer, `soul dev`.
559
+ An instance of another soul whose name holds `dev` is not listed. `Esc`
560
+ clears it, and `/` replaces it with a text filter.
561
+ - **`r`** reads the souls again; while a read is under way it starts
562
+ nothing. `Esc` closes the detail, then clears a kept filter, then goes
563
+ back to the instances.
564
+ - **When it reads:** the first time the view is shown, never before: a run
565
+ that never shows it never runs `oats souls`. After that, a read of the
566
+ workspace reads the souls again only when the workspace changed (its
567
+ commit, a member's, its externals), and `r` does. While the first read is
568
+ under way the view says `Reading souls…`. A read that fails says why,
569
+ with `r` to try again; one that fails after a good one keeps the souls it
570
+ had, under a heading that says it failed and when the souls were read;
571
+ the selected soul's detail says why in full, under its name.
572
+ - **What is kept:** the selected soul and the filter, when the view is left
573
+ and shown again, for the run.
574
+ - **Only this machine's:** the view lists the souls of a workspace of this
575
+ machine. With none open it says so.
576
+
577
+ `n` or `N` spawns an agent of the selected soul: [Spawning an
578
+ agent](#spawning-an-agent).
579
+
300
580
  ## The switcher
301
581
 
302
582
  `w` opens the switcher: what this run can show, over the whole body of the
303
583
  screen.
304
584
 
305
585
  ```
306
- oats workspaces
307
- 1 Instances 2 Souls 3 Capabilities
586
+ workspaces
587
+ Instances Souls Capabilities
308
588
  ────────────────────────────────────────────────────────────────────────────────
309
589
  > * acme-platform This machine · garnet
310
590
  ledger quartz
@@ -316,8 +596,8 @@ screen.
316
596
 
317
597
 
318
598
 
319
- ────────────────────────────────────────────────────────────────────────────────
320
- Enter open / filter r refresh Esc close ? help q quit
599
+
600
+ C-\ commands Enter open / filter r refresh Esc close ? help q quit
321
601
  ```
322
602
 
323
603
  It lists, in this order:
@@ -379,8 +659,13 @@ confirmation:
379
659
  The rules are the Desktop's, from the readers both clients share: an
380
660
  instance offers what the Desktop offers for it, and nothing else. One that
381
661
  is still being spawned, and one its machine reports it cannot reach, offers
382
- none; one whose spawn stopped half way offers only to be retired; a running
383
- one offers restart and not start, a stopped one start and not restart. The
662
+ none; one whose spawn stopped half way, and one whose retire failed or
663
+ didn't finish, offers only to be retired; a running one offers restart and
664
+ not start, a stopped one start and not restart. One that is `Retiring…`
665
+ offers no start, stop, restart or open: `D` still opens its retire
666
+ confirmation, but the footer does not name it, since the kernel refuses a
667
+ second retire while one runs and it is needed only when the first one's
668
+ holder can't be read. The
384
669
  footer names the keys the selected instance offers now, after `Enter`, and
385
670
  on a narrow terminal they are the first hints it gives up. A key for an act
386
671
  the instance does not offer opens nothing, and the line above the panes
@@ -452,6 +737,82 @@ The exit status never depends on it.
452
737
  there can leave `.oats-stop-pending.json` in the agent's home, and then
453
738
  the agent can be started but not stopped while that file exists.
454
739
 
740
+ ## Spawning an agent
741
+
742
+ `n` spawns an agent of a soul of the open workspace, on this machine, with
743
+ one screen to read and one `Enter` to press.
744
+
745
+ - **`n`** in the list of instances (or the leader then `n`, from any focus,
746
+ a terminal's too) opens the soul picker over the list: the souls of
747
+ [the Souls view](#the-souls-view), read with `oats souls` if they were
748
+ not read yet (`Reading souls…` until then). Typing filters them with the
749
+ palette's subsequence match; `Up`/`Down` move, `Enter` picks the selected
750
+ soul, `Esc` closes. A soul a spawn here would refuse is listed with `!`
751
+ and why, and cannot be picked.
752
+ - **`N`** (or the leader then `N`) spawns another of the selected instance's
753
+ soul (from a terminal's focus, that terminal's instance): it opens the
754
+ preview at once. In the Souls view `n` and `N` both open the preview of
755
+ the selected soul. The palette lists `Spawn an agent` and, with an
756
+ instance selected whose soul the catalog lists, `Spawn another <soul>`.
757
+ - **The preview** is the OATS Desktop's, read with the kernel's
758
+ `oats spawn <soul> --preview --json` and worded by the same shared
759
+ readers: the name the agent will have, its home, where it works, its
760
+ harness and model and where that choice was made, its team, its
761
+ relationship, its worktree setup, where it runs; then the launch-prompt
762
+ policy, the capabilities' warnings and the modules, each folded to one
763
+ row.
764
+ - **One focus ring:** `Spawn` (where the focus starts), `name`, `child of`
765
+ (when an instance of this machine was selected), then each folded part.
766
+ `Tab` moves along it, `Shift+Tab` back. `Enter` does what the focus says,
767
+ and the footer names it:
768
+ - on `Spawn`, spawns what the preview shows;
769
+ - on `name`, keeps the name typed and reads the preview again with it:
770
+ the instance is named `<soul>-<name>` (`--purpose`). Only the letters,
771
+ digits and dashes of a name are typed; `Esc` puts back the name the
772
+ preview was read with;
773
+ - on `child of`, switches between no parent and the instance that was
774
+ selected when the prompt opened, and reads the preview again;
775
+ - on a folded part, opens or closes it.
776
+
777
+ `Esc` on any other focus gives it to `Spawn`; on `Spawn` it goes back to
778
+ the picker (to the list for `N` and from the Souls view). The movement
779
+ keys scroll a preview taller than the screen.
780
+ - **Nothing else is chosen here:** the harness and the model are the
781
+ soul's and this machine's launch preferences (`oats soul launch set`),
782
+ and there is no task: the new agent starts with none, and you type to it
783
+ in its terminal.
784
+ - **A paste cannot spawn.** An `Enter` in the same read of input as the
785
+ key that opened the prompt does nothing; `Enter` on `Spawn` spawns only
786
+ once the preview was read for exactly the choices shown, a frame that
787
+ shows it ready with its `Spawn` button was written to the terminal, and
788
+ only from a read of input later than that frame. A pasted `n`, a soul's
789
+ name and two `Enter`s stop at the preview.
790
+ - **`n` and `N` are of the view they are pressed in**: the leader's too.
791
+ From the Souls view (its list, its filter or its detail) both are of its
792
+ selected soul, whatever the list of instances has selected.
793
+ - **One spawn at a time.** While one is under way the line above the
794
+ panes says `Spawning <name>…`, and the TUI goes on working: `n` and `N`
795
+ say a spawn is under way and open nothing.
796
+ - **Only on this machine.** On another machine's row or workspace `n` and
797
+ `N` (from their keys, the leader or the palette) say that spawning on
798
+ another machine is not offered here, and that `oats spawn` there makes
799
+ one.
800
+
801
+ **What follows the spawn** is said in the shared words, the Desktop's, and
802
+ the TUI adds only what to do next, naming its keys or an `oats` command:
803
+
804
+ | Outcome | What follows |
805
+ |---|---|
806
+ | created and started | the instances are read at once; when the new row appears it is selected and its terminal opens beside the list in a new [tab](#tabs), with the focus in it. With four tabs open the line says it was created, then `4 terminals are open; close one with C-\ w.`, and nothing opens. Not running after two reads: the line says it is not visible yet, and nothing opens later by itself |
807
+ | created, but not started, or its wake not saved, or not finished | the line says so; nothing opens. A home the spawn left reads as [held](#held-rows) |
808
+ | not known (the answer was lost, or still running at the deadline) | the line says so, and `C` checks its result once, without spawning again: it is offered only then |
809
+ | its cleanup is owed | the line says so and names the retire |
810
+ | refused, rolled back, never submitted, or changed since you looked | the preview again, read anew, with the line in it: change the choices or press `Enter` again |
811
+
812
+ **Quitting with a spawn under way** lets it go: the spawn finishes, or the
813
+ kernel's own limits bound it; `oats tui` neither waits for it nor ends it.
814
+ The line after leaving says so and names `oats status` to see it.
815
+
455
816
  ## Keys
456
817
 
457
818
  | Key | Does |
@@ -465,13 +826,20 @@ The exit status never depends on it.
465
826
  | `/` | filter |
466
827
  | `r` | read now |
467
828
  | `1` | the Instances view |
468
- | `2`, `3` | the Souls and Capabilities views: not in this version, so a line says what to run instead |
829
+ | `2` | [the Souls view](#the-souls-view); `Esc` or `1` goes back |
830
+ | `3` | the Capabilities view, which says what it will hold and what to run until then; `Esc` or `1` goes back |
469
831
  | `w` | opens [the switcher](#the-switcher) |
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) |
832
+ | `Enter` | in the list of instances, opens the selected agent's terminal in a new [tab](#tabs) beside the list, or shows its tab when it has one, with the focus in it; in the switcher, opens the selected row; in a confirmation, presses the button with the focus |
833
+ | `z` | gives the shown terminal the focus and the whole body |
834
+ | `c` | closes the shown terminal's tab and shows the tab beside it; the agent keeps running |
835
+ | `[`, `]` | in the Instances view, shows the tab before or after the shown one |
836
+ | `\|`, `-` | in the Instances view, [splits](#splits) the panel side by side or one above the other |
837
+ | `Ctrl+\` | [the leader](#the-leader), from every focus ([`tui.json`](#change-the-keys-tuijson) can name another key) |
838
+ | `Ctrl+K` | opens [the palette](#the-palette); `Ctrl+K` again closes it |
474
839
  | `X`, `D`, `S`, `R` | stop, retire, start, restart the selected agent, [after a confirmation](#stopping-starting-restarting-and-retiring) |
840
+ | `n` | [spawns an agent](#spawning-an-agent): the soul picker, then the preview |
841
+ | `N` | spawns another of the selected instance's soul: its preview |
842
+ | `C` | checks the result of a spawn whose outcome is not known, while one is |
475
843
  | `Left`/`Right`, `Tab`/`Shift+Tab` | in a confirmation, move between its buttons |
476
844
  | `Space` | in a confirmation, switches the plan's choice |
477
845
  | `?` | opens the help; `?` again closes it |
@@ -489,10 +857,91 @@ instance can always be read, however many they are. The selection stays
489
857
  where it is, and the list returns to it at the next key that moves it.
490
858
 
491
859
  The help screen is generated from the table the program acts on, so it
492
- always lists the keys that work, with the marks and with what this version
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.
860
+ always lists the keys that work, the leader's among them, with the marks
861
+ and with what this version does not do. The movement keys scroll it. While
862
+ a terminal has the focus the table's keys are the agent's: the leader alone
863
+ is the TUI's.
864
+
865
+ ### The leader
866
+
867
+ Every action is reached by keys from every focus, a terminal's too: the
868
+ leader, `Ctrl+\` (tui.json's `open.detachKey`), then one plain key.
869
+
870
+ | The leader, then | Does |
871
+ |---|---|
872
+ | `k` or `Space` | opens [the palette](#the-palette) |
873
+ | `1`, `2`, `3` | the Instances, Souls and Capabilities views |
874
+ | `Up`, `Down` | opens the terminal of the instance before or after, in the list as it is drawn, the focus in it: from the shown terminal's instance, or from the selection when none is open. It shows the instance's tab when it has one, else opens a new [tab](#tabs). Rows that cannot be opened are passed over, and the list does not wrap |
875
+ | `Left`, `Right` | shows the tab before or after the shown one; the strip does not wrap, and the focus stays where it was |
876
+ | `z` | zooms the shown terminal in or out; with the list focused, gives it the focus and the whole body |
877
+ | `w` | closes the shown terminal's tab and shows the tab beside it; the agent keeps running |
878
+ | `\|`, `-` | [splits](#splits) the panel side by side or one above the other |
879
+ | `Tab` | goes to the other group's terminal (or to the other group, when it is empty); from the list, to the focused group's |
880
+ | `m` | with two groups, moves the shown tab to the other group, and goes there |
881
+ | `x` | closes the focused group while it is empty |
882
+ | `X`, `R`, `S`, `D` | stop, restart, start, retire, [after a confirmation](#stopping-starting-restarting-and-retiring): from a terminal's focus on that terminal's instance, which has the focus again when the confirmation closes |
883
+ | `n`, `N` | [spawns an agent](#spawning-an-agent); `N` of the shown terminal's soul from its focus |
884
+ | `/` | the filter |
885
+ | `o` | [the switcher](#the-switcher) |
886
+ | `?` | the help |
887
+ | `Esc`, or the leader again | gives the list the focus; with the list focused, only closes the hint |
888
+
889
+ - **While the leader waits** for its key the footer row is its hint, which
890
+ names these keys (`z` and `w` only while a terminal is open, `Left` and
891
+ `Right` only with two tabs or more, `|` and `-` while the panel has one
892
+ group, `Tab` with two, then `m` while the focused group shows a tab or
893
+ `x` while it is empty). It waits
894
+ with no time limit. A key not in the table cancels it and is dropped:
895
+ nothing is typed.
896
+ - **Only a key in a later read counts.** A key that came in the same read of
897
+ input as the leader cancels it and is dropped, with the rest of that
898
+ read, so a paste can never run a command. In a terminal the bytes before
899
+ the leader in that read still go to the agent. A leader inside a
900
+ bracketed paste is pasted text.
901
+ - **In the list no leader is needed:** the plain keys work as they always
902
+ have, and the leader works there too.
903
+ - **What was open under it is settled first,** from whatever view: a
904
+ filter field keeps its filter, as `Enter` does, and a confirmation
905
+ closes. `Up`, `Down`, `Left`, `Right`, `z`, `w`, the split's keys and the acts then go to
906
+ the Instances view, from Souls, Capabilities, the help or the switcher
907
+ too; with no workspace open they do nothing, and `Left`, `Right`, `z` and
908
+ `w` do nothing with no terminal open.
909
+ - **The table is fixed** in this version: `keys` in `tui.json` rebinds the
910
+ plain keys, and `open.detachKey` the leader.
911
+
912
+ ### The palette
913
+
914
+ The leader then `k` (or `Space`), or `Ctrl+K` in the list, opens one input
915
+ over a list, as the OATS Desktop's ⌘K does. It takes the body, and while it
916
+ is open no terminal is drawn and the TUI reads the keys.
917
+
918
+ - **It lists, in this order:** the instances that can be opened, the most
919
+ recently opened or shown in this run first (when the first is the shown tab's,
920
+ the second is selected as it opens), then the list's order, each with its
921
+ state mark, its name and, for another machine, `on <machine>`; the souls
922
+ of the open workspace, once [the Souls view](#the-souls-view) has read
923
+ them (choosing one shows that view with it selected; the palette never
924
+ reads them); the views, Instances, Souls and Capabilities; the acts the
925
+ instance offers now (the shown terminal's when the palette was opened from
926
+ its focus, else the selected one's), with `Spawn another <soul>` once the
927
+ catalog lists its soul; then Spawn an agent, Workspaces, Refresh and Help, and [the split's](#splits)
928
+ rows where each applies.
929
+ Each row says at its right edge what kind it is: `instance`, `soul`,
930
+ `view`, `act` or `command`.
931
+ - **Typing filters it** with the Desktop's subsequence match, a prefix
932
+ first: each kind keeps the rows that match, the best first.
933
+ `Backspace` removes a character, and a paste adds its first line.
934
+ `Up`/`Down` (and `PageUp`/`PageDown`) move, `Enter` runs the selected
935
+ row, `Esc` closes it.
936
+ - **Running a row** settles what was open under the palette, as the leader
937
+ does: an instance shows its tab, or opens its terminal in a new one, in
938
+ the Instances view, the focus in it ([Tabs](#tabs)); an act opens its
939
+ confirmation; a view shows
940
+ it; a command does what its key does.
941
+ - **An `Enter` in the same read as the palette's opening runs nothing**, so
942
+ a paste cannot open it and run a row.
943
+ - Closed, it gives the focus back to the terminal it was opened from.
944
+ Recency is kept for the run only: nothing is written.
496
945
 
497
946
  **The filter.** `/` opens a field on the last row. What you type narrows the
498
947
  list to the instances whose name, soul or repository contains it, with the
@@ -526,12 +975,18 @@ never writes it. With no file the keys are the ones above.
526
975
  do not name keeps its keys.
527
976
  - The actions are `up`, `down`, `top`, `bottom`, `page-up`, `page-down`,
528
977
  `collapse`, `expand`, `detail`, `filter`, `refresh`, `instances`,
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,
978
+ `souls`, `capabilities`, `workspaces`, `palette`, `open`, `soul-instances`, `zoom`, `close-terminal`,
979
+ `tab-previous`, `tab-next`, `split-right`, `split-down`, `group-next`, `tab-move`,
980
+ `group-close`, `stop`, `retire`, `start`, `restart`, `spawn`, `spawn-another`,
981
+ `spawn-check`, `help`, `close`, `quit`, `suspend` and `redraw`. `workspaces` (`w`) opens the switcher and `open` (`enter`)
982
+ opens the selected agent's terminal in the list of instances, the
983
+ selected row in the switcher and the detail in the Souls view;
984
+ `soul-instances` (`i`) shows the selected soul's instances. `zoom` (`z`) and `close-terminal` (`c`) act
985
+ on the shown terminal, and `tab-previous` (`[`) and `tab-next` (`]`) show
986
+ the tab before and after it. `split-right` (`|`) and `split-down` (`-`)
987
+ [split](#splits) the panel; `group-next`, `tab-move` and `group-close`
988
+ have no key of their own by default (the leader then `Tab`, `m` and `x`
989
+ reach them). In an open filter field `Enter` keeps the filter,
535
990
  whatever key `open` has.
536
991
  - A key is written as the help shows it, in lower case: `q`, `G`, `?`,
537
992
  `space`, `enter`, `tab`, `escape`, `backspace`, `up`, `pageup`, `f5`,
@@ -540,9 +995,11 @@ never writes it. With no file the keys are the ones above.
540
995
  and `Ctrl+M` as `backspace`, `tab` and `enter`, so those four are not
541
996
  keys of their own.
542
997
  - `ascii: true` is `--ascii`.
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
998
+ - `open.detachKey` is **[the leader](#the-leader)**, `C-\` when you name
999
+ none. It is `oats tui`'s own and never reaches the agent or the kernel.
1000
+ It is read as a key wherever the TUI reads keys, so it may not be a key
1001
+ an action has: `C-l` is `redraw`'s `Ctrl+L`, `C-k` the palette's
1002
+ `Ctrl+K`, `C-j` is `Enter`. It is one of
546
1003
  these, written as shown: `C-` with a letter but `h`, `i` and `m` (a
547
1004
  terminal sends those as `Backspace`, `Tab` and `Enter`) or one of `\`
548
1005
  `]` `^` `_`; `M-` with a lower-case letter or a digit; or `F1` to `F12`,
@@ -562,6 +1019,7 @@ guesses nothing. It refuses:
562
1019
  | 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` |
563
1020
  | has a member of `open` other than `detachKey` | `unknown member … of open; open has detachKey` |
564
1021
  | gives `open.detachKey` anything but one of the keys above | `open.detachKey must be one key: …`, with the keys it can be |
1022
+ | gives `open.detachKey` a key an action has | `open.detachKey … is read as …, the key of …; give the leader a key no action has, or give … another` |
565
1023
  | names `open-workspace`, the action's name before it became `open` | `open-workspace is called open now; rename it` |
566
1024
  | names an action that does not exist | `unknown action …`, with the list of actions |
567
1025
  | gives an action something that is not a list of strings | `… must be a list of key ids` |
@@ -597,6 +1055,15 @@ with the Desktop (`packages/client/`).
597
1055
  read's. What a read in the background may reuse is the kernel's own look
598
1056
  at the workspace's remotes, for up to 60 seconds; `r` asks the kernel to
599
1057
  look again.
1058
+ - **The souls are one more read**, `oats souls --json` for the open
1059
+ workspace, by the same kernel, with 60 seconds and 4 MiB: only once [the
1060
+ Souls view](#the-souls-view) was shown, then only when the workspace
1061
+ changed, and on `r` there.
1062
+ - **A spawn's preview is one more read**, `oats spawn <soul> --preview
1063
+ --json` with the choices shown, by the same kernel, with 30 seconds: only
1064
+ while [the spawn prompt](#spawning-an-agent) is open, and again when a
1065
+ choice changes. An answer is reused for a minute, as the Desktop reuses
1066
+ it, until a spawn is applied or the workspace changes.
600
1067
  - **The other machines are one more read**, `oats server roster --json`,
601
1068
  by the same kernel: one answer for every machine registered on this
602
1069
  machine. It has 60 seconds and 4 MiB.
@@ -642,13 +1109,41 @@ with the Desktop (`packages/client/`).
642
1109
  `ps -o ppid= -p` (macOS). With neither (no `/proc`, and no `ps` or one
643
1110
  that refuses `-p`, like BusyBox's), the keeper kills nothing. A normal
644
1111
  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
1112
+ its private server running, with its tabs' viewers still
1113
+ attached to their agents, until you end it with `tmux -S
647
1114
  <run directory>/tmux kill-server`. The next run's sweep leaves that
648
1115
  directory alone while its socket answers.
649
1116
 
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
1117
+ Each tab is a window of the server, whose process is the viewer itself,
1118
+ with no shell between them. Beside the keeper it holds up to four. Up
1119
+ to two are displayed, each group's shown tab ([Splits](#splits)), and
1120
+ every tab has its group's size: a resize resizes each tab's window in the
1121
+ groups drawn. Only the displayed tabs' panes are captured, and only the
1122
+ focused group's shown tab is typed into.
1123
+
1124
+ **A tab that is not drawn sends no output, from its mark on.** A hidden
1125
+ tab is heard until it prints: its first output captures nothing, sets its
1126
+ mark, and pauses its pane for `oats tui`'s control client
1127
+ (`refresh-client -A '%<pane>:pause'`, tmux 3.2 and later). From then on tmux sends none of
1128
+ that pane's output until the tab is displayed again, so a hidden agent
1129
+ that prints without pause costs one chunk of output each time its tab is
1130
+ hidden, and a quiet one nothing. The panel hidden as a whole (another
1131
+ view or an overlay over it, or the list alone under 80 columns) pauses
1132
+ its displayed tabs the same way. A
1133
+ paused pane is still read by the private server, so its screen stays
1134
+ current and its viewer never waits. A tab displayed again is continued
1135
+ (`:continue`) before it is captured: tmux restarts its output from where
1136
+ the pane is then, so the first frame is the pane's screen as it is, and
1137
+ nothing written meanwhile is replayed. `pause`, not `off`: from tmux 3.4
1138
+ on, a pane the control client has turned off is no longer read at all, so
1139
+ its viewer would stall and its screen go stale. Measured with a hidden tab
1140
+ printing without pause, `oats tui` takes about 0.4% of a core instead of
1141
+ 11%, and the private server 9% instead of 14%.
1142
+
1143
+ The panel refuses a fifth open (`E_PANEL_FULL`, an open
1144
+ still under way counted) and a second open while one is under way
1145
+ (`E_PANEL_BUSY`); the TUI asks for neither, since it refuses such an open
1146
+ itself ([Tabs](#tabs)). It is closed with `kill-pane`, which hangs up
652
1147
  the viewer's terminal: the viewer gets SIGHUP at once and removes its own
653
1148
  session on the agents' server. The viewer's error output goes to a file
654
1149
  of the run's directory (0600), read back when it ends and deleted. Its
@@ -658,22 +1153,28 @@ with the Desktop (`packages/client/`).
658
1153
  before it has that status (3.4 does, when the viewer's terminal hangs up a
659
1154
  moment before its process is reaped): `oats tui` then waits for the
660
1155
  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
1156
+ on tmux 3.2, which never says which signal ended a pane). A tmux built
1157
+ with libutempter can lose a status for good: as it destroys a pane at
1158
+ the hang-up, libutempter holds back SIGCHLD while its helper runs, and
1159
+ tmux, which reaps only on a SIGCHLD, leaves a viewer that exited in that
1160
+ moment unreaped (tmux 3.4). So while `oats tui` waits it sends the server
1161
+ `run-shell true` at once and every second: that child's end makes tmux
1162
+ reap the viewer too, and its status follows at the next report. A pane whose
662
1163
  status has not come by then is taken as ended without one, and closed:
663
1164
  the terminal closes with the line that the viewer ended without saying
664
- why. What the terminal
1165
+ why. What the shown terminal
665
1166
  shows is captured into `capture` in that directory, which the server
666
1167
  writes and `oats tui` reads back, so nothing an agent prints passes
667
1168
  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
1169
+ answer the server would never give ends that stream, and every tab
1170
+ closes with it. The server is ended
670
1171
  on every way out a process can handle. At its start a run also removes
671
1172
  what a run that is gone left (below), and nothing else: it signals
672
1173
  nothing.
673
1174
  - **Every read runs in a session of its own** and is ended when the TUI
674
1175
  ends, on every way out a process can handle (for SIGKILL see
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
1176
+ [below](#what-it-changes-in-your-terminal-and-restores)). Every tab's
1177
+ viewer ends with the private server. A read that was
677
1178
  running when the TUI is suspended is dropped, not shown: its answer could
678
1179
  arrive cut. That holds for the read of the other machines too. The return
679
1180
  reads again.
@@ -693,9 +1194,24 @@ with the Desktop (`packages/client/`).
693
1194
  writing to them), and the directory is removed. `oats tui` waits for an
694
1195
  apply's answer for 10 minutes and for a start's for 60 seconds; then it
695
1196
  says so, and the change goes on.
1197
+ - **A spawn runs the kernel's own `oats spawn`**, as the Desktop does: the
1198
+ prepare (a read, with the choices on screen) and then the apply of the
1199
+ decision on screen (`--expect-decision`, `--idempotency-key`), a change
1200
+ like the acts', with its output in the same directory. It has the
1201
+ deadline the shared apply gives it, as the Desktop's has: 60 seconds,
1202
+ more for each worktree setup a capability runs. Past it, the spawn is
1203
+ sent SIGTERM (by `oats tui`, through the shared apply), and on an OATS
1204
+ that rolls a spawn back on it, SIGKILL 20 seconds later if it still
1205
+ runs: the outcome is then not known, and `C` checks it. Those timers are
1206
+ the run's: once `oats tui` has gone, no deadline of a spawn it let go
1207
+ signals it, and none keeps the process waiting. The shared apply
1208
+ writes the task file `oats spawn --task-file` reads, empty, under the
1209
+ system's temporary directory (`oats-desktop-task-*`, mode 0600), and
1210
+ removes it when the spawn answers; a spawn let go on the way out leaves
1211
+ it.
696
1212
  - It runs no other command that changes a deployment or a registration, and
697
1213
  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
1214
+ keeper's FIFO `alive`, `capture` (the shown terminal's screen, which the
699
1215
  server writes there for `oats tui` to read), and `owner.json` (`{ "tool":
700
1216
  "oats-tui", "pid": …, "started": … }`), which lets a later run tell a
701
1217
  directory a run that is gone left. A run that ends normally removes all
@@ -708,7 +1224,8 @@ with the Desktop (`packages/client/`).
708
1224
  | To | Run |
709
1225
  |---|---|
710
1226
  | start an agent with another harness or model | `oats session start --home <home>` with its options |
711
- | see souls, spawn an agent | `oats souls`, `oats spawn <soul>` |
1227
+ | spawn an agent on another machine | `oats spawn <soul> --server <id>` |
1228
+ | spawn an agent with another harness, model or task | `oats spawn <soul>` with its options |
712
1229
  | see capabilities | `oats capabilities` |
713
1230
  | add a machine to this workspace | `oats server connect <id> --ssh <alias>` |
714
1231
  | check a machine | `oats server check <id>` |
@@ -727,12 +1244,17 @@ version:
727
1244
  opened with `oats tui --dir <path>`.
728
1245
  - **A row of another machine shows what its host reported at the last
729
1246
  read,** not what is true at this moment. The time of that read is on the
730
- machine's heading. A view of one machine has no heading: there the header
731
- names the machine (`on garnet`) and carries the time.
732
- - Souls and Capabilities, when they come, are this machine's.
1247
+ machine's heading when it is not the header's time. A view of one machine
1248
+ has no heading: there the header names the machine (`on garnet`) and
1249
+ carries the time.
1250
+ - The Souls view lists a workspace of this machine's souls, and
1251
+ Capabilities, when it comes, is this machine's too.
733
1252
  - There is no sorting and no mouse, and a deployment's heading cannot be
734
1253
  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.
1254
+ - Up to four terminals are open at a time, as tabs, in at most two
1255
+ groups. The split cannot be resized or nested, a tab moves only between
1256
+ the two groups, and no tab or split is kept from one run to the next, or
1257
+ across a switch of workspace.
736
1258
  - With an OATS older than 0.52.0, after an interrupted stop the instance can
737
1259
  be started and then cannot be stopped while `.oats-stop-pending.json` exists
738
1260
  in its home.
@@ -789,9 +1311,10 @@ suspends as one job.
789
1311
 
790
1312
  **While an agent's terminal is open** the terminal stays `oats tui`'s: the
791
1313
  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.
1314
+ `oats tui` draws what the displayed tabs' panes show. Every way out in the
1315
+ table above ends the private server and with it every tab's viewer, with
1316
+ that status. A suspend
1317
+ leaves the server and its viewers running; `fg` draws the terminal afresh.
795
1318
 
796
1319
  `Ctrl+C` is the quit key: in raw mode the terminal sends it as a byte, not as
797
1320
  a signal, so it answers 0. A SIGINT sent from outside (`kill -INT`) answers
@@ -804,9 +1327,9 @@ on tmux 3.7c, `reset` brought back the cursor and autowrap, and the pane
804
1327
  stayed in the alternate screen until `tput rmcup`. Nothing else is left in
805
1328
  tmux: `oats tui` creates no session, window, option or key binding.
806
1329
  Nor can it end a read after SIGKILL: nothing of the TUI runs any more, so a
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`
1330
+ read that was in flight runs to its own end. The open terminals' private
1331
+ server is ended by its keeper as soon as `oats tui` is gone, so each tab's
1332
+ viewer has its terminal hung up and removes its own session. A stopped `oats tui`
810
1333
  (`Ctrl+Z`, SIGSTOP) still holds the keeper's FIFO, so its server is left
811
1334
  alone. The next run removes the directory that is left, with its `tmux`,
812
1335
  `alive`, `capture` and `owner.json`.
@@ -853,13 +1376,16 @@ alone. The next run removes the directory that is left, with its `tmux`,
853
1376
  socket but to ask whether a dead run's still answers.
854
1377
  - It starts no daemon, and writes no file but the output of a change and
855
1378
  its private server's own, in its own directory
1379
+ ([above](#what-it-reads-and-what-it-runs)), and a spawn's empty task file
856
1380
  ([above](#what-it-reads-and-what-it-runs)). The processes it starts are
857
1381
  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
1382
+ viewers in it, one for each tab, and the acts you confirm. No read, server or viewer
859
1383
  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
1384
+ in flight runs to its own end, and the private server and its viewers end
861
1385
  by themselves. An act you confirmed is never ended by `oats tui`: it runs
862
- to its own end.
1386
+ to its own end. A spawn is ended only at its deadline, while `oats tui`
1387
+ runs ([above](#what-it-reads-and-what-it-runs)): never on the way out,
1388
+ and never after it.
863
1389
 
864
1390
  ## Errors
865
1391