@awebai/oats 0.58.0 → 0.60.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 (63) hide show
  1. package/bin/oats.mjs +1 -1
  2. package/docs/desktop-cli-api.md +80 -8
  3. package/docs/desktop.md +30 -3
  4. package/docs/execution-targets.md +18 -2
  5. package/docs/implementation.md +3 -0
  6. package/docs/integrations.md +2 -2
  7. package/docs/knowledge.md +4 -4
  8. package/docs/official-catalog.md +4 -4
  9. package/docs/packages.md +14 -14
  10. package/docs/release-notes/v0.59.0.md +288 -0
  11. package/docs/release-notes/v0.60.0.md +104 -0
  12. package/docs/servers.md +4 -1
  13. package/docs/souls-and-instances.md +21 -0
  14. package/docs/tui.md +753 -119
  15. package/docs/workspaces.md +2 -2
  16. package/lib/core.mjs +258 -57
  17. package/lib/read-ahead-worker.mjs +119 -0
  18. package/lib/read-ahead.mjs +115 -0
  19. package/lib/retire-state.mjs +33 -0
  20. package/lib/servers.mjs +9 -1
  21. package/lib/session-input.mjs +53 -26
  22. package/package-catalog.json +3 -3
  23. package/package.json +1 -1
  24. package/packages/client/capability-catalog.mjs +93 -0
  25. package/packages/client/capability-facts.mjs +59 -0
  26. package/packages/client/capability-rows.mjs +121 -0
  27. package/packages/client/catalog-messages.mjs +12 -0
  28. package/packages/client/cli-locator.mjs +2 -2
  29. package/packages/client/deployment-data.mjs +4 -0
  30. package/packages/client/deployment-panel.mjs +3 -0
  31. package/packages/client/instance-acts.mjs +23 -8
  32. package/packages/client/instance-presentation.mjs +3 -2
  33. package/packages/client/instance-tree.mjs +84 -39
  34. package/packages/client/lifecycle-confirmation.mjs +9 -3
  35. package/packages/client/remote-roster.mjs +4 -1
  36. package/packages/client/retire-in-flight.mjs +65 -0
  37. package/packages/client/retire-state.mjs +30 -0
  38. package/packages/client/soul-catalog.mjs +8 -0
  39. package/packages/client/soul-facts.mjs +7 -0
  40. package/packages/client/spawn-apply.mjs +13 -4
  41. package/packages/client/spawn-messages.mjs +8 -0
  42. package/packages/client/subsequence-score.mjs +15 -0
  43. package/packages/tui/README.md +23 -10
  44. package/packages/tui/lib/actions.mjs +63 -5
  45. package/packages/tui/lib/client.mjs +17 -1
  46. package/packages/tui/lib/config.mjs +7 -2
  47. package/packages/tui/lib/main.mjs +364 -82
  48. package/packages/tui/lib/model.mjs +614 -57
  49. package/packages/tui/lib/panel.mjs +436 -125
  50. package/packages/tui/lib/read.mjs +52 -26
  51. package/packages/tui/lib/store.mjs +1025 -65
  52. package/packages/tui/lib/term/keys.mjs +9 -2
  53. package/packages/tui/lib/term/text.mjs +4 -0
  54. package/packages/tui/lib/term/through.mjs +12 -1
  55. package/packages/tui/lib/views/capabilities.mjs +239 -0
  56. package/packages/tui/lib/views/frame.mjs +433 -99
  57. package/packages/tui/lib/views/help.mjs +61 -15
  58. package/packages/tui/lib/views/instances.mjs +43 -25
  59. package/packages/tui/lib/views/palette.mjs +66 -0
  60. package/packages/tui/lib/views/souls.mjs +270 -0
  61. package/packages/tui/lib/views/spawn.mjs +301 -0
  62. package/packages/tui/lib/views/split.mjs +29 -0
  63. package/skills/oats-getting-started/SKILL.md +2 -2
