@awebai/oats 0.68.1 → 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 (67) 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 +108 -10
  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.69.0.md +658 -0
  15. package/docs/release-notes/v0.69.1.md +25 -0
  16. package/docs/servers.md +44 -5
  17. package/docs/souls-and-instances.md +11 -7
  18. package/docs/tui.md +77 -12
  19. package/docs/upgrading.md +12 -7
  20. package/docs/workspaces.md +1 -1
  21. package/lib/core.mjs +345 -89
  22. package/lib/file-pieces.mjs +49 -0
  23. package/lib/instance-events.mjs +25 -4
  24. package/lib/launch-prompt-fixtures/README.md +62 -0
  25. package/lib/launch-prompt-fixtures/resume-confirmation.json +32 -0
  26. package/lib/launch-prompt-fixtures.mjs +49 -0
  27. package/lib/launch-prompt-resume.mjs +55 -0
  28. package/lib/login-environment.mjs +27 -9
  29. package/lib/schedule.mjs +3 -3
  30. package/lib/servers.mjs +117 -23
  31. package/lib/session-end.mjs +82 -0
  32. package/lib/session-input.mjs +43 -9
  33. package/lib/session-resume-contract.mjs +32 -0
  34. package/lib/session-resume.mjs +310 -0
  35. package/lib/session-seen.mjs +163 -0
  36. package/lib/session-viewer.mjs +147 -44
  37. package/lib/soul-composition.mjs +2 -1
  38. package/lib/start-env.mjs +110 -0
  39. package/lib/tmux-server-scope.mjs +139 -14
  40. package/lib/workspace.mjs +38 -4
  41. package/package-catalog.json +10 -4
  42. package/package.json +1 -1
  43. package/packages/client/cli-adapter.mjs +9 -0
  44. package/packages/client/cli-locator.mjs +3 -2
  45. package/packages/client/deployment-data.mjs +7 -0
  46. package/packages/client/deployment-panel.mjs +3 -0
  47. package/packages/client/file-output-exec.mjs +98 -0
  48. package/packages/client/launch-prompt-outcome.mjs +25 -13
  49. package/packages/client/own-codes.mjs +2 -0
  50. package/packages/client/session-attach.mjs +35 -5
  51. package/packages/client/session-resume-cli.mjs +64 -0
  52. package/packages/client/session-resume-trigger.mjs +167 -0
  53. package/packages/client/session-resume.mjs +332 -0
  54. package/packages/client/tmux-status.mjs +30 -7
  55. package/packages/client/waiting-on-you.mjs +11 -4
  56. package/packages/client/workspace-step.mjs +17 -5
  57. package/packages/record/lib/last-conversation.mjs +123 -0
  58. package/packages/record/lib/session-roots.mjs +10 -1
  59. package/packages/tui/lib/client.mjs +1 -1
  60. package/packages/tui/lib/main.mjs +5 -3
  61. package/packages/tui/lib/model.mjs +45 -12
  62. package/packages/tui/lib/store.mjs +8 -7
  63. package/packages/tui/lib/term/text.mjs +12 -9
  64. package/packages/tui/lib/views/frame.mjs +72 -7
  65. package/packages/tui/lib/views/help.mjs +8 -3
  66. package/packages/tui/lib/views/instances.mjs +3 -2
  67. 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
@@ -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
@@ -302,7 +302,7 @@ in its workspace for the rest of the run, also while it is not reached.
302
302
  | `?` | `?` | state unknown: the kernel or the terminal probe could not tell, or the instance's machine was not reached |
