@awebai/oats 0.63.0 → 0.65.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 (47) hide show
  1. package/README.md +14 -1
  2. package/bin/oats.mjs +158 -26
  3. package/docs/desktop-cli-api.md +127 -3
  4. package/docs/desktop.md +14 -5
  5. package/docs/execution-targets.md +9 -5
  6. package/docs/first-team.md +6 -0
  7. package/docs/implementation.md +17 -3
  8. package/docs/official-catalog.md +1 -1
  9. package/docs/packages.md +5 -5
  10. package/docs/release-notes/v0.64.0.md +105 -0
  11. package/docs/release-notes/v0.65.0.md +187 -0
  12. package/docs/souls-and-instances.md +26 -6
  13. package/docs/tui.md +416 -238
  14. package/docs/upgrading.md +2 -1
  15. package/docs/workspaces.md +125 -1
  16. package/lib/core.mjs +43 -11
  17. package/lib/deployments.mjs +325 -0
  18. package/lib/resolved-deployment.mjs +37 -0
  19. package/lib/session-input.mjs +12 -2
  20. package/lib/workspace.mjs +2 -0
  21. package/package-catalog.json +1 -1
  22. package/package.json +1 -1
  23. package/packages/client/cli-locator.mjs +2 -2
  24. package/packages/client/deployment-label.mjs +2 -2
  25. package/packages/client/deployment-list-cli.mjs +98 -0
  26. package/packages/client/deployment-list.mjs +91 -0
  27. package/packages/client/instance-tree.mjs +53 -3
  28. package/packages/client/keymap.mjs +106 -0
  29. package/packages/client/own-codes.mjs +2 -0
  30. package/packages/client/panel-views.mjs +1 -1
  31. package/packages/client/roster-sections.mjs +22 -6
  32. package/packages/client/workspace-admission.mjs +2 -1
  33. package/packages/tui/README.md +4 -4
  34. package/packages/tui/lib/actions.mjs +29 -5
  35. package/packages/tui/lib/client.mjs +3 -1
  36. package/packages/tui/lib/config.mjs +21 -14
  37. package/packages/tui/lib/main.mjs +108 -31
  38. package/packages/tui/lib/model.mjs +71 -41
  39. package/packages/tui/lib/read.mjs +15 -45
  40. package/packages/tui/lib/store.mjs +158 -39
  41. package/packages/tui/lib/term/through.mjs +40 -18
  42. package/packages/tui/lib/views/act.mjs +17 -13
  43. package/packages/tui/lib/views/frame.mjs +418 -421
  44. package/packages/tui/lib/views/help.mjs +41 -19
  45. package/packages/tui/lib/views/instances.mjs +38 -9
  46. package/packages/tui/lib/views/switcher.mjs +65 -21
  47. package/skills/oats-getting-started/SKILL.md +440 -170
