@awebai/oats 0.68.0 → 0.69.1

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 (72) hide show
  1. package/bin/oats.mjs +102 -22
  2. package/docs/capabilities.md +49 -5
  3. package/docs/configuration.md +68 -2
  4. package/docs/desktop-cli-api.md +355 -12
  5. package/docs/desktop-instance-start.md +88 -3
  6. package/docs/desktop.md +147 -13
  7. package/docs/execution-targets.md +514 -62
  8. package/docs/harness-trust.md +3 -1
  9. package/docs/implementation.md +28 -11
  10. package/docs/integrations.md +1 -1
  11. package/docs/oats-local.schema.json +2 -2
  12. package/docs/official-catalog.md +4 -3
  13. package/docs/packages.md +7 -7
  14. package/docs/release-notes/v0.68.1.md +102 -0
  15. package/docs/release-notes/v0.69.0.md +658 -0
  16. package/docs/release-notes/v0.69.1.md +25 -0
  17. package/docs/servers.md +44 -5
  18. package/docs/souls-and-instances.md +11 -7
  19. package/docs/tui.md +114 -31
  20. package/docs/upgrading.md +14 -5
  21. package/docs/workspaces.md +1 -1
  22. package/lib/core.mjs +345 -89
  23. package/lib/file-pieces.mjs +49 -0
  24. package/lib/instance-events.mjs +25 -4
  25. package/lib/launch-prompt-fixtures/README.md +62 -0
  26. package/lib/launch-prompt-fixtures/resume-confirmation.json +32 -0
  27. package/lib/launch-prompt-fixtures.mjs +49 -0
  28. package/lib/launch-prompt-resume.mjs +55 -0
  29. package/lib/login-environment.mjs +27 -9
  30. package/lib/schedule.mjs +3 -3
  31. package/lib/servers.mjs +117 -23
  32. package/lib/session-end.mjs +82 -0
  33. package/lib/session-input.mjs +43 -9
  34. package/lib/session-resume-contract.mjs +32 -0
  35. package/lib/session-resume.mjs +310 -0
  36. package/lib/session-seen.mjs +163 -0
  37. package/lib/session-viewer.mjs +147 -44
  38. package/lib/soul-composition.mjs +2 -1
  39. package/lib/start-env.mjs +110 -0
  40. package/lib/tmux-server-scope.mjs +139 -14
  41. package/lib/workspace.mjs +38 -4
  42. package/package-catalog.json +10 -4
  43. package/package.json +1 -1
  44. package/packages/client/cli-adapter.mjs +9 -0
  45. package/packages/client/cli-locator.mjs +3 -2
  46. package/packages/client/deployment-data.mjs +7 -0
  47. package/packages/client/deployment-panel.mjs +3 -0
  48. package/packages/client/file-output-exec.mjs +98 -0
  49. package/packages/client/instance-display-name.mjs +18 -0
  50. package/packages/client/launch-prompt-outcome.mjs +25 -13
  51. package/packages/client/own-codes.mjs +2 -0
  52. package/packages/client/session-attach.mjs +35 -5
  53. package/packages/client/session-resume-cli.mjs +64 -0
  54. package/packages/client/session-resume-trigger.mjs +167 -0
  55. package/packages/client/session-resume.mjs +332 -0
  56. package/packages/client/tmux-status.mjs +30 -7
  57. package/packages/client/waiting-on-you.mjs +11 -4
  58. package/packages/client/workspace-step.mjs +17 -5
  59. package/packages/record/lib/last-conversation.mjs +123 -0
  60. package/packages/record/lib/session-roots.mjs +10 -1
  61. package/packages/tui/README.md +1 -1
  62. package/packages/tui/lib/client.mjs +2 -1
  63. package/packages/tui/lib/main.mjs +5 -3
  64. package/packages/tui/lib/model.mjs +57 -15
  65. package/packages/tui/lib/store.mjs +8 -7
  66. package/packages/tui/lib/term/text.mjs +12 -9
  67. package/packages/tui/lib/views/capabilities.mjs +6 -6
  68. package/packages/tui/lib/views/frame.mjs +72 -7
  69. package/packages/tui/lib/views/help.mjs +9 -4
  70. package/packages/tui/lib/views/instances.mjs +46 -29
  71. package/packages/tui/lib/views/souls.mjs +9 -8
  72. package/skills/oats-getting-started/SKILL.md +117 -4