@@ -0,0 +1,288 @@
1
+ # OATS 0.59.0
2
+
3
+ 2026-10-16
4
+
5
+ ## Upgrade
6
+
7
+ - **Install the Desktop first and the CLI second,** as
8
+ [Upgrading](../upgrading.md) says: a 0.58 Desktop refuses a 0.59.0 CLI. The
9
+ 0.59.0 Desktop accepts OATS CLIs `>=0.26.0 <0.60.0`.
10
+
11
+ - **The official catalog moves three pins:** oats.framework 1.12.0 → 1.12.2,
12
+ oats.okf 5.2.0 → 5.2.1 and oats.aweb 1.27.3 → 1.28.0 (see Provider
13
+ updates). oats.engineering 1.10.0, oats.cloning 1.0.1, oats.authoring
14
+ 1.0.3, oats.jira 1.0.1, oats.linear 1.0.1 and oats.apps 1.0.0 are
15
+ unchanged. A deployment takes them by changing its pins and running
16
+ `oats sync`. Only new spawns use them.
17
+
18
+ - **With oats.aweb 1.28.0, a host that needs the wake broker** (a Codex
19
+ home, `delivery: session`, or a join) installs it once with
20
+ `oats aweb wake install`. Run it from the host's own login session (on
21
+ macOS, at the desktop), not over ssh.
22
+
23
+ - **`oats tui`: the back key is now the leader, pressed twice to go back to
24
+ the list.** `Ctrl+\` (`open.detachKey` in `tui.json`) pressed once in a
25
+ terminal waits for a command key; pressed again it gives the focus to the
26
+ list, as one press did up to 0.58.0. A `tui.json` whose `open.detachKey` is a
27
+ key an action has is now refused: give one of the two another key. See
28
+ Added and Changed ([#855](https://github.com/awebai/oats/issues/855)).
29
+
30
+ ## Added
31
+
32
+ - **`retire` on status rows: whether a retire of the home is running,
33
+ cannot be told, failed or was interrupted** (feature `status-retire-state`,
34
+ [#1247](https://github.com/awebai/oats/issues/1247)). `oats status --json`
35
+ instance rows carry `retire: {state, since, self, code?, message?}` while a
36
+ retire of the home is running, scheduled or owed, and no such key
37
+ otherwise. It is read only from the files beside the home: the self-retire
38
+ marker (`self: true`) with its completion process and its result file, or,
39
+ without a marker, the home's claim held by an `oats retire` (`self:
40
+ false`). `state` is `running`, `unknown` (liveness cannot be read),
41
+ `failed` (with the result's kernel `code` and its one-line `message`) or
42
+ `interrupted` (the completion process is gone). `since` is always an
43
+ instant (the recorded time, else the file's modification time), and
44
+ `code` and `message` are strings or absent, never `null`. Status still takes no
45
+ claim, removes no file and signals no process. `retirePending` keeps its
46
+ meaning. Remote roster rows relay `retire` only when the host's row has
47
+ it, checked by the same rule, and drop a value that fails it. A client
48
+ reads the field only when `oats version --json` lists
49
+ `status-retire-state`: an older kernel never carries it
50
+ ([`retire`](../desktop-cli-api.md#row-retire)).
51
+
52
+ - `oats session inspect --json` reports the agent window's `size: { cols, rows }`
53
+ in cells when present, including through `--server`. The dimensions come
54
+ from the same tmux call as the pane identity and are omitted for absent or
55
+ dead terminals. `oats version --json` advertises `session-inspect-size`, so
56
+ viewers can discover support before opening a PTY at that size (#1285).
57
+
58
+ - **`oats tui` has a leader key, so every action is reached by keys from
59
+ every focus** ([#855](https://github.com/awebai/oats/issues/855)). The
60
+ leader is `Ctrl+\` (`open.detachKey` in `tui.json`), then one plain key:
61
+ `k` or `Space` the palette, `1` to `3` the views, `Up`/`Down` the
62
+ previous or next instance's terminal, `z` zoom, `w` close the terminal,
63
+ `X`/`R`/`S`/`D` the acts, `/` filter, `o` workspaces, `?` help, and `Esc`
64
+ or the leader again the list. In a terminal the leader is still the one
65
+ key taken from the agent, now twice to go back to the list. A key that
66
+ comes in the same read as the leader cancels it, so a paste never runs a
67
+ command. See [the TUI page](../tui.md#the-leader).
68
+ - **A palette, as the Desktop's ⌘K:** the leader then `k`, or `Ctrl+K` in
69
+ the list, opens one input over the instances that can be opened (the
70
+ most recently opened or shown in the run first), the views, the selected
71
+ instance's acts, and workspaces, refresh and help, filtered as you type
72
+ with the Desktop's match. Choosing an instance shows its tab, or opens it
73
+ in a new one. See [the TUI page](../tui.md#the-palette).
74
+
75
+ - **`oats tui` lists the open workspace's souls**
76
+ ([#855](https://github.com/awebai/oats/issues/855)). `2`, or the leader
77
+ then `2`, shows the Souls view: one row per soul with its colour, a count
78
+ of its instances on this machine, and `!` for a soul a spawn here would
79
+ refuse. The detail beside it says where the soul comes from and where it
80
+ works, which harness a spawn would use, its teams, its capabilities and
81
+ its instances here. `i` (or `Enter` in the detail) shows those instances
82
+ in the Instances view, filtered by that soul; `Esc` clears the filter.
83
+ The list is the OATS Desktop's, read with `oats souls` only once the view
84
+ is first shown, and again only when the workspace changes, or with `r`.
85
+ The palette lists the souls once they are read. `tui.json` has a new
86
+ action, `soul-instances` (default `i`). See
87
+ [the TUI page](../tui.md#the-souls-view).
88
+
89
+ - **`oats tui` spawns an agent on this machine**
90
+ ([#855](https://github.com/awebai/oats/issues/855)). `n` (or the leader
91
+ then `n`) opens a picker of the open workspace's souls; `N` spawns
92
+ another of the selected instance's soul. The preview is the OATS
93
+ Desktop's, read with `oats spawn <soul> --preview --json`: the name, the
94
+ home, where it works, the harness and model and where they were chosen,
95
+ the team and the worktree setup, with the launch-prompt policy, the
96
+ warnings and the modules folded to one row each. `Tab` moves between
97
+ Spawn, the name (the instance's `--purpose`), the parent and the folds;
98
+ `Enter` on Spawn applies exactly the decision on screen, through the
99
+ shared apply, and a pasted `n` and `Enter`s never spawn. When the agent
100
+ is created and started its terminal opens beside the list; any other
101
+ outcome is said in the Desktop's words, with what to do next, and an
102
+ outcome that is not known is checked once with `C`. One spawn runs at a
103
+ time; spawning on another machine, or with another harness, model or a
104
+ task, stays `oats spawn`. The palette lists Spawn an agent and Spawn
105
+ another. `tui.json` has three new actions, `spawn` (default `n`),
106
+ `spawn-another` (`N`) and `spawn-check` (`C`). See
107
+ [the TUI page](../tui.md#spawning-an-agent).
108
+
109
+ - **`oats tui` splits its panel in two groups**
110
+ ([#855](https://github.com/awebai/oats/issues/855)). The leader then `|`
111
+ splits it side by side, and the leader then `-` one above the other (`|`
112
+ and `-` alone in the Instances view). The open tabs stay in the first
113
+ group; the second starts empty, says `Enter on an agent opens it here`,
114
+ and an agent opened then opens in it. Each group has its own strip and
115
+ shown tab, both shown tabs are drawn, and a rule separates them. The
116
+ leader then `Tab` goes to the other group, the leader then `m` moves the
117
+ shown tab there, and the leader then `x` closes an empty group; closing a
118
+ group's last tab gives the other the whole panel. Each group needs 40
119
+ columns side by side or 8 rows one above the other, and the four tabs
120
+ are counted across both. `tui.json` has five new actions: `split-right`
121
+ (default `|`), `split-down` (`-`), and `group-next`, `tab-move` and
122
+ `group-close`, which have no key of their own by default. See
123
+ [the TUI page](../tui.md#splits).
124
+
125
+ - **`oats tui` opens up to four terminals at a time, as tabs**
126
+ ([#855](https://github.com/awebai/oats/issues/855)). The panel's top row
127
+ is the tab strip: each tab's agent in the order it was opened, the shown
128
+ one in reverse while it has the focus and bold otherwise, and `•` (`*` in
129
+ ASCII) after a hidden tab whose agent wrote since it was last shown. With
130
+ one tab the row reads as before. `[` and `]` in the Instances view, or
131
+ the leader then `Left`/`Right` from any focus, show the tab before or
132
+ after, without wrapping; showing a tab selects its row in the list and
133
+ leaves the focus where it was. Opening an instance that has a tab shows
134
+ that tab. The palette opens with the second recent instance selected
135
+ when the first is the shown tab's, as the Desktop's does. `tui.json` has
136
+ two new actions, `tab-previous` (default `[`) and `tab-next` (`]`). See
137
+ [the TUI page](../tui.md#tabs).
138
+
139
+ ## Changed
140
+
141
+ - **A retire with a large work tree is about twice as fast
142
+ ([#1247](https://github.com/awebai/oats/issues/1247)).** On a Linux
143
+ laptop (btrfs on dm-crypt), the retire of a home holding about 400 MiB in
144
+ 37,000 files under `work/` took 18–30 s and now takes 10–17 s. Every
145
+ recovery copy is still written and verified before the retire hooks run,
146
+ and every safety rule is kept.
147
+ - **Cold reads in parallel.** A digest reads its files one at a time, and
148
+ a tree outside the page cache read at about 40 MB/s: the copy of a
149
+ clone just made by a reflink, or a `node_modules/` not read for a
150
+ while. A few worker threads now read the next files ahead of it. No
151
+ digest value changes, including those of baselines older kernels wrote,
152
+ and no error changes. The verification still reads the copy's own bytes
153
+ back.
154
+ - **One read per state.** A worktree's untracked and ignored digest and
155
+ its bytes are taken from one read of each file, both before the hooks
156
+ and after them.
157
+ - **A directory instance's pre-hook copy no longer reads its source a
158
+ second time.** A file changed before the copy read it still refuses the
159
+ retire before any hook runs. A file changed during the copy, after it
160
+ was copied, used to refuse the retire. It is now preserved, verified,
161
+ under `after-hooks/`, as a worktree's work already was
162
+ ([souls-and-instances.md](../souls-and-instances.md)).
163
+
164
+ - **Desktop and TUI: the instance list is in name order**
165
+ ([#1262](https://github.com/awebai/oats/issues/1262)). The sidebar, the
166
+ command palette and the TUI's list order instances by name, each bundle by
167
+ its top instance. Starting or stopping an instance no longer moves it, and
168
+ running instances are no longer gathered at the top.
169
+
170
+ - **OATS Desktop accepts an `oats` CLI 0.59.x.** Its band is now
171
+ `>=0.26.0 <0.60.0`. 0.59 adds no new gate on the band: the Desktop reads
172
+ the `retire` field on status rows where it is present (feature
173
+ `status-retire-state`).
174
+
175
+ - **`oats tui`: the header starts with the workspace's name**, with no `oats` title,
176
+ and the Souls and Capabilities views are no longer dim: `2` and `3`, or
177
+ the leader then `2`/`3`, show what each will hold and what to run until
178
+ then.
179
+ - **`oats tui`: the footer is one row of keys from the first column**, with no rule
180
+ above it, and names `C-\ commands` first in every focus. The `1-3 views`
181
+ hint is gone: the header names the views.
182
+ - **`oats tui`, a quieter list:** a row is its state mark and its name, the harness
183
+ and the state in words moved to the detail, a folded row says `+n`, a
184
+ machine's heading is its name, with the time of its read only when it
185
+ differs from the header's, and with a terminal open the list keeps 30
186
+ columns. A saved route to an instance its machine no longer has reads
187
+ `gone from <machine>`, as the Desktop says it, not `unknown`.
188
+ - **`oats tui`: `tui.json` is refused when `open.detachKey` is a key an action has**,
189
+ since the leader is read as a key in the list too: `C-l` is `Ctrl+L`,
190
+ `C-k` is `Ctrl+K`, `C-j` is `Enter`. Give the action another key, or the
191
+ leader another key.
192
+
193
+ - **A hidden tab in `oats tui` no longer costs CPU while its agent
194
+ prints** ([#855](https://github.com/awebai/oats/issues/855)). Its first
195
+ output marks the tab as before. Its pane is then paused for `oats tui`
196
+ (tmux's `refresh-client -A '%<pane>:pause'`) until the tab is shown
197
+ again, when it is drawn from the pane's current screen. Measured with a
198
+ hidden agent printing without pause, `oats tui` takes about 0.4% of a
199
+ core instead of 11%, and its private tmux server 9% instead of 14%. The
200
+ same holds while another view or an overlay covers the panel.
201
+
202
+ - **Opening another agent's terminal in `oats tui` no longer closes the
203
+ one that was open.** It opens in a new tab after the shown one. With four
204
+ tabs open nothing closes by itself: the line says
205
+ `4 terminals are open; close one with C-\ w.` Closing a tab (`c`, or the
206
+ leader then `w`) shows the tab to its right, else the one to its left;
207
+ closing the last one gives the right side back to the detail. A tab whose
208
+ viewer ends by itself closes, hidden or shown, with its line; a hidden
209
+ one's end leaves the shown tab and the focus as they were. Opening
210
+ another workspace closes every tab, and the agents keep running.
211
+
212
+ ## Fixed
213
+
214
+ - **Desktop and `oats tui`: a retire in progress no longer shows as failed;
215
+ it reads Retiring…** ([#1247](https://github.com/awebai/oats/issues/1247)).
216
+ An instance being retired read **Retire didn't finish** while its retire
217
+ was still running, as if it had failed. Its row now reads **Retiring…**
218
+ while the retire runs, while OATS cannot tell whether the process holding
219
+ it still runs, and from the moment you send a retire until the roster has
220
+ been read after its answer. With an OATS that does not report a retire's
221
+ state, a pending retire reads **Retiring…** too. A retiring row offers no
222
+ start, stop, restart or open; Retire stays reachable but out of the way
223
+ (in the Desktop's row menu, on the TUI's key). A self-retire whose
224
+ completion failed reads **Retire failed**, with OATS's own message and
225
+ code through the display filter, and one whose completion was lost reads
226
+ **Retire didn't finish**; both offer Retire to finish it. See
227
+ [Stopping and retiring](../desktop.md#stopping-and-retiring) and
228
+ [held rows](../tui.md#held-rows).
229
+
230
+ - **Desktop and TUI: a bundle keeps its place when its instance gains or
231
+ loses children** ([#1262](https://github.com/awebai/oats/issues/1262)).
232
+ An instance that spawns its first child no longer jumps to the top of the
233
+ list with its new bundle: it stays where it was, with the child under it,
234
+ and it stays there when its last child goes.
235
+
236
+ - **`oats tui` no longer loses a terminal's exit status on tmux built
237
+ with libutempter** ([#1277](https://github.com/awebai/oats/issues/1277)).
238
+ With Ubuntu's or Debian's tmux, a viewer that exited as its pane closed
239
+ could be left unreaped by tmux. The terminal then closed ten seconds
240
+ later, with "ended without saying why" where its own line belonged: for
241
+ example "could not be opened", with what the viewer printed under it.
242
+ While a terminal waits for its status, `oats tui` now has tmux reap its
243
+ children once a second (`run-shell true` on its private server), so the
244
+ terminal closes within a second or two with its status.
245
+
246
+ ## Provider updates
247
+
248
+ - **oats.aweb 1.28.0: `oats aweb wake install` puts the host wake broker in
249
+ place** ([#1224](https://github.com/awebai/oats/issues/1224)). The catalog
250
+ and this workspace pin `oats.aweb: v1.28.0`.
251
+ - `oats aweb wake install|status|uninstall` (with `--plan`) writes, checks
252
+ and removes a per-user systemd or launchd unit that runs `aw wake run`.
253
+ It recognises only its own unit: a hand-written one is refused
254
+ (`E_WAKE_UNIT_CONFLICT`, with the steps to retire it).
255
+ - Readiness adds the warning `claude-channel-mode-default` (a Claude home
256
+ in development channel mode because `claudeChannelMode` is unset) and a
257
+ soul-scope broker check: a soul with `delivery: session` or a join fails
258
+ readiness while no broker runs.
259
+ - `/oats-host-delivery` (oats.setup 2.6.1, oats.framework 1.11.1 and later)
260
+ teaches it. The floor is unchanged (OATS >=0.52.0).
261
+ - A deployment gets it by pinning `oats.aweb: v1.28.0` and running
262
+ `oats sync`; only new spawns use it. Install the broker from the host's
263
+ own login session (on macOS, at the desktop).
264
+
265
+ - **oats.okf 5.2.1: faster spawn checks** ([#1246](https://github.com/awebai/oats/issues/1246)).
266
+ The catalog and this workspace pin `oats.okf: v5.2.1`. Its spawn hook primes
267
+ only the bases a soul owns or reads, and checks a usable cached commit
268
+ offline first. A node or owner mismatch on a cache that is due gets one
269
+ bounded normal resolution before it refuses, so a new accepted node is
270
+ never rejected because of an old cache. One `git cat-file --batch` replaces
271
+ one process per blob in accepted-tree validation. Measured on #1246: an
272
+ expired cache 1088 → 561 ms, a cached revalidation 3175 → 1047 ms. The
273
+ harvest duty, inject and skills of 5.2.0 are unchanged, and so is the
274
+ floor (OATS >=0.49.0). A deployment gets it by pinning
275
+ `oats.okf: v5.2.1` and running `oats sync`; only new spawns use it.
276
+ - **oats.framework 1.12.1, oats.core 2.6.2: `/oats-operate` says how to read
277
+ an agent window's size** ([#1285](https://github.com/awebai/oats/issues/1285)).
278
+ `oats session inspect --json` reports `size: { cols, rows }` where the
279
+ kernel lists `session-inspect-size` in `oats version --json`; the skill
280
+ names that check, and that a `--server` inspect needs it on the host.
281
+ Instruction text only; the floors are unchanged. A deployment gets it by
282
+ pinning `oats.framework: v1.12.1` and running `oats sync`. Instances already
283
+ running keep the skills they were spawned with.
284
+ - **oats.framework 1.12.2, oats.setup 2.7.1: `/oats-onboarding` pins
285
+ `oats.okf` 5.2.1** ([#1246](https://github.com/awebai/oats/issues/1246)).
286
+ Its knowledge-operations card names and pins the catalog's OKF release.
287
+ Instruction text only; the floors are unchanged. A deployment gets it by
288
+ pinning `oats.framework: v1.12.2` and running `oats sync`.
@@ -0,0 +1,104 @@
1
+ # OATS 0.60.0
2
+
3
+ 2026-10-16
4
+
5
+ ## Upgrade
6
+
7
+ - **Install the Desktop first and the CLI second,** as
8
+ [Upgrading](../upgrading.md) says: a 0.59 Desktop refuses a 0.60.0 CLI. The
9
+ 0.60.0 Desktop accepts OATS CLIs `>=0.26.0 <0.61.0`.
10
+
11
+ - **`running` in a status row now means the harness is running**
12
+ ([#364](https://github.com/awebai/oats/issues/364)). A window left at its
13
+ fallback shell after Stop reads `running: false`, `runtimeState: "shell"`;
14
+ before, it read `true` because the window existed. A script or tool that
15
+ reads `oats status --json` to see whether an agent is running now gets the
16
+ answer the lifecycle commands give. See Changed.
17
+
18
+ - **The official catalog moves two pins:** oats.framework 1.12.2 → 1.12.3
19
+ and oats.aweb 1.28.0 → 1.29.0 (see Provider updates). The other packages
20
+ are unchanged. A deployment takes them by changing its pins and running
21
+ `oats sync`. Only new spawns use them.
22
+
23
+ ## Added
24
+
25
+ - **`oats tui` lists the open workspace's capabilities**
26
+ ([#855](https://github.com/awebai/oats/issues/855)). `3`, or the leader
27
+ then `3`, shows the Capabilities view, which until now was a placeholder:
28
+ the capabilities in the OATS Desktop's sections (Workspace owned, Repo
29
+ owned, Packages), grouped by repository or package, each with its layer.
30
+ The detail beside it says what the capability is, where it comes from,
31
+ the skills, commands and hooks it provides, and the souls that use it,
32
+ each with how many of its instances here carry it and how many of those
33
+ are on an older version. In the detail, `Up`/`Down` mark a soul and
34
+ `Enter` shows it in the Souls view. The list is the Desktop's, read with
35
+ `oats capabilities` only once the view is first shown, and again only
36
+ when the workspace changes, or with `r`. The palette lists the
37
+ capabilities once they are read. See
38
+ [the TUI page](../tui.md#the-capabilities-view).
39
+
40
+ ## Changed
41
+
42
+ - **`oats status` reports whether the harness is running**
43
+ ([#364](https://github.com/awebai/oats/issues/364)). After Stop leaves a
44
+ fallback shell, the row reads `running: false` with `runtimeState: "shell"`,
45
+ even though its tmux window remains. A live harness remains running, and an
46
+ unreadable session remains unknown. Pane reads are batched per socket and
47
+ session.
48
+
49
+ - **OATS Desktop accepts an `oats` CLI 0.60.x.** Its band is now
50
+ `>=0.26.0 <0.61.0`. 0.60 adds no new gate on the band: a status row's
51
+ `running: false` with `runtimeState: "shell"` for a window at its fallback
52
+ shell is what the Desktop's own terminal probe already reports for a local
53
+ row, and a server's rows now read the same way.
54
+
55
+ - **`oats tui` polish** ([#855](https://github.com/awebai/oats/issues/855)).
56
+ The footer names `[/] tab` while two tabs or more are open. The help's
57
+ Marks section lists the soul mark `■` (`#` in ASCII) and a refused soul's
58
+ `!`. A split one above the other joins the list's bar with `├` (`+` in
59
+ ASCII).
60
+
61
+ ## Fixed
62
+
63
+ - **`r` in the `oats tui` Souls view keeps the souls when the read fails**
64
+ ([#1301](https://github.com/awebai/oats/issues/1301)). In 0.59.0, `r`
65
+ forgot the souls before reading them again, so a read that failed left
66
+ only the failure. Now the souls stay listed while `r` reads, and a read
67
+ that fails keeps them under a heading that says it failed, as the
68
+ Capabilities view does. See [the TUI page](../tui.md#the-souls-view).
69
+
70
+ - **`oats tui`: a package soul's instances are its own in the Souls view**
71
+ ([#855](https://github.com/awebai/oats/issues/855)). In 0.59.0 the Souls
72
+ view counted no instances for a soul that comes from a package, and `i`
73
+ on it listed none: the view did not match the name its instances carry,
74
+ `<package>--<soul>`. Its row now counts its instances on this machine,
75
+ `i` lists them in the Instances view, and its detail names them. See
76
+ [the TUI page](../tui.md#the-souls-view).
77
+
78
+ ## Provider updates
79
+
80
+ - **oats.framework 1.12.3, oats.core 2.6.3: `/oats-operate` says what
81
+ `running` means** ([#364](https://github.com/awebai/oats/issues/364)).
82
+ From OATS 0.60.0, a status row's `running` is the harness's liveness: a
83
+ window left at its fallback shell after Stop reads `running: false`,
84
+ `runtimeState: "shell"`. The skill dates the rule, since an older kernel
85
+ still reports such a window as running. Instruction text only; the floors
86
+ are unchanged. A deployment gets it by pinning `oats.framework: v1.12.3`
87
+ and running `oats sync`.
88
+
89
+ - **oats.aweb 1.29.0: the agent status publisher.** The catalog and this
90
+ workspace pin `oats.aweb: v1.29.0`.
91
+ - `oats aweb health enable | status | disable | publish` publishes, once a
92
+ minute, a signed status for every agent of the deployment to aweb:
93
+ whether it can be reached (`yes`, `degraded`, `no` or `unknown`), why
94
+ not, and who fixes it. It is opt-in and host-only
95
+ (`settings.oats.aweb.health` in `oats-local.yaml`), runs in the
96
+ deployment directory, never inside an instance, and needs aw 1.36.38 to
97
+ publish (checked before anything is sent). `disable` clears every
98
+ designation it made.
99
+ - `/oats-aweb`: on macOS, `oats aweb wake install` runs from the desktop
100
+ login, not over ssh.
101
+ - The floors are unchanged (OATS >=0.52.0, aw >=1.36.33). A deployment
102
+ gets it by pinning `oats.aweb: v1.29.0` and running `oats sync`; only
103
+ new spawns use it. The provider's reference is its
104
+ `docs/health-publisher.md`.
package/docs/servers.md CHANGED
@@ -360,7 +360,10 @@ the host's own facts from its `status --json`: `identity`,
360
360
  `repo` a path on the host. A fact the host does not supply is `null`
361
361
  (an older host, or a saved route the host no longer lists). A row also
362
362
  carries `waitingOnYou` (needs input) when the host's kernel reports it, and
363
- only then: an older host's row has no such key. A removed or edited registration keeps
363
+ only then: an older host's row has no such key. `retire` (0.59.0, a retire
364
+ of the home running, unknown, failed or interrupted) is relayed the same
365
+ way, through the kernel's own read of it, and a value that read refuses is
366
+ dropped ([`retire`](desktop-cli-api.md#row-retire)). A removed or edited registration keeps
364
367
  its group from the saved routes. State is pulled on every call, from every
365
368
  group at once: each probe has its own deadline, `--per-target` (default 20 s)
366
369
  capped by `--budget` (default 45 s, the deadline of the whole answer), and a
@@ -852,6 +852,27 @@ the Git state did not move, or to verify the copy when it did. With nothing
852
852
  preserved before the hooks, nothing is compared: a
853
853
  recovery is written after them whenever there is something to preserve.
854
854
 
855
+ Those reads are the inspection's own where they can be: the walk that takes
856
+ the untracked and ignored digest of the worktree takes its bytes from the
857
+ same read of each file. A directory instance's pre-hook copy is verified by
858
+ reading the copy back and comparing it with the bytes the inspection before
859
+ the hooks read. A file changed before the copy read it refuses the retire
860
+ with `E_WORK_PRESERVATION_FAILED`, before any hook, as does a copy changed
861
+ after it was written. A file changed during the copy, after it was copied, is
862
+ not in the pre-hook copy: the inspection after the hooks reads the work
863
+ again, sees the change, and copies the work again, verified, under
864
+ `after-hooks/`. Every other copy of the work is the last read of its source
865
+ before the home is removed, and it reads the source again after the copy:
866
+ any change since the inspection refuses.
867
+
868
+ Every digest reads its files itself, one at a time, in a fixed order. While
869
+ it reads them, a few worker threads read the files it reads next, so a tree
870
+ that is not in the page cache yet (a copy just made on a file system that
871
+ clones files, a `node_modules/` not read for a while) comes from the cache.
872
+ That changes no digest and no error, and it is bounded: at most four files
873
+ are read at once, each through a 1 MiB buffer, and never more than 64 MiB or
874
+ 4096 files ahead of the digest.
875
+
855
876
  A worktree whose `git status` fails refuses the retire with
856
877
  `E_WORK_INSPECTION_FAILED` at the first inspection: no recovery was written,
857
878
  nothing was deleted, and the retire has not stopped the instance's session.