303
303
  | `◆` | `#` | held by a spawn or a retire: under way (Retiring…), failed or not finished ([below](#held-rows)) |
304
304
  | `+n` | `+n` | after a name: n instances folded away below it |
305
- | `!` | `!` | needs input: in place of the state mark, in yellow and reverse video (not reversed on the selected row) |
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
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 |
307
307
  | `>` | `>` | the selected row (also drawn in reverse video), and the pane the movement keys act on |
308
308
  | `*` | `*` | in the switcher: the workspace that is open |
@@ -473,9 +473,39 @@ fit; the detail shows them whole. The TUI's own words end the same way:
473
473
  reason holds it (an instance gone from its machine, say). An agent on another machine is asked first whether it
474
474
  can be opened (`Esc` gives that up); a machine whose OATS cannot open its
475
475
  sessions is said then.
476
- - **No scrollback but the viewer's own, and no mouse.** The panel shows
477
- what the agent's window shows now; what has scrolled away is reached as
478
- 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.
479
509
  - **How it works.** The terminal is the kernel's own viewer,
480
510
  `oats session attach`, run in a pane of a tmux server private to this run
481
511
  of `oats tui`: its socket is in a directory of the run's own (mode 0700,
@@ -551,6 +581,37 @@ Each terminal open in the panel is a tab, and the panel holds up to four.
551
581
  of the row with their dividers (they stay open). The shown tab's name
552
582
  stays whole while the row can hold it, and is cut last.
553
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.
554
615
  - **Opening.** `Enter` on a row, an instance in
555
616
  [the palette](#the-palette), `Alt+Shift+Up` or `Alt+Shift+Down`, and a
556
617
  [spawn](#spawning-an-agent)'s new agent open a terminal the same way:
@@ -932,10 +993,12 @@ workspace the list is its row.
932
993
  - **The leader then `Up` or `Down`**, or the [chords](#chords) `Alt+Up` and
933
994
  `Alt+Down` (in the Alt family and on macOS; the Ctrl+Alt and Ctrl+Shift
934
995
  families leave them to the programs, and the leader does it), opens the
935
- workspace before or after the open one, as the list draws them. It does not wrap: at an end nothing
936
- moves, and the line under the list says `No workspace above this one.` or
937
- `No workspace below this one.` until the next key, of any kind (one typed
938
- 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
939
1002
  list, so the list of instances does not move while it shows; only when
940
1003
  that list fills the sidebar, which then has no such row, does the line
941
1004
  take a row, the list giving up its last. With the list's focus (`w`) the
@@ -955,7 +1018,8 @@ workspace the list is its row.
955
1018
  workspace's name is underlined until `Enter` opens another; the list of
956
1019
  instances keeps its selection in reverse video, without its `>`. `Up`/`k`,
957
1020
  `Down`/`j`, `g`/`Home` and `G`/`End` move the cursor over the rows that
958
- 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;
959
1023
  `Esc` gives that focus back with nothing opened; `w` again opens the
960
1024
  switcher, for what the list does not hold. Any other key gives the list
961
1025
  of instances the focus, then does what it does there. The cheat sheet
@@ -1619,7 +1683,7 @@ which edits the command line in your editor, is `Ctrl+X` twice, then
1619
1683
  |---|---|
1620
1684
  | `k` or `Space` | opens [the palette](#the-palette) |
1621
1685
  | `1`, `2`, `3` | the Instances, Souls and Capabilities views |
1622
- | `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)) |
1623
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 |
1624
1688
  | `z` | zooms the shown terminal in or out; with the list focused, gives it the focus and the whole screen |
1625
1689
  | `w` | closes the shown terminal's tab and shows the tab beside it; the agent keeps running |
@@ -2456,7 +2520,8 @@ version:
2456
2520
  - The Souls and Capabilities views list a workspace of this machine's
2457
2521
  souls and capabilities: both are this machine's.
2458
2522
  - There is no sorting and no mouse, and a deployment's heading cannot be
2459
- 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.
2460
2525
  - Up to four terminals are open at a time, as tabs, in at most two
2461
2526
  groups. The split cannot be resized or nested, a tab moves only between
2462
2527
  the two groups, and no tab or split is kept from one run to the next, or
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.1** ([release notes](release-notes/v0.68.1.md)).
10
- The 0.68.1 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.1,** 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.1 first
23
- npm install -g @awebai/oats@0.68.1 # 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,8 +166,13 @@ 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.68.0](release-notes/v0.68.0.md#upgrade):** the Desktop first, then the CLI: a 0.67 Desktop refuses a 0.68
170
- CLI. The catalog pins new package versions; after `oats sync`, a stopped
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
171
176
  home can move to them with `oats instance upgrade` instead of a respawn
172
177
  ([Moving existing homes](#moving-existing-homes-to-locked-package-versions)).
173
178
  - **[0.67.0](release-notes/v0.67.0.md#upgrade), first published as
@@ -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