@@ -0,0 +1,25 @@
1
+ # OATS 0.69.1
2
+
3
+ Unreleased
4
+
5
+ 0.69.0 was tagged but never published: its release run failed on a macOS-only
6
+ test before anything was released. 0.69.1 is the first 0.69 release, and it
7
+ carries everything in [0.69.0's notes](v0.69.0.md): session resume, the agent's
8
+ pane in a split window, the scroll keys, the waiting row, oats.aweb 1.32.0,
9
+ oats.engineering 1.15.0 and oats.framework 1.15.1.
10
+
11
+ ## Upgrade
12
+
13
+ - **Follow [0.69.0's Upgrade section](v0.69.0.md#upgrade)**: install the
14
+ Desktop first and the CLI second (a 0.68 Desktop refuses a 0.69 CLI). The
15
+ 0.69.1 Desktop accepts OATS CLIs `>=0.26.0 <0.70.0`. Every host that shares
16
+ a workspace runs OATS 0.68.0 or later before any of them syncs to
17
+ oats.aweb 1.32.0. Then run `oats status` once before you restart, so the
18
+ session resume sweep knows what was running.
19
+
20
+ ## Fixed
21
+
22
+ - **The Desktop's tests pass on macOS.** A test of the session resume
23
+ runner compared a working directory without resolving macOS's `/var` →
24
+ `/private/var` link, which failed both macOS Desktop builds of 0.69.0
25
+ (#1590). No behaviour changes.
package/docs/servers.md CHANGED
@@ -71,7 +71,7 @@ which is where a [macOS keychain](#git-on-a-macos-host) problem shows up.
71
71
  ## Connect a machine
72
72
 
73
73
  ```bash
74
- oats server connect altair-aweb --ssh altair --dir '~/acme' --path /opt/homebrew/bin --install-oats
74
+ oats server connect altair-aweb --ssh altair --dir '~/acme' --install-oats
75
75
  ```
76
76
 
77
77
  Run from a deployment, `server connect` puts that deployment's workspace on
@@ -83,7 +83,7 @@ missing, so after a human step you run the same command again.
83
83
  |---|---|
84
84
  | `--dir <path>` | none, inside a deployment too: the folder on the host for this deployment, absolute or `~/…` (resolved by the host). Without it: `E_BAD_ARGS` "--dir <path on the host> is required: the folder on `<host>` for this deployment (absolute, or ~/… resolved there)". A registration made before it was required is unchanged |
85
85
  | `--workspace-ref <ref>` | this deployment's `oats-local.yaml` `workspace:` |
86
- | `--oats <path>`, `--path <dirs>`, `--label <text>` | as for `server add`; `--path` is where the host finds `npm`, `oats` and the harnesses |
86
+ | `--oats <path>`, `--path <dirs>`, `--label <text>` | as for `server add`; `--path` is where the host finds `npm`, `oats` and the harnesses. Without it, connect uses the PATH of the host user's [login shell](#the-hosts-login-shell-path) |
87
87
  | `--install-oats` | off: a missing or older OATS is a human step |
88
88
  | `--replace` | off: an id registered for another host or directory is refused |
89
89
 
@@ -91,8 +91,8 @@ The steps, in order:
91
91
 
92
92
  | Step | Checks | When something is missing |
93
93
  |---|---|---|
94
- | `ssh` | the host answers a non-interactive ssh | `failed` `E_SSH` |
95
- | `oats` | `oats version --json` there is this kernel's version or newer and advertises `server-connect` (a build of the same version without it is not enough) | with `--install-oats`: runs `npm install -g @awebai/oats@<this version>` there (`done`); without it, or with no `npm` on the host's PATH: `needs-human` with the command to run |
94
+ | `ssh` | the host answers a non-interactive ssh; without `--path`, the PATH of the host user's [login shell](#the-hosts-login-shell-path) is read (its `detail` says whether) | `failed` `E_SSH` |
95
+ | `oats` | `oats version --json` there is this kernel's version or newer and advertises `server-connect` (a build of the same version without it is not enough) | with `--install-oats`: runs `npm install -g @awebai/oats@<this version>` there (`done`); without it: `needs-human` with the command to run. With no `npm` on the PATH it searched (named in `detail`): `needs-human` to install Node.js there, with a command that checks the login shell finds `npm`, then check again |
96
96
  | `git` | the host's Git reads the workspace remote | `needs-human` with the remedy (and the [keychain hint](#git-on-a-macos-host)) |
97
97
  | `deployment` | `--dir` holds a deployment of this workspace | an absent or empty directory is onboarded there (`done`); a deployment of another workspace is `failed` `E_SERVER_WORKSPACE_MISMATCH`; a non-empty directory without `oats-local.yaml` is `failed` `E_DIR_NOT_EMPTY` and nothing is written into it |
98
98
  | `register` | the registration exists, with its `workspaceKey` | written (`done`); an id registered for another target is `failed` `E_SERVER_EXISTS` unless `--replace` (checked before anything else, so a requested id never reports ready while it routes elsewhere); a new id whose host and directory are already registered under another id is reported (`ok`, naming that id; the text result then names that id to spawn with) and not registered twice |
@@ -105,6 +105,37 @@ human. Connect never handles credentials: what Git on the host cannot read
105
105
  is always a human step there. The `--json` shape is in
106
106
  [desktop-cli-api.md](desktop-cli-api.md#oats-server-connect).
107
107
 
108
+ ### The host's login-shell PATH
109
+
110
+ A non-interactive ssh command does not read the user's login files, so on a
111
+ host whose PATH comes from `~/.zprofile`, `~/.bash_profile` or `~/.profile`
112
+ (a Homebrew or version-manager directory, say) it finds neither `npm` nor
113
+ `oats`. Without `--path`, connect therefore asks the host user's own login
114
+ shell for its PATH once, in the `ssh` step, by the rules OATS uses for the
115
+ local login environment ([execution-targets.md](execution-targets.md)):
116
+
117
+ - The shell is the host's `$SHELL`, which sshd sets from the host's password
118
+ database. Only bash, zsh or fish at an absolute path is run; it runs
119
+ `-l -i -c` (login and interactive, so both its profile and its rc files are
120
+ read) and prints its PATH between two delimiters that carry a random nonce,
121
+ within 15 s and 1 MiB.
122
+ - The PATH's absolute directories (each once, in order) become the
123
+ registration's `path`, the field `--path` sets, so every later step and
124
+ every later `--server` command runs with them. `oats` found on that PATH is
125
+ recorded as `oatsPath` by its absolute path.
126
+ - Another shell, no answer in time, or an answer that is not one PATH: the
127
+ `ssh` step stays `ok`, its `detail` says why the PATH could not be read, and
128
+ connect goes on with ssh's own PATH.
129
+ - An explicit `--path` always wins: the login shell is not asked. An explicit
130
+ `--oats` is kept as given.
131
+ - A registration of the same host and directory made before keeps the `path`
132
+ and `oatsPath` it has; connect only fills in the ones it lacks (`register`
133
+ `done`, "recorded …"), and `--replace` rewrites them with what it found.
134
+ - The recorded `path` and `oatsPath` are a snapshot of the login shell at
135
+ connect time. On a host whose Node comes from a version manager (nvm,
136
+ asdf), a later Node upgrade can leave `oatsPath` pointing at a directory
137
+ that is gone; `oats server connect … --replace` reads them again.
138
+
108
139
  ### What connect runs on the host
109
140
 
110
141
  Besides `version --json`, `status --json`, `souls --json` and `readiness
@@ -238,7 +269,7 @@ sent as text or on stdin, never as paths.
238
269
  | `spawn` | registered workspace | the requested harness, backend and yolo option; `launch-config` for `--launch-config`; `schedule` for a wake schedule; `spawn-name` for `--name`; `spawn-preview-2` for `--preview`; `spawn-suggest-name` for `--suggest-name` on a preview, `spawn-apply-suggest-name` on an apply |
239
270
  | `status` | registered workspace | |
240
271
  | `retire` | the instance's home | `retire-home` to retire by exact home |
241
- | `session inspect`, `session attach` | the instance's home | `session`; `session-attach-detach-key` for `attach --detach-key` |
272
+ | `session inspect`, `session attach` | the instance's home | `session`; `session-attach-detach-key` for `attach --detach-key`; `session-attach-no-status-line` for `attach --no-status-line`, which a host without it ignores |
242
273
  | `session start`, `session restart` | the instance's home | `session-start`; `session-restart`; `launch-config` when `--launch-config`, `--harness` or `--yolo` is given |
243
274
  | `session upload` | the instance's home | `session-upload` |
244
275
  | `okf harvest --instance <name>` | the saved home | `harvest` |
@@ -331,6 +362,11 @@ nothing was sent`. Under `--json` the envelope's `error.details` is
331
362
  under `--print`, which otherwise skips it: a printed command must not carry
332
363
  a flag its host would ignore.
333
364
 
365
+ `--no-status-line` travels as it is, with no probe of its own: a host that
366
+ does not advertise `session-attach-no-status-line` ignores it and shows the
367
+ viewer's status line, which loses nothing
368
+ ([execution-targets.md](execution-targets.md#inspect-input-and-attach)).
369
+
334
370
  **Not routed.** `session input` runs on the execution host, where schedules
335
371
  and messaging capabilities call it. `session restart --stop-grace` is refused
336
372
  with `--server`; the remote default applies. `session attach --print` shows
@@ -389,6 +425,9 @@ answer, never a separate `version --json`, kept only when it is a valid list
389
425
  of feature names and otherwise `null` (unknown, as from a host before
390
426
  0.49.0); a failed probe has no `features` key
391
427
  ([the field](desktop-cli-api.md#the-remote-roster-oats-server-roster---json)).
428
+ It relays the host's viewer fact the same way, `probe.sessionViewer`
429
+ (`{prefixScroll}`, feature `session-attach-prefix-scroll`): whether that
430
+ host's viewer takes `C-b [`, or `null` when unknown.
392
431
 
393
432
  **Harvest** runs the knowledge capability's `okf harvest --json` in the
394
433
  instance's saved home on the server and relays its envelope.
@@ -982,8 +982,10 @@ A worktree that cannot be proven unchanged is copied without the read, so
982
982
  there the refusal comes from the copy, as `E_WORK_PRESERVATION_FAILED`.
983
983
 
984
984
  **A file in the worktree that cannot be read.** The same read refuses a file
985
- it cannot read: one without read permission, or one over 2 GiB, which a
986
- single read cannot take. Two kinds of file are read although they are nothing
985
+ it cannot read: one without read permission, or one that ends before the
986
+ size it had when it was opened, because it shrank while it was read. A
987
+ file of any size is read in pieces of 1 MiB, so a file over 2 GiB is read
988
+ like any other. Two kinds of file are read although they are nothing
987
989
  to preserve: a tracked file that is unchanged, and a file under a work root
988
990
  that a capability declared disposable (`retirement.disposable.work`). So a
989
991
  retire that has only the home to preserve refuses for such a file, with
@@ -992,10 +994,9 @@ retire that has only the home to preserve refuses for such a file, with
992
994
  or a FIFO refused before the hooks, the retire has already stopped the
993
995
  session of a launched instance by then, the instance is not retired, and its
994
996
  home is kept. The message is `could not read the worktree at <work>:
995
- <reason>`. For a file without read permission the reason names the file. For
996
- a file over 2 GiB it gives the size, and `find <work> -type f -size
997
- +2147483647c` finds the file. To continue, move the file out of the worktree
998
- or make it readable, then run `oats retire <instance>` again. With nothing to
997
+ <reason>`. The reason names the file. To continue, make the file readable,
998
+ move it out of the worktree, or stop what writes to it, then run
999
+ `oats retire <instance>` again. With nothing to
999
1000
  preserve, the files are not read and the retire goes through.
1000
1001
 
1001
1002
  **A home whose `instance.json` cannot be read.** The record is what
@@ -1053,7 +1054,10 @@ of the whole home.
1053
1054
  untracked and ignored files, have anything to preserve is decided against
1054
1055
  two digests the spawn baseline stores: one of the home (without `work/`, the
1055
1056
  provider-owned entries declared at spawn, the kernel's records above, and
1056
- the fields the kernel writes into `instance.json` after spawn), and one of
1057
+ the fields the kernel writes into `instance.json` after spawn, for an
1058
+ `instance.json` of at most 16 MiB: a larger one is taken as its bytes, so a
1059
+ baseline that took it without those fields reads the home as changed and
1060
+ the retire copies the home to the recovery), and one of
1057
1061
  the worktree's untracked and ignored paths outside the roots a capability
1058
1062
  declared disposable. A spawn by 0.49.0 or later records `digestVersion: 2`
1059
1063
  in the baseline, and its digests order entries by the bytes of their names,
package/docs/tui.md CHANGED
@@ -98,10 +98,10 @@ runs.
98
98
  acme-platform │ dev
99
99
  │ soul dev
100
100
  Instances 1 │ state running
101
- > ● dev │ harness claude, claude-opus-5-5 (so…
101
+ > ● Dev │ harness claude, claude-opus-5-5 (so…
102
102
  │ work worktree, agents/dev
103
- ● reviewer Needs input │ team eng
104
- ○ helper │ started 11:00
103
+ ! Reviewer │ team eng
104
+ ○ Helper │ started 11:00
105
105
  ──────────────────────────────────────│ home …oy/agents/dev/instances/dev
106
106
  Souls 2 │
107
107
  Capabilities 3 │
@@ -132,7 +132,7 @@ while a terminal is open); under 80 columns it has the whole width.
132
132
  `since …` and its reason on rows of its own; the note of a view of one
133
133
  deployment; and the line that says what happened after an open, an act or
134
134
  a spawn. Then an empty row. A line that goes at the next key and fits one
135
- row (`No workspace above this one.`) stands in that empty row instead, so
135
+ row (`No other workspace to show.`) stands in that empty row instead, so
136
136
  nothing under it moves.
137
137
  - **The views** follow as an accordion, always in this order: `Instances`,
138
138
  `Souls`, `Capabilities`, each with its key dim at the right edge. The open
@@ -183,21 +183,32 @@ while a terminal is open); under 80 columns it has the whole width.
183
183
  indent alone says which instance is under which: no mark is drawn for
184
184
  it. A row whose instances are folded away (`h`) says how many after its
185
185
  name: `+1`.
186
- - **Each row** is the mark of its state and the name, then, when it needs
187
- input, a tag at its right edge in the Desktop's words: `Needs input`. A
186
+ - **Each row** is the mark of its state and the name. A row that needs
187
+ input has the needs-input mark in place of its state mark: `!`, bold,
188
+ in reverse video in the waiting colour, a yellow cell with the `!` cut
189
+ out (the Desktop's mark in one cell), whatever the row's state and its
190
+ instance colour. On the selected row, which is in reverse video already,
191
+ it is the waiting colour not reversed, a gap in the selection's bar;
192
+ under `NO_COLOR` the reverse video and the `!` carry it, and in ASCII it
193
+ is the same `!`. The detail says it in words (its `needs` line, the
194
+ reason and how long it has waited), and so does the help. The row shows the name as words, as the Desktop's sidebar does: each `-`
195
+ a space and the first letter upper-case, so `oats-expert-lead` reads
196
+ `Oats expert lead`. Only the row does: the detail, the filter (`/` with
197
+ `oats-expert` still finds the row), the palette, the tabs, the
198
+ confirmations and everything sent to OATS keep the instance's name. A
188
199
  folded row with waiting instances among those it folds away says how
189
- many: `3 below`, and `99+ below` past 99. A row that needs input itself
190
- and folds waiting ones away says `Needs input`, as the Desktop's row
191
- does: the detail's `below` line names the others. The tag is in reverse
192
- video in the waiting colour, and on the selected row, which is in reverse
193
- video already, it is the waiting colour not reversed, a gap in the
200
+ many in a tag at its right edge, in the Desktop's words: `3 below`, and
201
+ `99+ below` past 99, whether or not the row needs input itself: its mark
202
+ says its own claim, the tag the rest, and the detail's `below` line names
203
+ them. The tag is in reverse video in the waiting colour, and on the
204
+ selected row it is the waiting colour not reversed, a gap in the
194
205
  selection's bar; under `NO_COLOR` the reverse video alone carries it. On
195
206
  a narrow row the tag gives way first: it says its words only where the
196
207
  whole name, its `+1` and the row's word in its column all fit beside them,
197
- and else shrinks to `!`, or the count alone (`3`, `99+`), still in
198
- reverse video, in the cells every row keeps at its right edge. So the
199
- tag never cuts a name, a word or a mark: those give way as on a row
200
- that does not wait. The harness and the state in words are in
208
+ and else shrinks to the count alone (`3`, `99+`), still in reverse video,
209
+ in the cells every row keeps at its right edge. So the tag never cuts a
210
+ name, a word or a mark: those give way as on a row whose instances do
211
+ not wait. The harness and the state in words are in
201
212
  the detail. A row has a word, dim, only where its mark cannot say it: the
202
213
  state of a home a spawn or a retire holds (`Retire didn't finish`), or
203
214
  the shared words for why an instance cannot be reached or opened:
@@ -291,20 +302,23 @@ in its workspace for the rest of the run, also while it is not reached.
291
302
  | `?` | `?` | state unknown: the kernel or the terminal probe could not tell, or the instance's machine was not reached |
292
303
  | `◆` | `#` | held by a spawn or a retire: under way (Retiring…), failed or not finished ([below](#held-rows)) |
293
304
  | `+n` | `+n` | after a name: n instances folded away below it |
294
- | `Needs input` | `Needs input` | needs input: a tag in reverse video at the row's right edge, `!` where the whole name does not fit beside the words |
295
- | `N below` | `N below` | N instances folded away below it need input, `N` where the whole name does not fit beside the words |
305
+ | `!` | `!` | needs input: in place of the state mark, in yellow and reverse video (not reversed on the selected row); with its terminal shown, the [waiting row](#tabs) under the tab bar says what it waits on |
306
+ | `N below` | `N below` | N instances folded away below it need input: a tag in reverse video at the row's right edge, `N` where the whole name does not fit beside the words |
296
307
  | `>` | `>` | the selected row (also drawn in reverse video), and the pane the movement keys act on |
297
308
  | `*` | `*` | in the switcher: the workspace that is open |
298
309
 
299
- Every state has a mark of its own shape, so nothing is told by colour alone.
310
+ Every state has a mark of its own shape, and so does needs input, so
311
+ nothing is told by colour alone.
300
312
 
301
313
  **An instance's colour** (feature `instance-color`; set with
302
314
  `oats instance color <instance> <colour>`, [desktop-cli-api.md](desktop-cli-api.md#an-instances-colour-oats-instance-color))
303
315
  colours its mark, in the list and in a soul's detail: a running mark in it, a
304
316
  stopped one and one with a shell left in it dim in it. `?` and `◆` keep their
305
317
  own look whatever the colour, and an instance with no colour looks as above.
306
- The six colours are the terminal's: `sand` yellow, `sage` green, `slate` blue,
307
- `mauve` magenta, `clay` red, `olive` cyan, the souls' own map. Which colour a
318
+ The six colours are the terminal's: `sand` its own foreground colour, `sage`
319
+ green, `slate` blue, `mauve` magenta, `clay` red, `olive` cyan, the souls' own
320
+ map. `sand` is not yellow, which says needs input and nothing else, and in the
321
+ foreground colour it is seen on a light theme as on a dark one. Which colour a
308
322
  row shows is the Desktop's rule (`instanceColor` in `packages/client`); an
309
323
  older kernel reports none. Setting a colour from the TUI is not in this
310
324
  version.
@@ -459,9 +473,39 @@ fit; the detail shows them whole. The TUI's own words end the same way:
459
473
  reason holds it (an instance gone from its machine, say). An agent on another machine is asked first whether it
460
474
  can be opened (`Esc` gives that up); a machine whose OATS cannot open its
461
475
  sessions is said then.
462
- - **No scrollback but the viewer's own, and no mouse.** The panel shows
463
- what the agent's window shows now; what has scrolled away is reached as
464
- the agent's own terminal reaches it.
476
+ - **The viewer's scroll keys, and no mouse.** The panel shows what the
477
+ agent's window shows now. What has scrolled away is reached through the
478
+ viewer's own keys, as in `oats session attach`: `Shift+PageUp`, or
479
+ `Ctrl+B` then `[`, put it in tmux's copy mode. Then `PageUp`, `PageDown`,
480
+ the arrows, `Ctrl+U` and `Ctrl+D` move, and `q` or `Esc` leaves. The TUI
481
+ adds no key of its own: they reach the viewer as a terminal without the
482
+ kitty keyboard protocol sends them (re-encoded under it), and the viewer
483
+ shows no status line of its own (`--no-status-line`, where the kernel has
484
+ it).
485
+ - **The cheat sheet names them** while a terminal has the focus, and so
486
+ does a zoomed terminal's title row where it has room: `Shift+PageUp or
487
+ Ctrl+B [`, then `scroll back`. Where the row holds one key, `Ctrl+B [`.
488
+ The title row gives them up first: in the Alt family, whose chords lead
489
+ that row, a zoomed terminal 120 columns wide or less does not name
490
+ them. The help does.
491
+ - **As the tab's host says.** Each tab runs its host's viewer, so the
492
+ keys named are the ones that host's kernel says its viewer takes: this
493
+ machine's `oats version --json` for a tab of this machine, the roster's
494
+ probe of its server for another's
495
+ ([`session-attach-prefix-scroll`](desktop-cli-api.md#features)).
496
+ `Shift+PageUp` where the host's kernel lists the feature, and
497
+ `Ctrl+B [` too where its `sessionViewer.prefixScroll` is true (a tmux of
498
+ 3.3 or later, see
499
+ [Inspect, input and attach](execution-targets.md#inspect-input-and-attach)).
500
+ A host whose kernel does not list it, or one the roster did not reach,
501
+ gets no scroll keys named at all: an older viewer may hand
502
+ `Shift+PageUp` to the agent.
503
+ - **A leader of `Ctrl+B`** (`open.detachKey: "C-b"` in
504
+ [`tui.json`](#change-the-keys-tuijson)) takes `Ctrl+B` before the
505
+ viewer reads it, so `Ctrl+B [` cannot be typed there. The sheet and the
506
+ help name `Shift+PageUp` alone.
507
+ - Copy mode is the agent's pane's: while a tab is scrolled back, every
508
+ other viewer of that agent shows the same frozen screen.
465
509
  - **How it works.** The terminal is the kernel's own viewer,
466
510
  `oats session attach`, run in a pane of a tmux server private to this run
467
511
  of `oats tui`: its socket is in a directory of the run's own (mode 0700,
@@ -537,6 +581,37 @@ Each terminal open in the panel is a tab, and the panel holds up to four.
537
581
  of the row with their dividers (they stay open). The shown tab's name
538
582
  stays whole while the row can hold it, and is cut last.
539
583
  - The TUI takes no mouse input: a tab is shown with the keys below.
584
+ - **The waiting row.** While the shown tab's agent waits on you (a live
585
+ `waitingOnYou` claim, as the list's `!` mark shows it), a row
586
+ stands under its group's tab bar, and the agent's screen starts under it:
587
+
588
+ ```
589
+ │[steward 1]│ backend-lead 2
590
+ │ Needs input · 12 min Survey done: yes/no on bumping Claude Code
591
+ │ 2.1.309 + Codex 0.164.0 and removing their old mise installs
592
+ │>
593
+ ```
594
+
595
+ - It reads `Needs input` in the list's needs-input look (reverse video in
596
+ the waiting colour), then how long the agent has waited, dim, after ` · `
597
+ (` - ` in ASCII), then the claim's message, the agent's own text. The
598
+ age comes first, so a cut never removes it.
599
+ - **A claim with no message** says what it waits on in the TUI's words:
600
+ `waiting on a permission prompt`, `asked you a question`,
601
+ `asked for your attention`, or `waiting for your input` when the
602
+ reason is not one of those.
603
+ - **A long message wraps** to at most 3 rows, and to no more than a
604
+ quarter of the group's height; when more is left, the last row ends in
605
+ `…` (`...` in ASCII). The whole message is in the agent's
606
+ [detail](#what-it-shows), and in `oats status`.
607
+ - **The agent's screen loses those rows** while the row stands, so its
608
+ pane is resized when the claim starts, clears or its text changes, and
609
+ never as the age grows: the rows are counted as if the age were its
610
+ longest, `under a minute`.
611
+ - In a [split](#splits) each group has its own row for its own shown tab.
612
+ A hidden tab's claim adds no row: the list's `!` mark shows it.
613
+ - Under `NO_COLOR` the words carry it: `Needs input` stays in reverse
614
+ video.
540
615
  - **Opening.** `Enter` on a row, an instance in
541
616
  [the palette](#the-palette), `Alt+Shift+Up` or `Alt+Shift+Down`, and a
542
617
  [spawn](#spawning-an-agent)'s new agent open a terminal the same way:
@@ -918,10 +993,12 @@ workspace the list is its row.
918
993
  - **The leader then `Up` or `Down`**, or the [chords](#chords) `Alt+Up` and
919
994
  `Alt+Down` (in the Alt family and on macOS; the Ctrl+Alt and Ctrl+Shift
920
995
  families leave them to the programs, and the leader does it), opens the
921
- workspace before or after the open one, as the list draws them. It does not wrap: at an end nothing
922
- moves, and the line under the list says `No workspace above this one.` or
923
- `No workspace below this one.` until the next key, of any kind (one typed
924
- to an agent too), or a resize. The line stands in the empty row under the
996
+ workspace before or after the open one, as the list draws them. It wraps,
997
+ as the [OATS Desktop](desktop.md#workspaces)'s do: `Down` on the last row
998
+ opens the first, and `Up` on the first opens the last. With no other row
999
+ to open, nothing moves, and the line under the list says `No other
1000
+ workspace to show.` until the next key, of any kind (one typed to an agent
1001
+ too), or a resize. The line stands in the empty row under the
925
1002
  list, so the list of instances does not move while it shows; only when
926
1003
  that list fills the sidebar, which then has no such row, does the line
927
1004
  take a row, the list giving up its last. With the list's focus (`w`) the
@@ -941,7 +1018,8 @@ workspace the list is its row.
941
1018
  workspace's name is underlined until `Enter` opens another; the list of
942
1019
  instances keeps its selection in reverse video, without its `>`. `Up`/`k`,
943
1020
  `Down`/`j`, `g`/`Home` and `G`/`End` move the cursor over the rows that
944
- open; `Enter` opens its row and gives the list of instances the focus;
1021
+ open, and stop at the list's ends (they do not wrap, as the Desktop
1022
+ list's own do not); `Enter` opens its row and gives the list of instances the focus;
945
1023
  `Esc` gives that focus back with nothing opened; `w` again opens the
946
1024
  switcher, for what the list does not hold. Any other key gives the list
947
1025
  of instances the focus, then does what it does there. The cheat sheet
@@ -1605,7 +1683,7 @@ which edits the command line in your editor, is `Ctrl+X` twice, then
1605
1683
  |---|---|
1606
1684
  | `k` or `Space` | opens [the palette](#the-palette) |
1607
1685
  | `1`, `2`, `3` | the Instances, Souls and Capabilities views |
1608
- | `Up`, `Down` | opens the workspace before or after the open one, in [the list of workspaces](#the-list-of-workspaces) as it is drawn (the chords `Alt+Up`, `Alt+Down`). Every row opens, and the list does not wrap. The terminal of the instance before or after is `Alt+Shift+Up`, `Alt+Shift+Down` ([Chords](#chords)) |
1686
+ | `Up`, `Down` | opens the workspace before or after the open one, in [the list of workspaces](#the-list-of-workspaces) as it is drawn (the chords `Alt+Up`, `Alt+Down`). Every row opens, and the moves wrap: past the last row, the first, and before the first, the last. The terminal of the instance before or after is `Alt+Shift+Up`, `Alt+Shift+Down` ([Chords](#chords)) |
1609
1687
  | `Left`, `Right` | shows the tab before or after the shown one; the tab bar does not wrap, and the focus stays where it was |
1610
1688
  | `z` | zooms the shown terminal in or out; with the list focused, gives it the focus and the whole screen |
1611
1689
  | `w` | closes the shown terminal's tab and shows the tab beside it; the agent keeps running |
@@ -2442,7 +2520,8 @@ version:
2442
2520
  - The Souls and Capabilities views list a workspace of this machine's
2443
2521
  souls and capabilities: both are this machine's.
2444
2522
  - There is no sorting and no mouse, and a deployment's heading cannot be
2445
- folded. An open terminal has no scrollback but the viewer's own.
2523
+ folded. An open terminal scrolls back with the viewer's own keys,
2524
+ `Shift+PageUp` and `Ctrl+B [`, and no other.
2446
2525
  - Up to four terminals are open at a time, as tabs, in at most two
2447
2526
  groups. The split cannot be resized or nested, a tab moves only between
2448
2527
  the two groups, and no tab or split is kept from one run to the next, or
@@ -2546,7 +2625,11 @@ alone. The next run removes the directory that is left, with its `tmux`,
2546
2625
  included) and attributes: those are the agent's. With `NO_COLOR` set and
2547
2626
  not empty it uses no colour at all, the agent's included; the agent's
2548
2627
  bold, underline, reverse and the like stay. Nothing is told by colour
2549
- alone.
2628
+ alone. **Yellow says needs input, and only that:** the `!` in place of a
2629
+ row's state mark and the dot in the list of workspaces. A state unknown,
2630
+ `?`, is dim in your terminal's foreground, and a warning (a failed read,
2631
+ `Can't spawn here`, `· 1 on an older version`) is bold red, and a soul's
2632
+ `sand` is in your terminal's foreground ([What it shows](#what-it-shows)).
2550
2633
  - It draws its rules and marks in UTF-8 when `LC_ALL`, else `LC_CTYPE`, else
2551
2634
  `LANG` names UTF-8, and in ASCII otherwise or with `--ascii`. No icon font,
2552
2635
  no emoji. When the locale is not UTF-8, a character outside ASCII in text
package/docs/upgrading.md CHANGED
@@ -6,11 +6,11 @@ host that comes from it.
6
6
 
7
7
  ## Upgrading to the latest version
8
8
 
9
- The latest version is **OATS 0.68.0** ([release notes](release-notes/v0.68.0.md)).
10
- The 0.68.0 Desktop accepts OATS CLIs `>=0.26.0 <0.69.0`.
9
+ The latest version is **OATS 0.69.1** ([release notes](release-notes/v0.69.1.md)).
10
+ The 0.69.1 Desktop accepts OATS CLIs `>=0.26.0 <0.70.0`.
11
11
 
12
12
  **First, read the `## Upgrade` section of every release after yours, up to
13
- 0.68.0,** in the [release notes](release-notes/): it says what to do before
13
+ 0.69.1,** in the [release notes](release-notes/): it says what to do before
14
14
  the CLI changes, and what else must change with it (the Desktop, another
15
15
  tool, a package pin). [Coming from an older version](#coming-from-an-older-version)
16
16
  names the releases that ask for more than the steps below. `oats version`
@@ -19,8 +19,8 @@ prints the version you have.
19
19
  Then, on each host:
20
20
 
21
21
  ```sh
22
- # 0. where the Desktop is installed: Desktop 0.68.0 first
23
- npm install -g @awebai/oats@0.68.0 # 1. the CLI
22
+ # 0. where the Desktop is installed: Desktop 0.69.1 first
23
+ npm install -g @awebai/oats@0.69.1 # 1. the CLI
24
24
  oats update # 2. in each deployment: the plan, then it asks before it runs
25
25
  oats doctor # 3. in the same deployment
26
26
  ```
@@ -166,6 +166,15 @@ of the Desktop and the CLI, and an optional package pin. A change a script
166
166
  must follow is in its release's Upgrade section whether or not it is listed
167
167
  here.
168
168
 
169
+ - **[0.69.1](release-notes/v0.69.1.md#upgrade):** 0.69.0 was tagged but never
170
+ published; 0.69.1 carries all of it, so follow
171
+ [0.69.0's Upgrade section](release-notes/v0.69.0.md#upgrade): the Desktop
172
+ first, then the CLI: a 0.68 Desktop refuses a 0.69 CLI. Every host that shares a workspace
173
+ runs OATS 0.68.0 or later before any of them syncs to oats.aweb 1.32.0.
174
+ - **[0.68.0](release-notes/v0.68.0.md#upgrade):** the Desktop first, then the
175
+ CLI: a 0.67 Desktop refuses a 0.68 CLI. The catalog pins new package versions; after `oats sync`, a stopped
176
+ home can move to them with `oats instance upgrade` instead of a respawn
177
+ ([Moving existing homes](#moving-existing-homes-to-locked-package-versions)).
169
178
  - **[0.67.0](release-notes/v0.67.0.md#upgrade), first published as
170
179
  0.67.1:** the leader is Ctrl+X in OATS Desktop and in `oats tui`, on every
171
180
  platform; a leader you rebound is kept. A `tui.json` that gives `ctrl+x` to an action and names no leader
@@ -54,7 +54,7 @@ members: # repo refs, NO @revision (E_WORKSPAC
54
54
  - git:github.com/acme/tools # a member that ALSO publishes a package (see below)
55
55
 
56
56
  packages: # the ONLY versioned things
57
- oats.framework: v1.14.1 # bare version → resolves through the official catalog
57
+ oats.framework: v1.15.1 # bare version → resolves through the official catalog
58
58
  oats.okf: v5.3.0
59
59
  acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
60
60