package/docs/tui.md CHANGED
@@ -48,11 +48,27 @@ Another deployment is opened from [the switcher](#the-switcher), in the
48
48
  same run.
49
49
 
50
50
  **Outside every deployment.** Started with no `--dir` in a directory that
51
- is in no deployment, it looks directly inside `~/Agents`. When a deployment
52
- is there it starts with the switcher, and nothing is open until you open a
53
- row. When none is there it prints one line (`E_NO_DEPLOYMENT`) and exits 1
54
- without touching the terminal. With `--dir`, nothing is offered in place of
55
- a path that is in no deployment: the same line, and exit 1.
51
+ is in no deployment, it reads this computer's list of deployments,
52
+ `oats deployments --json` ([This computer's
53
+ deployments](workspaces.md#this-computers-deployments)), through the kernel
54
+ it shipped with. When the list holds a row it starts with the switcher, and
55
+ nothing is open until you open a row. When the list holds none it prints
56
+ one line (`E_NO_DEPLOYMENT`) and exits 1 without touching the terminal, and
57
+ when the list cannot be read it prints the kernel's code and message
58
+ instead, which say what to do. With `--dir`, nothing is offered in place of
59
+ a path that is in no deployment: the `E_NO_DEPLOYMENT` line that names
60
+ `--dir`, and exit 1.
61
+
62
+ **Opening a deployment lists it.** The deployment a run starts in, from
63
+ where you are or from `--dir`, is added to this computer's list once, as the
64
+ TUI's (`oats deployments add <path> --via tui --json`), also when you had
65
+ removed it from the list. It is best effort: a failure opens nothing less,
66
+ and is said once, in the line under the title, in the kernel's words. When
67
+ it comes while the switcher, the help, a confirmation, the palette, the
68
+ spawn prompt, a detail or a terminal has the screen or the focus, it is said
69
+ once a view's list has the focus again, so no screen that covers the
70
+ sidebar hides it. A deployment opened from the switcher is
71
+ on the list already.
56
72
 
57
73
  **From inside an agent's pane it still reads the deployment you asked
58
74
  for.** An instance session carries variables that make a kernel command
@@ -79,44 +95,82 @@ runs.
79
95
  ## What it shows
80
96
 
81
97
  ```
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.
98
+ acme-platform │ dev
99
+ │ soul dev
100
+ Instances 1 │ state running
101
+ > ● dev │ harness claude, claude-opus-5-5 (so…
102
+ │ work worktree, agents/dev
103
+ ● reviewer !│ team eng
104
+ ○ helper │ started 11:00
105
+ ──────────────────────────────────────│ home …oy/agents/dev/instances/dev
106
+ Souls 2 │
107
+ Capabilities 3 │
108
+ ──────────────────────────────────────│
109
+ Alt+O commands │
110
+ Ctrl+K palette │
111
+ Enter open │
112
+ n spawn │
113
+ ? help │
114
+ q quit │
115
+ │
116
+ │
97
117
  ```
98
118
 
99
- - **The header** starts with the workspace's name, then what the view holds of
100
- other machines, then the counts. Beside a deployment of this machine the
119
+ The screen is the sidebar on the left and the main area on the right, with
120
+ a rule between them over every row. There is no header and no footer. From
121
+ 80 columns the sidebar takes about half the width (36 to 60 columns, 30
122
+ while a terminal is open); under 80 columns it has the whole width.
123
+
124
+ - **The title** is the sidebar's first row: the workspace's name, then what
125
+ the view holds of other machines. Beside a deployment of this machine the
101
126
  other machines are counted: `+1 machine`, `+2 machines`. A view that holds
102
127
  no deployment of this machine names its one machine, `on garnet`, or
103
- counts them when there are two or more, `2 machines`. The counts are over
104
- every row of the view: instances running, instances that need input,
105
- stopped, state unknown, and rows the kernel reported that were withheld (a
106
- home outside its soul's directory, or one reported twice). A count of zero
107
- is left out. The second row names the views, `Instances Souls
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, and [the Capabilities view](#the-capabilities-view)
113
- its capabilities. On the right is the time of the read of this machine
114
- 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.
128
+ counts them when there are two or more, `2 machines`. While
129
+ [the switcher](#the-switcher) is shown the title is `workspaces`.
130
+ - **Under the title** stands what the view needs to say first, wrapped to
131
+ the sidebar's width: a deployment's state when it is not live, with
132
+ `since …` and its reason on rows of its own; the note of a view of one
133
+ deployment; and the line that says what happened after an open, an act or
134
+ a spawn. Then an empty row.
135
+ - **The views** follow as an accordion, always in this order: `Instances`,
136
+ `Souls`, `Capabilities`, each with its key dim at the right edge. The open
137
+ view's heading is bold and its list stands under it, with a rule between
138
+ it and the views before and after it. `1`, `2` and `3` open them in the
139
+ list, and [the leader](#the-leader) then `1`, `2` or `3` from anywhere;
140
+ the leader's hint, [the palette](#the-palette) and the help name those
141
+ keys. [The Souls view](#the-souls-view) lists the open workspace's souls,
142
+ and [the Capabilities view](#the-capabilities-view) its capabilities. A
143
+ workspace with no instances reads `No agents yet: n spawns one`, with the
144
+ key `spawn` has (`No agents yet.` when it has none).
145
+ - **The cheat sheet** comes last, under a rule: a few keys, one per row,
146
+ the key in bold and what it does beside it. Its first row is always the
147
+ leader, `Alt+O commands`, which reaches every action; then
148
+ `Ctrl+K palette`. In a view's list it names what `Enter` does now
149
+ (`open`, `focus terminal` on the row whose terminal is open, `detail`
150
+ in the Souls and Capabilities views), then `n spawn` where it spawns,
151
+ and `? help` and `q quit` last; with the detail's focus `Tab back`
152
+ comes before `Enter`. The other keys (the acts, `/`, `Tab`, `r`, `w`,
153
+ and a terminal's `z`, `c`, `[` and `]`) are not listed there:
154
+ the leader's hint, the palette and the help name them. While the
155
+ terminal has the focus, in an overlay and in the filter field it names
156
+ the keys that work them. While the leader waits for its key the rows are
157
+ the leader's hint.
158
+ Everything flows from the top, so empty rows are at the bottom. On a
159
+ short screen the list keeps its rows first: the cheat sheet gives up rows
160
+ from its end, down to the leader alone, then the empty row under the
161
+ title goes, and the list scrolls in what is left.
162
+ - **The main area** holds the selected row's detail, an
163
+ [open terminal](#open-an-agents-terminal), or an overlay: the switcher,
164
+ the palette, the spawn prompt, the help or a confirmation. From 80
165
+ columns an overlay covers the main area and the sidebar stays beside it,
166
+ its cheat sheet naming the overlay's keys. Under 80 columns the detail
167
+ and every overlay cover the whole screen, and their first row carries
168
+ their keys at the right, dim: the detail's `Tab back` first.
169
+ - **The counts and the time of the read are not on the screen.** The help's
170
+ top row has the time of the read of this machine that the screen shows,
171
+ `read 14:03:27`, which moves with every read, and how many rows the
172
+ kernel reported that were withheld (a home outside its soul's directory,
173
+ or one reported twice), `2 withheld`, when there are any.
120
174
  - **The list** is the roster the Desktop draws: the same groups in the same
121
175
  order, from the same code. It is in name order, by each group's top
122
176
  instance, so starting or stopping an instance moves nothing. An instance
@@ -132,7 +186,11 @@ runs.
132
186
  state of a home a spawn or a retire holds (`Retire didn't finish`), or
133
187
  the shared words for why an instance cannot be reached or opened:
134
188
  `gone from garnet`, `garnet not reached`, `not reachable on garnet`,
135
- `Herdr no longer supported`, `state unknown`.
189
+ `Herdr no longer supported`, `state unknown`. The words stand in a
190
+ column of their own. The name comes first: on a narrow sidebar, where
191
+ the column would leave the name less than 16 cells, the word is cut to
192
+ what the name leaves, or left out when that is under 6 cells; the mark
193
+ and the detail still say it.
136
194
  - **The detail** shows the selected instance: its soul, its state, and
137
195
  under it the reason when there is one, after the words that say who gave
138
196
  it: `OATS says:` for a kernel (this machine's, or the instance's
@@ -150,10 +208,10 @@ runs.
150
208
  link, either way, as the Desktop reads them: `sibling of a`, `sibling of
151
209
  a and b`, `sibling of a, b and c`. They are read inside the instance's
152
210
  own deployment, and a name that is no instance there, or two of them, is
153
- not shown. From 80 columns up it stands beside the list; on a narrower
154
- terminal `Tab` opens it as a page.
211
+ not shown. From 80 columns up it stands beside the sidebar; on a narrower
212
+ terminal `Tab` opens it as a page over the whole screen.
155
213
  - **Opening an agent.** `Enter` on an instance that runs opens its terminal
156
- beside the list, where the detail was, as a tab: see
214
+ beside the sidebar, where the detail was, as a tab: see
157
215
  [Open an agent's terminal](#open-an-agents-terminal) and [Tabs](#tabs).
158
216
 
159
217
  **A view of more than one deployment** (this machine and another, or two
@@ -165,9 +223,9 @@ deployments on one machine) is one list, grouped as the Desktop groups it:
165
223
  view. A heading cannot be selected or folded: the movement keys pass over
166
224
  it. A view of one deployment has no heading.
167
225
  - **A machine's heading is its name.** When its rows were read at another
168
- time than the one in the header, that time stands at the right of the
169
- heading: `read 14:03:21`. A row of another machine shows what its host
170
- reported at that time.
226
+ time than this machine's (the one on the help's top row), that time
227
+ stands at the right of the heading: `read 14:03:21`. A row of another
228
+ machine shows what its host reported at that time.
171
229
  - **A deployment that is not live carries its state and a short reason**
172
230
  on its heading, and no time: `garnet remembered Not reached`. The rows
173
231
  a machine last reported are kept when it is not reached, and each of them
@@ -187,21 +245,21 @@ deployments on one machine) is one list, grouped as the Desktop groups it:
187
245
  deployment, such as `garnet now reports workspace other.` for a machine
188
246
  that reported another workspace before, or that a deployment's teams are
189
247
  local only. It stands under the deployment's heading. In a view of one
190
- deployment, which has no heading, it stands above the list.
248
+ deployment, which has no heading, it stands under the title.
191
249
  - **The detail has a `machine` line**, the machine the selected instance is
192
250
  on. When that deployment is not live, the whole sentence that says why
193
251
  follows it.
194
252
 
195
- **A view that holds no deployment of this machine** says so in its header:
253
+ **A view that holds no deployment of this machine** says so in its title:
196
254
  `other on garnet` for one machine, `2 machines` after the name for
197
- two or more. The time in the header is then the time the machines' rows
198
- were read. A view of one machine has no heading, so its state, when it is
199
- not live, is said above the list with the reason, as for a deployment of
200
- this machine. When no row of that machine is kept either, nothing is drawn
255
+ two or more. The time on the help's top row is then the time the machines'
256
+ rows were read. A view of one machine has no heading, so its state, when it
257
+ is not live, is said under the title with the reason, as for a deployment
258
+ of this machine. When no row of that machine is kept either, nothing is drawn
201
259
  under the reason: no list and no detail.
202
260
 
203
261
  **A machine that has not answered in this run is not in its workspace's
204
- list.** `oats tui` keeps nothing on disk, so it cannot tell which workspace
262
+ list.** `oats tui` keeps nothing on disk of its own, so it cannot tell which workspace
205
263
  a machine belongs to before the machine has said so in this run. Such a
206
264
  machine is listed in [the switcher](#the-switcher) by its own name, under
207
265
  `Not matched to a workspace`. The OATS Desktop, which remembers what each
@@ -248,7 +306,7 @@ last rows stay as they were; or they stay and are marked `stale`, with the
248
306
  time of the last read that succeeded (a remote that could not be read
249
307
  again); or the
250
308
  deployment is `not observed` and no row is drawn. A state that is not live
251
- is said in words above the list, with the reason on rows of its own. When
309
+ is said in words under the title, with the reason on rows of its own. When
252
310
  the kernel refused the read and no rows are kept, the reason says so and
253
311
  quotes it: `OATS answered with an error (<code>). It says: <message>`. When
254
312
  the last rows are kept as `stale`, the reason says so and then quotes the
@@ -274,53 +332,63 @@ fit; the detail shows them whole. The TUI's own words end the same way:
274
332
  ## Open an agent's terminal
275
333
 
276
334
  ```
277
- acme-platform 2 running
278
- Instances Souls Capabilities read 14:03:27
279
- ──────────────────────────────┬─────────────────────────────────────────────────
280
- > ● backend-lead │ backend-lead
281
- ● docs-writer │$ make docs
282
- │Building the reference...
283
- │
284
- │
285
- C-\ commands C-\ C-\ back to the list
335
+ acme-platform │ backend-lead
336
+ │$ make docs
337
+ Instances 1 │Building the reference...
338
+ > ● backend-lead │
339
+ ● docs-writer │
340
+ ──────────────────────────────│
341
+ Souls 2 │
342
+ Capabilities 3 │
343
+ ──────────────────────────────│
344
+ Alt+O commands │
345
+ Alt+O Esc the list │
346
+ Alt+O Alt+O types Alt+O │
286
347
  ```
287
348
 
288
349
  - **`Enter` on an instance that runs** opens its terminal on the right of
289
- the body, where the detail was, with the list on the left. Its top row
290
- names the agent (and `on <machine>` for one of another machine); under it
291
- is the agent's screen, as the agent draws it, in its own colours. While a
292
- terminal is open the list keeps 30 columns at most, also while the
350
+ the sidebar, where the detail was, over every row. Its top row names the
351
+ agent (and `on <machine>` for one of another machine); under it is the
352
+ agent's screen, as the agent draws it, in its own colours. While a
353
+ terminal is open the sidebar keeps 30 columns at most, also while the
293
354
  detail stands in the terminal's place, and a name longer than its row is
294
355
  cut with `…` (`...` in ASCII).
295
356
  - **The terminal has the focus.** What you type, what you paste and every
296
357
  key go to the agent exactly as typed, `Ctrl+C`, `Ctrl+Z`, `Esc` and `q`
297
- among them, but for **[the leader](#the-leader)** (`Ctrl+\` unless
298
- [`tui.json`](#change-the-keys-tuijson) names another), the one key the
299
- TUI takes from the agent. The leader twice gives the focus to the list;
300
- the leader then another key does what that key does from anywhere. While
301
- the terminal has the focus the footer names it, and the leader twice:
302
- `C-\ commands C-\ C-\ back to the list`. A leader inside a bracketed
303
- paste is pasted, not taken.
358
+ among them, but for **[the leader](#the-leader)** (`Alt+O`, `Ctrl+\` on
359
+ macOS, unless [`tui.json`](#change-the-keys-tuijson) names another), the
360
+ one key the TUI takes from the agent. The leader then `Esc` gives the
361
+ focus to the list; the leader twice types the leader into the agent; the
362
+ leader then another key does what that key does from anywhere. While the
363
+ terminal has the focus the cheat sheet names those three:
364
+ `Alt+O commands`, `Alt+O Esc the list`, `Alt+O Alt+O types Alt+O`. A
365
+ leader inside a bracketed paste is pasted, not taken.
304
366
  - **With the list focused** the terminal stays open, and the agent's screen
305
- is still drawn as it changes. The footer names the keys for it:
306
- `Enter focus terminal` on its row, `z zoom` and `c close terminal`.
367
+ is still drawn as it changes. The cheat sheet names `Enter focus terminal`
368
+ on its row; the leader's hint names `z zoom` and `w close terminal`.
307
369
  - `Enter` on the shown terminal's row gives it the focus again.
308
- - `z` gives it the focus and the whole body: the header and the footer
309
- stay, the list is hidden. The leader twice brings the list back beside
310
- it, and the leader then `z` zooms it out and in without leaving it.
311
- - `c` closes it: the agent keeps running. The tab beside it is shown;
312
- with no other tab the right side is the detail again.
370
+ - `z` gives it the focus and the whole screen: the sidebar is hidden. The
371
+ leader then `Esc` brings the sidebar back beside it, and the leader then
372
+ `z` zooms it out and in without leaving it.
373
+ - `c` closes it, and the leader then `w` from anywhere: the agent keeps
374
+ running. The tab beside it is shown; with no other tab the right side
375
+ is the detail again.
313
376
  - `Tab` shows the detail in its place until `Tab` or `Esc`. Nothing of
314
377
  the terminal is drawn meanwhile, and its screen is read afresh when it
315
378
  shows again.
316
379
  - **Up to four terminals are open at a time, each a tab.** `Enter` on
317
380
  another instance that runs opens its terminal in a new tab, and the
318
381
  others stay open: see [Tabs](#tabs).
319
- - **Under 80 columns** the terminal is always shown with the whole body
320
- when it has the focus. With the list focused the list is shown alone; the
321
- terminal stays open, unseen, and `Enter focus terminal` in the footer
322
- shows it again. Beside the list the terminal is never narrower than 40
323
- columns.
382
+ - **Under 80 columns** the terminal is always shown with the whole screen
383
+ when it has the focus. With the list focused the sidebar is shown alone;
384
+ the terminal stays open, unseen, and `Enter focus terminal` in the cheat
385
+ sheet shows it again. Beside the sidebar the terminal is never narrower
386
+ than 40 columns: with less room it has the whole screen too.
387
+ - **With the whole screen** (zoomed, or a narrow terminal) no cheat sheet is
388
+ drawn. The terminal's title row carries the keys at its right, dim:
389
+ `Alt+O commands Alt+O Esc the list`, and while the leader waits, the
390
+ leader's hint, as many keys as fit, `Esc the list` last. The agent's
391
+ screen keeps every row under it.
324
392
  - **A terminal also closes by itself** when its viewer ends, shown or
325
393
  hidden ([which tab is shown then](#tabs)): the agent's
326
394
  window ended, its session went away, or the link to its machine dropped.
@@ -331,7 +399,7 @@ C-\ commands C-\ C-\ back to the list
331
399
  terminal without it when it has not come. A tmux built with libutempter
332
400
  (Ubuntu's and Debian's are) can lose that status: while it waits,
333
401
  `oats tui` has tmux look for it again once a second, so the terminal
334
- 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
402
+ still closes within a second or two with the line its status calls for. The instances are then read again at once, and the line under the title
335
403
  says what happened: that it could not be opened, that the connection to
336
404
  its machine ended, or that the viewer ended without saying why. What the
337
405
  viewer printed on its error output stands under that line in quotation
@@ -360,15 +428,19 @@ C-\ commands C-\ C-\ back to the list
360
428
  ## Tabs
361
429
 
362
430
  ```
363
- acme-platform 3 running
364
- Instances Souls Capabilities read 14:03:27
365
- ──────────────────────────────┬─────────────────────────────────────────────────
366
- > ● backend-lead │ backend-lead docs-writer• qa-runner
367
- ● docs-writer │$ make test
368
- ● qa-runner │ok 41 of 41
369
- │
370
- │
371
- C-\ commands C-\ C-\ back to the list
431
+ acme-platform │ backend-lead docs-writer• qa-runner
432
+ │$ make test
433
+ Instances 1 │ok 41 of 41
434
+ > ● backend-lead │
435
+ ● docs-writer │
436
+ ● qa-runner │
437
+ ──────────────────────────────│
438
+ Souls 2 │
439
+ Capabilities 3 │
440
+ ──────────────────────────────│
441
+ Alt+O commands │
442
+ Alt+O Esc the list │
443
+ Alt+O Alt+O types Alt+O │
372
444
  ```
373
445
 
374
446
  Each terminal open in the panel is a tab, and the panel holds up to four.
@@ -400,16 +472,15 @@ Each terminal open in the panel is a tab, and the panel holds up to four.
400
472
  machine is asked whether it can be opened, another open does nothing,
401
473
  and neither does a key that shows another tab.
402
474
  - **At four tabs nothing closes by itself.** The open does nothing, and
403
- the line above the panes says `4 terminals are open; close one with C-\ w.`
475
+ the line under the title says `4 terminals are open; close one with Alt+O w.`
404
476
  (with your leader, when [`tui.json`](#change-the-keys-tuijson) names
405
477
  another). A tab still starting, and an agent of another machine while
406
478
  it is asked, hold a place among the four. An instance that cannot be
407
479
  opened says why, as it does with no tab open.
408
480
  - **Switching.** `[` and `]` in the Instances view, from the list or the
409
- detail, show the tab before or after the shown one; the footer names them
410
- (`[/] tab`) after the terminal's keys while two tabs or more are open, and
411
- gives them up after the acts, `workspaces`, `refresh` and `close`, before
412
- `detail`. The leader then
481
+ detail, show the tab before or after the shown one; the help names them,
482
+ and the leader's hint names the leader's own while two tabs or more are
483
+ open. The leader then
413
484
  `Left` or `Right` does the same from any focus, and from another view
414
485
  goes to the Instances view first.
415
486
  - The strip does not wrap: on the first tab `[` does nothing, and on the
@@ -433,13 +504,13 @@ Each terminal open in the panel is a tab, and the panel holds up to four.
433
504
  - Closing the last tab closes the panel: the right side is the detail
434
505
  again, and the list has the focus.
435
506
  - **A tab that closes by itself**, when its viewer ends, says so on the line
436
- above the panes in the words [above](#open-an-agents-terminal), for that
507
+ under the title in the words [above](#open-an-agents-terminal), for that
437
508
  tab's agent (no line when it ended cleanly).
438
509
  - The shown tab: the tab to its right is shown, else the one to its left,
439
510
  and the list takes the focus.
440
511
  - A hidden tab: the shown tab and the focus stay as they were.
441
- - **Zoom** (`z`, or the leader then `z`) gives the shown tab the whole body.
442
- The strip stays its top row, and the other tabs stay open.
512
+ - **Zoom** (`z`, or the leader then `z`) gives the shown tab the whole
513
+ screen. The strip stays its top row, and the other tabs stay open.
443
514
  - **The tabs are the open workspace's.** Opening another workspace in
444
515
  [the switcher](#the-switcher) closes them all, and so does the open
445
516
  workspace no longer being listed; their agents keep running. Coming back
@@ -448,15 +519,19 @@ Each terminal open in the panel is a tab, and the panel holds up to four.
448
519
  ## Splits
449
520
 
450
521
  ```
451
- acme-platform 3 running
452
- Instances Souls Capabilities read 14:03:27
453
- ──────────────────────────────┬─────────────────────────────────────────────────────────────────────────────────
454
- ● backend-lead │ backend-lead docs-writer │ qa-runner
455
- ● docs-writer │$ git log --oneline -2 │$ make test
456
- > ● qa-runner │4be1c0d Fix the reader │ok 41 of 41
457
- │9a03e7f Add the roster │
458
- │ │
459
- C-\ commands C-\ C-\ back to the list
522
+ acme-platform │ backend-lead docs-writer │ qa-runner
523
+ │$ git log --oneline -2 │$ make test
524
+ Instances 1 │4be1c0d Fix the reader │ok 41 of 41
525
+ ● backend-lead │9a03e7f Add the roster │
526
+ ● docs-writer │ │
527
+ > ● qa-runner │ │
528
+ ──────────────────────────────│ │
529
+ Souls 2 │ │
530
+ Capabilities 3 │ │
531
+ ──────────────────────────────│ │
532
+ Alt+O commands │ │
533
+ Alt+O Esc the list │ │
534
+ Alt+O Alt+O types Alt+O │ │
460
535
  ```
461
536
 
462
537
  The panel can be split in two **groups**, side by side or one above the
@@ -469,9 +544,9 @@ tab and the marks of its hidden ones.
469
544
  (left, or top). The second group starts empty and is the focused group.
470
545
  - A split needs a tab open, and none starting.
471
546
  - **There are at most two groups.** With two, the split keys do nothing,
472
- and the line above the panes says `The panel has two groups already.`
547
+ and the line under the title says `The panel has two groups already.`
473
548
  - **Each group needs 40 columns side by side, and 8 rows one above the
474
- other**, its strip counted. The panel beside the list then needs 81
549
+ other**, its strip counted. The panel beside the sidebar then needs 81
475
550
  columns (a terminal of 112), or 17 rows. A split that would leave a
476
551
  group smaller does nothing, and the line says so:
477
552
  `No room to split side by side: each group needs 40 columns.` or
@@ -490,10 +565,10 @@ tab and the marks of its hidden ones.
490
565
  it. **When the terminal becomes too small for both groups,** the split
491
566
  stays and the focused group is drawn alone; the other group's shown tab
492
567
  is not drawn, only marked, until there is room again.
493
- - **Under 80 columns** the terminal's focus gives the whole body to both
494
- groups, and the list's focus shows the list alone, as with one group.
568
+ - **Under 80 columns** the terminal's focus gives the whole screen to both
569
+ groups, and the list's focus shows the sidebar alone, as with one group.
495
570
  - **Zoom** (`z`, or the leader then `z`) gives the focused group's shown
496
- terminal the whole body, and the same key brings the split back. With
571
+ terminal the whole screen, and the same key brings the split back. With
497
572
  the empty group focused it does nothing.
498
573
  - **Opening.** `Enter`, the palette, the leader then `Up`/`Down` and a
499
574
  spawn open as with one group:
@@ -502,7 +577,7 @@ tab and the marks of its hidden ones.
502
577
  - any other: a new tab in the focused group, after its shown tab, or as
503
578
  the first tab of the empty group.
504
579
  - **The four tabs are counted across both groups.** At four, the line
505
- says `4 terminals are open; close one with C-\ w.` as with one group.
580
+ says `4 terminals are open; close one with Alt+O w.` as with one group.
506
581
  - **Moving between the groups.** The leader then `Tab` from a terminal goes
507
582
  to the other group's shown terminal, or to the other group when it is
508
583
  empty. From the list it goes to the focused group's terminal, or, with
@@ -537,14 +612,23 @@ ones `oats spawn` can make an instance of here, as the OATS Desktop lists
537
612
  them, from the same code.
538
613
 
539
614
  ```
540
- acme-platform 2 running 1 stopped
541
- Instances Souls Capabilities read 14:03:27
542
- ──────────────────────────────────────┬─────────────────────────────────────────
543
- > ■ dev ·2 │ dev
544
- ■ ops ! │ Builds and ships the platform.
545
- ■ reviewer ·1 │
546
- │ from oats-core
547
- │ works works in its own worktree
615
+ acme-platform │ dev
616
+ │ Builds and ships the platform.
617
+ Instances 1 │ from oats-core
618
+ ──────────────────────────────────────│ works works in its own worktree
619
+ Souls 2 │ harness
620
+ > ■ dev ·2 │ No default harness: you choose one
621
+ ■ ops ! │ when you launch it.
622
+ ■ reviewer ·1 │ instances here
623
+ ──────────────────────────────────────│ ● dev-1 ● dev-2
624
+ Capabilities 3 │ i shows them in the Instances view.
625
+ ──────────────────────────────────────│
626
+ Alt+O commands │
627
+ Ctrl+K palette │
628
+ Enter detail │
629
+ n spawn │
630
+ ? help │
631
+ q quit │
548
632
  ```
549
633
 
550
634
  - **A row** is the soul's colour mark (`■`, `#` in ASCII; its colour is the
@@ -559,10 +643,10 @@ them, from the same code.
559
643
  problem as the kernel reports it); its teams, the default first; its
560
644
  capabilities; and its instances on this machine, eight at most and then
561
645
  `+n`. `Enter` gives the detail the focus (under 80 columns it takes the
562
- list's place), and the movement keys then scroll it.
646
+ whole screen), and the movement keys then scroll it.
563
647
  - **`i`**, or `Enter` in the detail, shows that soul's instances in the
564
- Instances view: an exact filter, shown where a kept filter stands in
565
- the footer, `soul dev`.
648
+ Instances view: an exact filter, named where a kept filter stands, on
649
+ the view's heading: `Instances soul dev`.
566
650
  An instance of another soul whose name holds `dev` is not listed. `Esc`
567
651
  clears it, and `/` replaces it with a text filter.
568
652
  - **`r`** reads the souls again; while a read is under way it starts
@@ -593,25 +677,26 @@ the ones its repositories and its packages offer, as the OATS Desktop lists
593
677
  them, from the same code.
594
678
 
595
679
  ```
596
- acme-platform 3 running
597
- Instances Souls Capabilities read 14:03:27
598
- ──────────────────────────────────────┬─────────────────────────────────────────
599
- Workspace owned │ aweb Messaging
600
- oats · member repo · host │ Messaging over aweb, mail and chat,
601
- > aweb Messaging │ for every instance of the workspace.
602
- tools · member repo │
603
- notes │ Comes from
604
- Packages │ Repository oats
605
- oats-okf · package · v1.2.0 │ Latest bbbbbbb
606
- okf-knowledge Knowledge │ Path capabilities/aweb
607
- │
608
- │ Provides
609
- │ Skills oats-aweb, aweb-messaging
610
- │ Hooks SessionStart
611
- │
612
- │ Used by 2 souls
613
- │ ■ dev ·2 · 1 on an older version
614
- │ ■ reviewer ·1
680
+ acme-platform │ aweb Messaging
681
+ │ Messaging over aweb, mail and chat,
682
+ Instances 1 │ for every instance of the workspace.
683
+ Souls 2 │
684
+ ──────────────────────────────────────│ Comes from
685
+ Capabilities 3 │ Repository oats
686
+ Workspace owned │ Latest bbbbbbb
687
+ oats · member repo · host │ Path capabilities/aweb
688
+ > aweb Messaging │
689
+ tools · member repo │ Provides
690
+ notes │ Skills oats-aweb, aweb-messaging
691
+ Packages │ Hooks SessionStart
692
+ oats-okf · package · v1.2.0 │
693
+ okf-knowledge Knowledge │ Used by 2 souls
694
+ ──────────────────────────────────────│ ■ dev ·2 · 1 on an older version
695
+ Alt+O commands │ ■ reviewer ·1
696
+ Ctrl+K palette │
697
+ Enter detail │
698
+ ? help │
699
+ q quit │
615
700
  ```
616
701
 
617
702
  - **The list** is in the Desktop's sections: Workspace owned, Repo owned
@@ -647,7 +732,7 @@ them, from the same code.
647
732
  `Reading souls…`, and a read of them that fails says why, in the
648
733
  warning style.
649
734
  - **`Enter`** gives the detail the focus (under 80 columns it takes the
650
- list's place), with a mark, `>` in reverse video, on the first soul of
735
+ whole screen), with a mark, `>` in reverse video, on the first soul of
651
736
  Used by. `Up` and `Down` move the mark among the listed souls, and the
652
737
  detail scrolls to keep it in sight. Past the first or the last soul, and
653
738
  with the other movement keys, the detail scrolls; with no soul listed
@@ -680,25 +765,25 @@ selected.
680
765
 
681
766
  ## The switcher
682
767
 
683
- `w` opens the switcher: what this run can show, over the whole body of the
684
- screen.
768
+ `w` opens the switcher: what this run can show, over the main area. The
769
+ sidebar's title says `workspaces` and no view is open; under 80 columns the
770
+ switcher covers the whole screen.
685
771
 
686
772
  ```
687
- workspaces
688
- Instances Souls Capabilities
689
- ────────────────────────────────────────────────────────────────────────────────
690
- > * acme-platform This machine · garnet
691
- ledger quartz
692
- Not matched to a workspace
693
- basalt ssh needs a prompt
694
- On this machine, not opened
695
- acme-docs ~/Agents/acme-docs
696
- sandbox ~/Agents/sandbox
697
-
698
-
699
-
700
-
701
- C-\ commands Enter open / filter r refresh Esc close ? help q quit
773
+ workspaces │ > * acme-platform This machine · garnet
774
+ │ ledger quartz
775
+ Instances 1 │ Not matched to a workspace
776
+ Souls 2 │ basalt ssh needs a prompt
777
+ Capabilities 3 │ On this machine, not opened
778
+ ────────────────────────────────────────────────│ acme-docs ~/acme-docs
779
+ Alt+O commands │ sandbox Not found.
780
+ Ctrl+K palette │
781
+ Enter open │
782
+ / filter │
783
+ r refresh │
784
+ Esc close │
785
+ ? help │
786
+ q quit │
702
787
  ```
703
788
 
704
789
  It lists, in this order:
@@ -712,27 +797,63 @@ It lists, in this order:
712
797
  - **`Not matched to a workspace`**: what those rules matched to no
713
798
  workspace, each by its own name with a short reason. A machine that has
714
799
  not answered in this run is listed here.
715
- - **`On this machine, not opened`**: the deployments directly inside
716
- `~/Agents` that this run has not opened, each by its folder's name and
717
- its path. Nothing is read from one before it is picked. `~/Agents` is
718
- looked at up to its first 200 entries; when it holds more, a last row says
719
- `More folders than are listed here.`
800
+ - **`On this machine, not opened`**: the rows of this computer's list of
801
+ deployments (`oats deployments`) that this run has not opened, in the
802
+ list's order, each by its folder's name and its path. Nothing is read from
803
+ one before it is picked. A row that cannot be opened says why where its
804
+ path stood, and does not open:
805
+
806
+ | The row says | The list's state |
807
+ |---|---|
808
+ | `Not found.` | `missing`: the folder is gone, or on a volume that is not mounted |
809
+ | `Not an OATS deployment any more.` | `not-a-deployment`: the folder has no `oats-local.yaml` |
810
+ | `Can't be read.` | `unreadable`: the check failed, for example for a permission |
811
+
812
+ The list is read when the switcher opens, on `r` in it and after a
813
+ Remove. When a read fails, the rows of the last read stay, under a line
814
+ that says the list could not be read, with the kernel's message.
720
815
 
721
816
  | Key | Does |
722
817
  |---|---|
723
818
  | `Up` `k`, `Down` `j`, `g` `Home`, `G` `End`, `PageUp`, `PageDown` | move the selection among the rows; a heading is passed over |
724
819
  | `Enter` | opens the selected row |
725
820
  | `/` | filters the rows by what they show: a name, the machines, a path |
726
- | `r` | reads now, and lists `~/Agents` again |
727
- | `Esc` | clears a kept filter; else closes the switcher, back to the view that was open |
821
+ | `r` | reads now, and reads this computer's list of deployments again |
822
+ | `Delete` | on a row of `On this machine, not opened`, asks whether to remove it from this computer's list; the cheat sheet names it while such a row is selected |
823
+ | `Esc` | while a Remove is asked, keeps the row; else clears a kept filter; else closes the switcher, back to the view that was open |
728
824
  | `1` | closes the switcher, back to the view that was open |
729
825
 
730
- **Enter on a workspace** opens its view. **Enter on a folder** opens that
731
- deployment in this run: from then on it is read with the others, and its
732
- workspace is the open view. A folder that stopped being a deployment since
733
- it was listed is not opened: its row says
826
+ **Enter on a workspace** opens its view. **Enter on a row of the list**
827
+ opens that deployment in this run: from then on it is read with the others,
828
+ and its workspace is the open view. A folder that stopped being a deployment
829
+ since the list was read is not opened: its row says
734
830
  `Not an OATS deployment any more.` where its path stood.
735
831
 
832
+ **Remove** takes a row off this computer's list
833
+ (`oats deployments remove <path>`); nothing on disk is touched, and the
834
+ folder stays. `Delete` on the row asks first, above the rows:
835
+
836
+ ```
837
+ Remove the selected row from this computer's list?
838
+ Enter removes it; other keys keep it. Its folder stays.
839
+ ```
840
+
841
+ `Enter` removes it, and the list is read again; `Esc`, or any other key,
842
+ keeps it (the other key then does what it does). These are the keys
843
+ themselves, whatever your `tui.json` gives `open` and `close`. The question
844
+ is about the row marked when it was asked: when a read of the list no longer
845
+ holds that row, the question goes. An `Enter` that came in
846
+ the same read of input as the `Delete` is not taken. What the kernel
847
+ answered stands above the rows: that the row was removed, or why it was not,
848
+ in the kernel's words. A removed deployment is not listed again by the
849
+ kernel on its own; opening it with `oats tui --dir <path>` lists it again.
850
+ A workspace this run has open has no Remove here.
851
+
852
+ `Delete` is the key and no letter is: a new default key that your
853
+ [`tui.json`](#change-the-keys-tuijson) already gives to another action
854
+ would make the file refused at the start. To use another key, give it to
855
+ `remove` there, for example `{ "keys": { "remove": ["x"] } }`.
856
+
736
857
  **Each view keeps its place while the run lasts:** the selected instance,
737
858
  where its list and its detail were scrolled, and what was folded away are
738
859
  found again when the view is opened again. A filter is not kept from one
@@ -764,17 +885,18 @@ none; one whose spawn stopped half way, and one whose retire failed or
764
885
  didn't finish, offers only to be retired; a running one offers restart and
765
886
  not start, a stopped one start and not restart. One that is `Retiring…`
766
887
  offers no start, stop, restart or open: `D` still opens its retire
767
- confirmation, but the footer does not name it, since the kernel refuses a
768
- second retire while one runs and it is needed only when the first one's
769
- holder can't be read. The
770
- footer names the keys the selected instance offers now, after `Enter`, and
771
- on a narrow terminal they are the first hints it gives up. A key for an act
772
- the instance does not offer opens nothing, and the line above the panes
888
+ confirmation, which is needed only when the first retire's holder can't be
889
+ read, since the kernel refuses a second retire while one runs. The
890
+ palette offers the acts the selected instance offers now, and the leader's
891
+ hint and the help name their keys. A key for an act
892
+ the instance does not offer opens nothing, and the line under the title
773
893
  says why. The keys are yours to change in
774
894
  [`tui.json`](#change-the-keys-tuijson): the actions are `stop`, `retire`,
775
895
  `start` and `restart`.
776
896
 
777
- **The confirmation** opens over the list, with the focus on `Cancel`.
897
+ **The confirmation** opens over the main area, with the focus on `Cancel`;
898
+ the cheat sheet names its keys (under 80 columns it covers the whole screen,
899
+ its keys on its first row).
778
900
  `Left`/`Right` and `Tab`/`Shift+Tab` move between its buttons and `Enter`
779
901
  presses one. No letter moves the focus, and an `Enter` that arrives in the
780
902
  same read of input as the move onto the act's button is ignored, so pasted
@@ -844,7 +966,7 @@ The exit status never depends on it.
844
966
  one screen to read and one `Enter` to press.
845
967
 
846
968
  - **`n`** in the list of instances (or the leader then `n`, from any focus,
847
- a terminal's too) opens the soul picker over the list: the souls of
969
+ a terminal's too) opens the soul picker over the main area: the souls of
848
970
  [the Souls view](#the-souls-view), read with `oats souls` if they were
849
971
  not read yet (`Reading souls…` until then). Typing filters them with the
850
972
  palette's subsequence match; `Up`/`Down` move, `Enter` picks the selected
@@ -865,7 +987,7 @@ one screen to read and one `Enter` to press.
865
987
  - **One focus ring:** `Spawn` (where the focus starts), `name`, `child of`
866
988
  (when an instance of this machine was selected), then each folded part.
867
989
  `Tab` moves along it, `Shift+Tab` back. `Enter` does what the focus says,
868
- and the footer names it:
990
+ and the cheat sheet names it:
869
991
  - on `Spawn`, spawns what the preview shows;
870
992
  - on `name`, keeps the name typed and reads the preview again with it:
871
993
  the instance is named `<soul>-<name>` (`--purpose`). Only the letters,
@@ -891,8 +1013,8 @@ one screen to read and one `Enter` to press.
891
1013
  - **`n` and `N` are of the view they are pressed in**: the leader's too.
892
1014
  From the Souls view (its list, its filter or its detail) both are of its
893
1015
  selected soul, whatever the list of instances has selected.
894
- - **One spawn at a time.** While one is under way the line above the
895
- panes says `Spawning <name>…`, and the TUI goes on working: `n` and `N`
1016
+ - **One spawn at a time.** While one is under way the line under the
1017
+ title says `Spawning <name>…`, and the TUI goes on working: `n` and `N`
896
1018
  say a spawn is under way and open nothing.
897
1019
  - **Only on this machine.** On another machine's row or workspace `n` and
898
1020
  `N` (from their keys, the leader or the palette) say that spawning on
@@ -904,7 +1026,7 @@ the TUI adds only what to do next, naming its keys or an `oats` command:
904
1026
 
905
1027
  | Outcome | What follows |
906
1028
  |---|---|
907
- | 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 |
1029
+ | created and started | the instances are read at once; when the new row appears it is selected and its terminal opens beside the sidebar 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 Alt+O w.`, and nothing opens. Not running after two reads: the line says it is not visible yet, and nothing opens later by itself |
908
1030
  | 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) |
909
1031
  | 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 |
910
1032
  | its cleanup is owed | the line says so and names the retire |
@@ -930,12 +1052,13 @@ The line after leaving says so and names `oats status` to see it.
930
1052
  | `2` | [the Souls view](#the-souls-view); `Esc` or `1` goes back |
931
1053
  | `3` | [the Capabilities view](#the-capabilities-view); `Esc` or `1` goes back |
932
1054
  | `w` | opens [the switcher](#the-switcher) |
933
- | `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 |
934
- | `z` | gives the shown terminal the focus and the whole body |
1055
+ | `Delete` | in the switcher, asks whether to remove the selected row from this computer's list of deployments; `Enter` removes it |
1056
+ | `Enter` | in the list of instances, opens the selected agent's terminal in a new [tab](#tabs) beside the sidebar, 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 |
1057
+ | `z` | gives the shown terminal the focus and the whole screen |
935
1058
  | `c` | closes the shown terminal's tab and shows the tab beside it; the agent keeps running |
936
1059
  | `[`, `]` | in the Instances view, shows the tab before or after the shown one |
937
1060
  | `\|`, `-` | in the Instances view, [splits](#splits) the panel side by side or one above the other |
938
- | `Ctrl+\` | [the leader](#the-leader), from every focus ([`tui.json`](#change-the-keys-tuijson) can name another key) |
1061
+ | `Alt+O` (`Ctrl+\` on macOS) | [the leader](#the-leader), from every focus ([`tui.json`](#change-the-keys-tuijson) can name another key) |
939
1062
  | `Ctrl+K` | opens [the palette](#the-palette); `Ctrl+K` again closes it |
940
1063
  | `X`, `D`, `S`, `R` | stop, retire, start, restart the selected agent, [after a confirmation](#stopping-starting-restarting-and-retiring) |
941
1064
  | `n` | [spawns an agent](#spawning-an-agent): the soul picker, then the preview |
@@ -958,15 +1081,23 @@ instance can always be read, however many they are. The selection stays
958
1081
  where it is, and the list returns to it at the next key that moves it.
959
1082
 
960
1083
  The help screen is generated from the table the program acts on, so it
961
- always lists the keys that work, the leader's among them, with the marks
962
- and with what this version does not do. The movement keys scroll it. While
1084
+ always lists the keys that work, the leader's among them, the palette's
1085
+ and the spawn prompt's, with the marks and with what this version does not
1086
+ do. Its top row has the time of the read and the count of withheld rows
1087
+ ([What it shows](#what-it-shows)). The movement keys scroll it. While
963
1088
  a terminal has the focus the table's keys are the agent's: the leader alone
964
1089
  is the TUI's.
965
1090
 
966
1091
  ### The leader
967
1092
 
968
1093
  Every action is reached by keys from every focus, a terminal's too: the
969
- leader, `Ctrl+\` (tui.json's `open.detachKey`), then one plain key.
1094
+ leader (tui.json's `open.detachKey`), then one plain key. The leader is
1095
+ `Alt+O` on Linux and Windows and `Ctrl+\` on macOS, unless
1096
+ [`tui.json`](#change-the-keys-tuijson) names another key, `C-\` among
1097
+ them. `Alt+O` is reached with one hand on every keyboard layout, where
1098
+ `Ctrl+\` is a stretch on most and needs AltGr on many. macOS keeps
1099
+ `Ctrl+\` because its terminals type `ø` for Option+O unless they are set
1100
+ to use Option as Meta.
970
1101
 
971
1102
  | The leader, then | Does |
972
1103
  |---|---|
@@ -974,7 +1105,7 @@ leader, `Ctrl+\` (tui.json's `open.detachKey`), then one plain key.
974
1105
  | `1`, `2`, `3` | the Instances, Souls and Capabilities views |
975
1106
  | `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 |
976
1107
  | `Left`, `Right` | shows the tab before or after the shown one; the strip does not wrap, and the focus stays where it was |
977
- | `z` | zooms the shown terminal in or out; with the list focused, gives it the focus and the whole body |
1108
+ | `z` | zooms the shown terminal in or out; with the list focused, gives it the focus and the whole screen |
978
1109
  | `w` | closes the shown terminal's tab and shows the tab beside it; the agent keeps running |
979
1110
  | `\|`, `-` | [splits](#splits) the panel side by side or one above the other |
980
1111
  | `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 |
@@ -985,13 +1116,17 @@ leader, `Ctrl+\` (tui.json's `open.detachKey`), then one plain key.
985
1116
  | `/` | the filter |
986
1117
  | `o` | [the switcher](#the-switcher) |
987
1118
  | `?` | the help |
988
- | `Esc`, or the leader again | gives the list the focus; with the list focused, only closes the hint |
989
-
990
- - **While the leader waits** for its key the footer row is its hint, which
991
- names these keys (`z` and `w` only while a terminal is open, `Left` and
992
- `Right` only with two tabs or more, `|` and `-` while the panel has one
993
- group, `Tab` with two, then `m` while the focused group shows a tab or
994
- `x` while it is empty). It waits
1119
+ | `Esc` | gives the list the focus |
1120
+ | the leader again | types the leader into the terminal that has the focus, which keeps it; with the list focused, only closes the hint |
1121
+
1122
+ - **While the leader waits** for its key the cheat sheet's rows are its
1123
+ hint: `Alt+O then`, then a row per key, `Esc the list` last. It names
1124
+ these keys but `n` and `N` (`z` and `w` only while a terminal is open,
1125
+ `Left` and `Right` only with two tabs or more, `|` and `-` while the
1126
+ panel has one group, `Tab` with two, then `m` while the focused group
1127
+ shows a tab or `x` while it is empty, and the leader again while a
1128
+ terminal has the focus). On a short screen it gives up rows before its
1129
+ last. It waits
995
1130
  with no time limit. A key not in the table cancels it and is dropped:
996
1131
  nothing is typed.
997
1132
  - **Only a key in a later read counts.** A key that came in the same read of
@@ -999,6 +1134,13 @@ leader, `Ctrl+\` (tui.json's `open.detachKey`), then one plain key.
999
1134
  read, so a paste can never run a command. In a terminal the bytes before
1000
1135
  the leader in that read still go to the agent. A leader inside a
1001
1136
  bracketed paste is pasted text.
1137
+ - **In a terminal `Alt+O` is one keypress only.** A terminal sends `Alt+O`
1138
+ as `Esc` then `o`. Those bytes count as the leader when they arrive in
1139
+ one read, or split across reads within 10 ms. An `Esc` then `o` typed as
1140
+ two keys reaches the agent unchanged: in vim that is "leave insert mode,
1141
+ open a line". Over a slow link two keys typed apart can arrive in one
1142
+ read and act as the leader, and one `Alt+O` can arrive split and reach
1143
+ the agent as `Esc` and `o`.
1002
1144
  - **In the list no leader is needed:** the plain keys work as they always
1003
1145
  have, and the leader works there too.
1004
1146
  - **What was open under it is settled first,** from whatever view: a
@@ -1013,8 +1155,12 @@ leader, `Ctrl+\` (tui.json's `open.detachKey`), then one plain key.
1013
1155
  ### The palette
1014
1156
 
1015
1157
  The leader then `k` (or `Space`), or `Ctrl+K` in the list, opens one input
1016
- over a list, as the OATS Desktop's ⌘K does. It takes the body, and while it
1017
- is open no terminal is drawn and the TUI reads the keys.
1158
+ over a list, as the OATS Desktop's ⌘K does. From 80 columns it covers the
1159
+ main area and the sidebar stays beside it, its cheat sheet naming the
1160
+ palette's keys (`Enter run`, `Up/Down move`, `Esc close`); under 80 columns
1161
+ it covers the whole screen, with those keys on its first row. While it is
1162
+ open no terminal is drawn and the TUI reads the keys. The help lists its
1163
+ keys under The palette.
1018
1164
 
1019
1165
  - **It lists, in this order:** the instances that can be opened, the most
1020
1166
  recently opened or shown in this run first (when the first is the shown tab's,
@@ -1050,15 +1196,18 @@ is open no terminal is drawn and the TUI reads the keys.
1050
1196
  - Closed, it gives the focus back to the terminal it was opened from.
1051
1197
  Recency is kept for the run only: nothing is written.
1052
1198
 
1053
- **The filter.** `/` opens a field on the last row. What you type narrows the
1199
+ **The filter.** `/` opens a field on the open view's heading: while you
1200
+ type, the heading is `/` and the text. What you type narrows the
1054
1201
  list to the instances whose name, soul or repository contains it, with the
1055
1202
  instances they were spawned from, whatever is folded away. In the field
1056
1203
  every printable key is text, so `q` and `j` can be typed; `Backspace`
1057
1204
  removes a character, `Enter` keeps the filter and returns to the list
1058
- (the last row then shows it as `/text`), `Esc` clears it. `Ctrl+C`, `Ctrl+Z`
1205
+ (the heading then names it after the view's name, `Instances /text`),
1206
+ `Esc` clears it. `Ctrl+C`, `Ctrl+Z`
1059
1207
  and `Ctrl+L` still do what they do. The filter holds at most 200
1060
- characters. The switcher has a filter of its own, with the same field: it
1061
- narrows the rows to the ones whose name, machines or path contain the text.
1208
+ characters. The switcher has a filter of its own: its field stands on a
1209
+ row of its own above its list while it is typed or kept, and it narrows the
1210
+ rows to the ones whose name, machines or path contain the text.
1062
1211
 
1063
1212
  **Pasted text is never read as keys.** A paste into the list is dropped
1064
1213
  whole. A paste into the filter field adds its first line, and only when
@@ -1085,7 +1234,7 @@ never writes it. With no file the keys are the ones above.
1085
1234
  `souls`, `capabilities`, `workspaces`, `palette`, `open`, `soul-instances`, `zoom`, `close-terminal`,
1086
1235
  `tab-previous`, `tab-next`, `split-right`, `split-down`, `group-next`, `tab-move`,
1087
1236
  `group-close`, `stop`, `retire`, `start`, `restart`, `spawn`, `spawn-another`,
1088
- `spawn-check`, `help`, `close`, `quit`, `suspend` and `redraw`. `workspaces` (`w`) opens the switcher and `open` (`enter`)
1237
+ `spawn-check`, `remove`, `help`, `close`, `quit`, `suspend` and `redraw`. `workspaces` (`w`) opens the switcher and `open` (`enter`)
1089
1238
  opens the selected agent's terminal in the list of instances, the
1090
1239
  selected row in the switcher and the detail in the Souls view;
1091
1240
  `soul-instances` (`i`) shows the selected soul's instances. `zoom` (`z`) and `close-terminal` (`c`) act
@@ -1093,7 +1242,8 @@ never writes it. With no file the keys are the ones above.
1093
1242
  the tab before and after it. `split-right` (`|`) and `split-down` (`-`)
1094
1243
  [split](#splits) the panel; `group-next`, `tab-move` and `group-close`
1095
1244
  have no key of their own by default (the leader then `Tab`, `m` and `x`
1096
- reach them). In an open filter field `Enter` keeps the filter,
1245
+ reach them). `remove` (`delete`) asks whether to remove the selected row
1246
+ of this computer's list of deployments, in the switcher. In an open filter field `Enter` keeps the filter,
1097
1247
  whatever key `open` has.
1098
1248
  - A key is written as the help shows it, in lower case: `q`, `G`, `?`,
1099
1249
  `space`, `enter`, `tab`, `escape`, `backspace`, `up`, `pageup`, `f5`,
@@ -1102,12 +1252,16 @@ never writes it. With no file the keys are the ones above.
1102
1252
  and `Ctrl+M` as `backspace`, `tab` and `enter`, so those four are not
1103
1253
  keys of their own.
1104
1254
  - `ascii: true` is `--ascii`.
1105
- - `open.detachKey` is **[the leader](#the-leader)**, `C-\` when you name
1106
- none. It is `oats tui`'s own and never reaches the agent or the kernel.
1255
+ - `open.detachKey` is **[the leader](#the-leader)**. When you name none
1256
+ it is `M-o` (`Alt+O`) on Linux and Windows and `C-\` (`Ctrl+\`) on
1257
+ macOS; `C-\` stays a key you can name on every platform. It is
1258
+ `oats tui`'s own: it never reaches the kernel, and it reaches the agent
1259
+ only when you press it twice in the agent's terminal.
1107
1260
  It is read as a key wherever the TUI reads keys, so it may not be a key
1108
1261
  an action has: `C-l` is `redraw`'s `Ctrl+L`, `C-k` the palette's
1109
- `Ctrl+K`, `C-j` is `Enter`. It is one of
1110
- these, written as shown: `C-` with a letter but `h`, `i` and `m` (a
1262
+ `Ctrl+K`, `C-j` is `Enter`. That holds for the default too: a file that
1263
+ gives `alt+o` to an action on Linux or Windows names another leader as
1264
+ well. It is one of these, written as shown: `C-` with a letter but `h`, `i` and `m` (a
1111
1265
  terminal sends those as `Backspace`, `Tab` and `Enter`) or one of `\`
1112
1266
  `]` `^` `_`; `M-` with a lower-case letter or a digit; or `F1` to `F12`,
1113
1267
  alone or with one of `C-`, `M-`, `S-` (`C-F5`). These are the keys a
@@ -1126,7 +1280,7 @@ guesses nothing. It refuses:
1126
1280
  | 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` |
1127
1281
  | has a member of `open` other than `detachKey` | `unknown member … of open; open has detachKey` |
1128
1282
  | gives `open.detachKey` anything but one of the keys above | `open.detachKey must be one key: …`, with the keys it can be |
1129
- | 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` |
1283
+ | gives `open.detachKey`, or the default leader, a key an action has | `open.detachKey … is read as …, the key of …; give the leader a key no action has, or give … another`, or `the default leader … is read as …` with the same end when the file names no leader |
1130
1284
  | names `open-workspace`, the action's name before it became `open` | `open-workspace is called open now; rename it` |
1131
1285
  | names an action that does not exist | `unknown action …`, with the list of actions |
1132
1286
  | gives an action something that is not a list of strings | `… must be a list of key ids` |
@@ -1158,8 +1312,8 @@ with the Desktop (`packages/client/`).
1158
1312
  - **How often:** 5 seconds after the last read ended; 30 seconds once ten
1159
1313
  minutes have passed without a key; at once on `r`, on the return from a
1160
1314
  suspend and when a row is opened in the switcher. Every read asks tmux
1161
- anew and reads the instances anew, and the time in the header is that
1162
- read's. What a read in the background may reuse is the kernel's own look
1315
+ anew and reads the instances anew, and the time on the help's top row is
1316
+ that read's. What a read in the background may reuse is the kernel's own look
1163
1317
  at the workspace's remotes, for up to 60 seconds; `r` asks the kernel to
1164
1318
  look again.
1165
1319
  - **The souls are one more read**, `oats souls --json` for the open
@@ -1193,12 +1347,22 @@ with the Desktop (`packages/client/`).
1193
1347
  a suspend and when a row is opened in the switcher.
1194
1348
  - A kernel whose version record lists no read of other machines is never
1195
1349
  asked for one, and no other machine is shown.
1196
- - **Two looks at the file system serve the switcher**, and neither reads a
1197
- file's content. At a start outside every deployment with no `--dir`, when
1198
- the switcher opens, and on `r` in it, the entries of `~/Agents` are
1199
- listed: at most 200, and each directory among them is asked for a regular
1200
- `oats-local.yaml`. An entry that is a link is not followed. When a folder
1201
- is opened, that one directory is asked again.
1350
+ - **This computer's list of deployments is the kernel's**, read and changed
1351
+ through the same kernel, with 15 seconds and 4 MiB each, from `/`:
1352
+ - `oats deployments --json`, at a start outside every deployment with no
1353
+ `--dir` (before the terminal is taken), when the switcher opens, on `r`
1354
+ in it and after a Remove. One runs at a time: one asked for while one is
1355
+ on its way runs after it, however many times it was asked, and the
1356
+ answer taken is that later one's.
1357
+ - `oats deployments add <path> --via tui --json`, once a run, for the
1358
+ deployment it started in, from that deployment.
1359
+ - `oats deployments remove <path> --json`, for a Remove you confirmed.
1360
+
1361
+ An add and a remove are changes: `oats tui` never ends one, and one still
1362
+ running as it leaves is named in one line after the screen is left.
1363
+ - **One look at the file system serves the switcher**, and it reads no
1364
+ file's content: when a row of the list is opened, that one directory is
1365
+ asked for a regular `oats-local.yaml`.
1202
1366
  - **Opening an agent runs one more command,** `oats session attach --home
1203
1367
  <home>`, by the same kernel, in a pane of the run's private tmux server
1204
1368
  ([above](#open-an-agents-terminal)), with no key of its own. For an agent
@@ -1242,7 +1406,7 @@ with the Desktop (`packages/client/`).
1242
1406
  that pane's output until the tab is displayed again, so a hidden agent
1243
1407
  that prints without pause costs one chunk of output each time its tab is
1244
1408
  hidden, and a quiet one nothing. The panel hidden as a whole (another
1245
- view or an overlay over it, or the list alone under 80 columns) pauses
1409
+ view or an overlay over it, or the sidebar alone under 80 columns) pauses
1246
1410
  its displayed tabs the same way. A
1247
1411
  paused pane is still read by the private server, so its screen stays
1248
1412
  current and its viewer never waits. A tab displayed again is continued
@@ -1305,7 +1469,10 @@ with the Desktop (`packages/client/`).
1305
1469
  files in a directory of `oats tui`'s own (made with mode 0700 under the
1306
1470
  system's temporary directory), read back when it ends and deleted. On the
1307
1471
  way out the files of a change still running are deleted (it goes on
1308
- writing to them), and the directory is removed. `oats tui` waits for an
1472
+ writing to them), and the directory is removed. A run ended by SIGKILL
1473
+ removes nothing: with a kernel that lists this computer's deployments,
1474
+ the add at the start has made the directory, and when no terminal was
1475
+ opened in that run it holds no `owner.json`, so no later run removes it. `oats tui` waits for an
1309
1476
  apply's answer for 10 minutes and for a start's for 60 seconds; then it
1310
1477
  says so, and the change goes on.
1311
1478
  - **A spawn runs the kernel's own `oats spawn`**, as the Desktop does: the
@@ -1344,23 +1511,25 @@ with the Desktop (`packages/client/`).
1344
1511
  | add a machine to this workspace | `oats server connect <id> --ssh <alias>` |
1345
1512
  | check a machine | `oats server check <id>` |
1346
1513
  | remove a machine | `oats server remove <id>` |
1347
- | open a deployment outside `~/Agents` | `oats tui --dir <path>` |
1514
+ | open a deployment that is not listed | `oats tui --dir <path>` |
1348
1515
  | open an agent in a tmux window or split of its own | `oats session attach --home <home>` in that window (the detail shows the home) |
1349
1516
 
1350
1517
  The help screen (`?`) names the same commands. What else holds for this
1351
1518
  version:
1352
1519
 
1353
- - **It keeps nothing on disk.** A machine it has not reached in this run is
1354
- listed by its own name, in no workspace. What is folded away and each
1355
- view's place last as long as the run, and no filter is saved.
1520
+ - **It keeps nothing on disk of its own; opening a deployment lists it**
1521
+ on this computer's list, which is the kernel's. A machine it has not
1522
+ reached in this run is listed by its own name, in no workspace. What is
1523
+ folded away and each view's place last as long as the run, and no filter
1524
+ is saved.
1356
1525
  - **Of this machine's deployments, the switcher lists only the ones opened
1357
- in this run and the ones directly inside `~/Agents`.** Any other is
1358
- opened with `oats tui --dir <path>`.
1526
+ in this run and the ones on this computer's list.** Any other is opened
1527
+ with `oats tui --dir <path>`, which lists it.
1359
1528
  - **A row of another machine shows what its host reported at the last
1360
1529
  read,** not what is true at this moment. The time of that read is on the
1361
- machine's heading when it is not the header's time. A view of one machine
1362
- has no heading: there the header names the machine (`on garnet`) and
1363
- carries the time.
1530
+ machine's heading when it is not the time of this machine's read. A view
1531
+ of one machine has no heading: there the title names the machine
1532
+ (`on garnet`) and the help's top row carries the time.
1364
1533
  - The Souls and Capabilities views list a workspace of this machine's
1365
1534
  souls and capabilities: both are this machine's.
1366
1535
  - There is no sorting and no mouse, and a deployment's heading cannot be
@@ -1500,6 +1669,10 @@ alone. The next run removes the directory that is left, with its `tmux`,
1500
1669
  to its own end. A spawn is ended only at its deadline, while `oats tui`
1501
1670
  runs ([above](#what-it-reads-and-what-it-runs)): never on the way out,
1502
1671
  and never after it.
1672
+ - It **changes this computer's list of deployments only through the
1673
+ kernel** (`oats deployments add` and `remove`,
1674
+ [above](#what-it-reads-and-what-it-runs)), and never reads or writes the
1675
+ list's file itself.
1503
1676
 
1504
1677
  ## Errors
1505
1678
 
@@ -1509,11 +1682,16 @@ alone. The next run removes the directory that is left, with its `tmux`,
1509
1682
  | `E_BAD_ARGS` | `oats tui --json`: it is interactive and has no JSON form. The usual failure envelope, exit 1 | `oats status --json` is the machine view |
1510
1683
  | `E_BAD_ARGS` | any argument other than `--dir <path>`, `--ascii` and `--help`, or `--dir` with no path. One line on stderr with the usage, exit 1 | `oats tui --help` |
1511
1684
  | `E_TUI_CONFIG` | `tui.json` cannot be honoured. One line per problem on stderr, exit 1 | fix the file as the line says, or remove it |
1512
- | `E_NO_DEPLOYMENT` | no directory at or above the start holds an `oats-local.yaml`; and, for a start without `--dir`, `~/Agents` holds no deployment. One line on stderr, exit 1 | `oats tui --dir <path>`, or `cd` into the deployment |
1685
+ | `E_NO_DEPLOYMENT` | with `--dir`, no directory at or above it holds an `oats-local.yaml`: `no OATS deployment at or above <dir>`. One line on stderr, exit 1 | `oats tui --dir <path>` with a deployment, or `cd` into one |
1686
+ | `E_NO_DEPLOYMENT` | without `--dir`, no directory at or above the start holds an `oats-local.yaml`, and this computer's list of deployments holds none: `no deployment at or above <dir>, and this computer's list of deployments holds none (E_NO_DEPLOYMENT): \`oats tui --dir <path>\` opens one (and lists it), \`oats onboard <dir> --workspace <ref>\` creates one`. One line on stderr, exit 1 | as the line says |
1687
+ | the kernel's code (`E_DEPLOYMENTS_BUSY`, `E_DEPLOYMENTS_INVALID`, `E_DEPLOYMENTS_VERSION`, …) | without `--dir` and outside every deployment, this computer's list of deployments could not be read: `` `oats tui` could not read this computer's list of deployments (<code>): <the kernel's message> ``. One line on stderr, exit 1 | what the kernel's message says |
1513
1688
  | `E_TUI_KERNEL` | the kernel it shipped with did not answer `version --json` with a record it accepts; the line gives the reason. One line on stderr, exit 1 | reinstall `oats`: the client and the kernel are one package |
1514
1689
 
1515
1690
  These lines are written before the terminal is touched, in this order: the
1516
- arguments, the terminal, `tui.json`, the deployment, the kernel. None of the
1691
+ arguments, the terminal, `tui.json`, the deployment, the kernel, and then,
1692
+ for a start without `--dir` outside every deployment, this computer's list of
1693
+ deployments, which is read through that kernel. A `--dir` that is in no
1694
+ deployment is answered before the kernel is asked. None of the
1517
1695
  codes on stderr appears in a JSON envelope. A path is repeated in a line
1518
1696
  only when it is plain printable ASCII.
1519
1697