@awebai/oats 0.52.0 → 0.54.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 (100) hide show
  1. package/README.md +2 -1
  2. package/bin/oats.mjs +314 -92
  3. package/docs/capabilities.md +66 -4
  4. package/docs/configuration.md +66 -3
  5. package/docs/design/2026-09-23-workspace-module-contracts.md +3 -0
  6. package/docs/desktop-cli-api.md +696 -60
  7. package/docs/desktop-instance-start.md +25 -12
  8. package/docs/execution-targets.md +1 -0
  9. package/docs/implementation.md +184 -12
  10. package/docs/integrations.md +6 -3
  11. package/docs/knowledge.md +2 -2
  12. package/docs/macos-test-runs.md +246 -0
  13. package/docs/official-catalog.md +5 -5
  14. package/docs/packages.md +14 -14
  15. package/docs/release-lane.md +210 -6
  16. package/docs/release-notes/v0.53.0.md +1288 -0
  17. package/docs/release-notes/v0.54.0.md +142 -0
  18. package/docs/schedules.md +7 -1
  19. package/docs/souls-and-instances.md +239 -16
  20. package/docs/tui.md +453 -21
  21. package/docs/upgrading.md +310 -0
  22. package/docs/workspaces.md +123 -3
  23. package/lib/automations.mjs +22 -22
  24. package/lib/claim.mjs +93 -4
  25. package/lib/config-data.mjs +4 -1
  26. package/lib/core.mjs +569 -121
  27. package/lib/instance-events.mjs +19 -1
  28. package/lib/instance-git.mjs +39 -3
  29. package/lib/instance-inspect.mjs +5 -6
  30. package/lib/instance-lifecycle.mjs +145 -18
  31. package/lib/instance-resolution.mjs +59 -6
  32. package/lib/launch-preference.mjs +226 -15
  33. package/lib/local-edit.mjs +118 -0
  34. package/lib/packages.mjs +18 -5
  35. package/lib/pi-bridge.mjs +308 -0
  36. package/lib/refused-text.mjs +11 -0
  37. package/lib/remote.mjs +404 -60
  38. package/lib/resolve.mjs +2 -1
  39. package/lib/retained-after-retire.mjs +2 -2
  40. package/lib/retire-output.mjs +12 -1
  41. package/lib/schedule-host.mjs +6 -35
  42. package/lib/shell-word.mjs +13 -0
  43. package/lib/soul-launch-verbs.mjs +153 -0
  44. package/lib/stable-node.mjs +62 -0
  45. package/lib/teams-verbs.mjs +18 -46
  46. package/lib/workspace.mjs +75 -27
  47. package/package-catalog.json +4 -4
  48. package/package.json +2 -1
  49. package/packages/client/attach-exit.mjs +25 -0
  50. package/packages/client/cli-adapter.mjs +16 -3
  51. package/packages/client/cli-locator.mjs +2 -2
  52. package/packages/client/deployment-contract.mjs +4 -0
  53. package/packages/client/deployment-facts.mjs +71 -10
  54. package/packages/client/deployment-panel.mjs +49 -11
  55. package/packages/client/deployment-read-cli.mjs +7 -3
  56. package/packages/client/display-text.mjs +8 -2
  57. package/packages/client/instance-acts.mjs +46 -10
  58. package/packages/client/instance-events-contract.mjs +4 -2
  59. package/packages/client/instance-presentation.mjs +66 -2
  60. package/packages/client/instance-tree.mjs +23 -14
  61. package/packages/client/kernel-lines.mjs +31 -0
  62. package/packages/client/kernel-made.mjs +23 -0
  63. package/packages/client/launch-prompt-outcome.mjs +51 -16
  64. package/packages/client/lifecycle-contract.mjs +45 -4
  65. package/packages/client/liveness.mjs +14 -1
  66. package/packages/client/own-codes.mjs +31 -0
  67. package/packages/client/panel-views.mjs +18 -11
  68. package/packages/client/readiness-contract.mjs +3 -1
  69. package/packages/client/remote-address.mjs +34 -9
  70. package/packages/client/remote-identity-memory.mjs +94 -0
  71. package/packages/client/remote-roster.mjs +92 -6
  72. package/packages/client/session-attach.mjs +175 -0
  73. package/packages/client/spawn-apply-contract.mjs +16 -4
  74. package/packages/client/spawn-messages.mjs +26 -3
  75. package/packages/client/spawn-preview-cli.mjs +8 -2
  76. package/packages/client/spawn-preview-contract.mjs +5 -1
  77. package/packages/client/terminal-exec.mjs +21 -0
  78. package/packages/client/workspace-choices.mjs +95 -0
  79. package/packages/client/workspace-views.mjs +39 -3
  80. package/packages/record/README.md +21 -0
  81. package/packages/record/bin/setup.mjs +108 -15
  82. package/packages/tui/README.md +30 -12
  83. package/packages/tui/lib/actions.mjs +16 -1
  84. package/packages/tui/lib/client.mjs +32 -1
  85. package/packages/tui/lib/config.mjs +151 -0
  86. package/packages/tui/lib/main.mjs +117 -46
  87. package/packages/tui/lib/model.mjs +392 -0
  88. package/packages/tui/lib/read.mjs +473 -0
  89. package/packages/tui/lib/store.mjs +364 -0
  90. package/packages/tui/lib/term/keys.mjs +44 -0
  91. package/packages/tui/lib/term/screen.mjs +16 -4
  92. package/packages/tui/lib/term/text.mjs +60 -0
  93. package/packages/tui/lib/term/tty.mjs +13 -3
  94. package/packages/tui/lib/views/detail.mjs +46 -0
  95. package/packages/tui/lib/views/frame.mjs +230 -36
  96. package/packages/tui/lib/views/help.mjs +125 -13
  97. package/packages/tui/lib/views/instances.mjs +137 -0
  98. package/packages/tui/lib/views/scroll.mjs +19 -0
  99. package/packages/tui/lib/views/switcher.mjs +97 -0
  100. package/skills/oats-getting-started/SKILL.md +8 -2
@@ -0,0 +1,1288 @@
1
+ # OATS 0.53.0
2
+
3
+ 2026-10-13
4
+
5
+ ## Upgrade
6
+
7
+ [Upgrading OATS on a host](../upgrading.md) has the steps that are the same
8
+ for every release: the CLI, then `oats update` in each deployment, then
9
+ `oats doctor`. It also says when a change of Node version leaves something
10
+ to do on a host, and what: restart the instances and, where schedules run,
11
+ install the host timer again; before that, install the CLI again where it is
12
+ installed inside the Node version.
13
+
14
+ - **Where the Desktop is installed, install Desktop 0.53.0 before the CLI
15
+ ([#1107](https://github.com/awebai/oats/issues/1107)).** A 0.52.0 Desktop
16
+ refuses a 0.53.0 CLI and lists no instance until it is replaced. Desktop
17
+ 0.53.0 accepts the older CLI in the meantime. This includes an
18
+ `oats update` whose plan installs the CLI.
19
+
20
+ - **A host that comes from 0.51 or earlier does 0.52.0's
21
+ [Upgrade steps](v0.52.0.md#upgrade) first, in their order.** One of them is
22
+ easy to miss because it is a host tool and not OATS: aw 1.36.33 or later,
23
+ before `oats sync`. The sync to this release's catalog locks oats.aweb
24
+ 1.27.1, which refuses every new spawn below that version. After the sync,
25
+ `oats readiness --soul <name>` shows it as a failed provider check, with
26
+ the install that cures it.
27
+
28
+ - **Once the CLI is 0.53.0, run `oats update` in each deployment that
29
+ launches pi instances.** It now moves the pi bridge in every pi folder that
30
+ deployment's launch configurations name, and `oats doctor` warns about each
31
+ one that is behind
32
+ ([#991](https://github.com/awebai/oats/issues/991)). An `oats update` run
33
+ by 0.52 or earlier moves the bridge of the default pi folder only, so the
34
+ one that upgraded the CLI is not enough.
35
+
36
+ - **Claude Code instances on a Homebrew node: a restart rewrites their
37
+ waiting hooks, and a respawn makes that last
38
+ ([#997](https://github.com/awebai/oats/issues/997)).** A home's hooks in
39
+ `<home>/.claude/settings.json` are written again at every `oats session
40
+ start` and `restart`, by the copy of oats.core in that home, which a start
41
+ does not refresh. A home spawned before the oats.framework that carries
42
+ this fix keeps writing the path of the versioned keg, so it is repaired by
43
+ a restart after each Node upgrade, and gets the lasting path when it is
44
+ respawned. Between a Node upgrade and that restart, such an instance does
45
+ not report that it waits on you. A home spawned with the fixed oats.core
46
+ gets the lasting path at its first start under this kernel, whichever
47
+ kernel spawned it.
48
+
49
+ - **On every host where `oats setup` was run, run `oats setup` once more
50
+ after upgrading the CLI, as the same user
51
+ ([#1003](https://github.com/awebai/oats/issues/1003)).** The capture hooks
52
+ in `~/.claude*/settings.json` and the capture watcher's unit still name the
53
+ `node` that ran the earlier setup, and nothing else rewrites those files:
54
+ no `oats update`, spawn, start or restart. The run replaces its own hooks
55
+ and unit and adds no second one. `oats setup --dry-run` first prints the
56
+ `node` it would record and changes nothing. The same step follows a change
57
+ of Node version wherever the recorded path does not outlast it
58
+ ([Upgrading](../upgrading.md#after-a-change-of-node-version)).
59
+
60
+ A run that prints `already installed` for the watcher's unit has not
61
+ checked that the watcher is enabled
62
+ ([#1099](https://github.com/awebai/oats/issues/1099)). On Linux,
63
+ `systemctl --user is-enabled turn-record-capture.service` says whether it
64
+ is. Where an earlier `oats setup` could not enable it, enable it by hand:
65
+ `systemctl --user enable --now turn-record-capture.service`.
66
+
67
+ - **Existing resident custody units: after updating to oats.aweb 1.27.1, run
68
+ `oats aweb resident create <name>` again from the deployment**, with the same
69
+ `--root` if one was used. An existing unit changes only on that rerun; an
70
+ OATS upgrade or seat restart alone does not refresh it. OATS 0.53.0 supplies
71
+ the kernel-selected Node path; supported older kernels retain the previous
72
+ fallback. If the recorded `aw` path lives inside a Node version that will
73
+ be removed, install aw in the new version and rerun before removing the old
74
+ one. See [the provider's upgrade steps](https://github.com/awebai/oats-aweb/blob/v1.27.1/docs/resident-create.md#after-changing-node-or-aw).
75
+
76
+ - **After upgrading, run `oats doctor`: it lists each key of `souls.launch`
77
+ that matches no soul, with the command that fixes it.** Until then a spawn
78
+ that would fall through is refused and says the same
79
+ (`E_LAUNCH_PREFERENCE_UNMATCHED`, under **Changed** below). This reaches
80
+ scheduled jobs, triggers and agents' own spawns: before 0.53.0 such a key
81
+ was never read.
82
+
83
+ To check before upgrading: every key of `souls.launch` other than `"*"` is
84
+ the name of a soul that `oats souls` lists, bare for a member's soul and
85
+ `<package>/<soul>` for a package's. For a script, on 0.51.0 or 0.52.0:
86
+
87
+ ```
88
+ oats souls --json | node -e 'const r=JSON.parse(require("fs").readFileSync(0,"utf8")).result;const p="oats-local.yaml#/souls/launch/";console.log([...new Set(r.souls.map(s=>s.launch&&s.launch.at).filter(a=>a&&a.startsWith(p)).map(a=>a.slice(p.length).replace(/~1/g,"/").replace(/~0/g,"~")))].sort().join("\n"))'
89
+ ```
90
+
91
+ It prints the keys of `souls.launch` that decide some soul's launch. A key
92
+ in the file that it does not print, other than `"*"`, names no soul.
93
+
94
+ - **A host on 0.52.0 or earlier that is refused with
95
+ `E_REMOTE_UNREADABLE` in a second or two, on a network that is fine, needs
96
+ only this upgrade ([#1059](https://github.com/awebai/oats/issues/1059)).**
97
+ The refusal names the reason `network`, or `auth`, and neither is the
98
+ cause: see Fixed. Installing the CLI goes through npm and not through the
99
+ remote cache, so the fault does not block the upgrade, and the first read
100
+ by 0.53.0 fetches the commit. To run a command on the old kernel before
101
+ that, put three Git variables in front of it, for that command only:
102
+
103
+ ```
104
+ GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=fetch.negotiationAlgorithm GIT_CONFIG_VALUE_0=noop oats sync
105
+ ```
106
+
107
+ The same prefix works on any `oats` command that fetches: a spawn, a
108
+ preview, `oats souls`, `oats workspace status`. Do not run Git inside
109
+ `~/.cache/oats` and do not move a cache entry aside: the old kernel
110
+ rebuilds it and fails the same way. In that state `oats souls` can also
111
+ print its list without a package's souls, with no error and exit 0
112
+ ([#1098](https://github.com/awebai/oats/issues/1098)); `oats souls --json`
113
+ names them in `problems`.
114
+
115
+ - **The official catalog's versions in this release** are oats.framework
116
+ 1.9.4, oats.okf 5.0.3, oats.aweb 1.27.1 and oats.engineering 1.9.1: see
117
+ Provider updates. Pin what your workspace uses, then run `oats sync`.
118
+
119
+ ## Added
120
+
121
+ - **`oats tui` (preview) shows a deployment's instances (#855).** In 0.52 the
122
+ preview drew a frame and read nothing from the kernel. **This version shows
123
+ a workspace's instances, on this machine and on the other machines
124
+ registered on it, and changes nothing.** The list
125
+ is the roster the Desktop draws, with the same groups, order and states,
126
+ from the same code, and it follows the deployment every few seconds. Beside
127
+ it is the detail of the selected instance, with what it needs from you. `/`
128
+ filters by name, soul and repository. **It cannot yet** open an agent's
129
+ terminal, stop, start, restart, retire or spawn one, show souls or
130
+ capabilities, or add, check or remove a machine: its help screen
131
+ names the `oats` command for each. It is still a preview: its screens and its configuration
132
+ file may change without notice. [docs/tui.md](../tui.md) has the rest.
133
+ - **Start it in or under a deployment**, or name one: `oats tui --dir
134
+ <path>`. With no `oats-local.yaml` at or above the start, and, when no
135
+ `--dir` was given, no deployment directly inside `~/Agents` to offer, it
136
+ prints one line (`E_NO_DEPLOYMENT`) and exits 1. Started inside an agent's pane it
137
+ still reads the deployment it was asked about: it removes the instance's
138
+ variables from its own environment first.
139
+ - **It runs the kernel it shipped with**, never an `oats` found on `PATH`,
140
+ and only to read (`oats status` and `oats workspace status`, then a probe
141
+ of the terminals, and `oats server roster` for the other machines). A
142
+ kernel it cannot accept stops the start with
143
+ `E_TUI_KERNEL`. Start it again after upgrading OATS.
144
+ - **Every key can be changed** in `$XDG_CONFIG_HOME/oats/tui.json` (else
145
+ `~/.config/oats/tui.json`). A file it cannot honour stops the start, one
146
+ line per problem (`E_TUI_CONFIG`): it resolves no conflict between two
147
+ actions and guesses nothing.
148
+
149
+ - **`oats soul launch set|remove` writes a soul's launch preference
150
+ ([#990](https://github.com/awebai/oats/issues/990)).** Until now the only
151
+ way to pin a soul to a launch on a machine was to edit `oats-local.yaml`
152
+ `souls.launch` by hand, the edit everyone is told not to make.
153
+
154
+ ```
155
+ oats soul launch set <soul>|'*' (--launch-config <name>|none | --harness pi|claude|codex [--model <id>])
156
+ oats soul launch remove <soul>|'*'|<exact key>
157
+ ```
158
+
159
+ each with `--plan` (every check, nothing written), `--dir <deployment>` and
160
+ `--json`. `set` names the soul as a spawn does and writes the key that soul
161
+ has, so it cannot write a key that names no soul. `remove` also takes the
162
+ exact text of a key in the file, and that form works when the workspace's
163
+ souls cannot be read. Both answer what the next spawn of the soul selects
164
+ and every key of `souls.launch` that still names no soul. **The file is
165
+ rewritten, and every other entry keeps its value and its comments.** A
166
+ client gates on the feature `soul-launch`; the answer is `soulLaunchApi: 1`
167
+ ([docs/desktop-cli-api.md](../desktop-cli-api.md#oats-soul-launch)). New
168
+ code: `E_LAUNCH_PREFERENCE_UNKNOWN`, a `remove` of an entry the file does
169
+ not have. Not in this release: a `list` verb (`oats souls` shows each
170
+ soul's launch), and a lock for `oats launch-config set|remove`, which
171
+ writes the same file without the one this verb and `oats teams` hold
172
+ ([#998](https://github.com/awebai/oats/issues/998)).
173
+
174
+ - **`OATS_NODE_BIN`: the node a capability writes down
175
+ ([#997](https://github.com/awebai/oats/issues/997)).** Every hook, every
176
+ provider check and operation, and every dispatched command now receives
177
+ `OATS_NODE_BIN` beside `OATS_CLI_BIN`: the node to write into anything that
178
+ outlives the process (a harness's settings, a unit, a script). It is the
179
+ node running the kernel, by the rule the host timer's unit already follows
180
+ (#916): the Homebrew `opt` link for a keg, else the same node found on the
181
+ kernel's `PATH`, else the path as it is. A version manager's shim is another
182
+ program, so it is never the answer; with mise the answer is the version's
183
+ own path (measured), and other version managers were not measured. Like
184
+ `OATS_CLI_BIN`, a launch configuration cannot set it and it is not part of
185
+ the environment OATS starts a session with. A capability that must also run
186
+ under an older kernel falls back to `process.execPath` when the variable is
187
+ absent. See [Capabilities](../capabilities.md#the-node-a-hook-writes-down).
188
+ - **When the rule has no stable answer, a spawn and a start say so.** Each
189
+ carries one more line in `warnings`, for every harness: `the node path
190
+ <path> is not stable (no Homebrew opt link and no node on PATH resolves to
191
+ it): what this home's hooks record with it stops working when it goes
192
+ away; install a node with a stable path and restart the instance`. A
193
+ preview carries none. No other answer changes.
194
+
195
+ - **`oats tui` (preview) shows a workspace's other machines, and switches
196
+ between workspaces (#855).** It is still a preview: its screens and its
197
+ configuration file may change without notice, and it still changes
198
+ nothing. **This version adds the instances a workspace runs on the other
199
+ machines registered on this machine**, in the same list as this
200
+ machine's: each deployment under a heading of its own, a machine's
201
+ heading with the time its rows were read. A row of another machine shows
202
+ what its host reported at that time, not what is true at this moment. A
203
+ machine that is not reached keeps its heading and the rows it last
204
+ reported, and they read `unknown`: nothing reads as stopped that is only
205
+ not reached. **`w` opens a switcher of workspaces**: the workspaces this
206
+ run knows, what was matched to no workspace, and the deployments directly
207
+ inside `~/Agents`, which `Enter` opens in the same run. **Started outside
208
+ every deployment, with no `--dir`, it starts with that switcher** when
209
+ `~/Agents` holds a deployment, where it printed the `E_NO_DEPLOYMENT`
210
+ line; with none there, and with a `--dir` that is in no deployment, it
211
+ prints that line and exits 1. It keeps nothing on disk, so a machine it
212
+ has not reached in this run is listed by its own name, in no workspace.
213
+ **It cannot yet** open an agent's terminal (`oats session attach --home
214
+ <home>`), stop one (`oats instance stop <instance>`), start or restart one
215
+ (`oats session start --home <home>`), retire one (`oats retire
216
+ <instance>`), show souls or spawn an agent (`oats souls`, `oats spawn
217
+ <soul>`), show capabilities (`oats capabilities`), add, check or
218
+ remove a machine (`oats server connect`, `oats server check`, `oats server
219
+ remove`), or open from its switcher a deployment outside `~/Agents` (`oats
220
+ tui --dir <path>`): its help screen names the same commands.
221
+ [docs/tui.md](../tui.md) has the rest.
222
+ - **The other machines are one more read**, `oats server roster --json`,
223
+ by the kernel it shipped with. It never holds this machine's rows, one
224
+ runs at a time, and the next begins no sooner than 15 seconds after the
225
+ last one ended unless you ask for it (`r`).
226
+ - **Two new actions can be given other keys** in `tui.json`: `workspaces`
227
+ (`w`) and `open-workspace` (`enter`). A `tui.json` that gives `w` or
228
+ `enter` to another action stops the start, as any key given to two
229
+ actions does (`E_TUI_CONFIG`): give that action of the switcher another
230
+ key, or none.
231
+
232
+ - **A retire plan says as a fact whether `work/` is the instance's own tree
233
+ (#988).** `facts.ownWorktree` in `oats retire --plan --json`, and in the
234
+ fresh plan of an `E_PLAN_STALE` and an `E_CHILDREN_RUNNING` refusal, is a
235
+ boolean: `true` exactly when `work/` is the instance's own work tree, the
236
+ one the retire retains or removes. It is the answer of the reading the
237
+ retire acts on. `facts.workMode` is the record's value, which the
238
+ instance can write, and `facts.work` is an observation through any link,
239
+ so neither says it: a link or a directory of the home under a record that
240
+ says `worktree`, and an attached instance over a tree on another branch,
241
+ have `false`. `defaults.retainWorktree` is unchanged and follows the fact
242
+ today; it is the default of an option, not the place to learn what
243
+ `work/` is. Feature word `retire-plan-own-worktree`: without it the key
244
+ is absent and says nothing. A stop plan does not carry it. The plan's
245
+ revision, notes and text, and the receipt, are unchanged. See [the retire
246
+ plan](../desktop-cli-api.md#retire).
247
+
248
+ ## Changed
249
+
250
+ - **`oats teams add|remove|default` no longer re-wrap a long line of
251
+ `oats-local.yaml`.** These verbs rewrite the file, and a value past 80
252
+ columns elsewhere in it came back folded over two lines. Values are
253
+ unchanged, before and now: only the line breaks differ. The file is now
254
+ written the same way by every verb that shares this write, `oats soul
255
+ launch` included.
256
+
257
+ - **Desktop: a row keeps its roster group under a filter and a collapse**
258
+ ([#971](https://github.com/awebai/oats/issues/971)). A relation group is
259
+ now decided on the whole roster, not on the rows left on screen. With a
260
+ filter, one match out of a group of five is listed under its group's name,
261
+ where it stood under "independent"; the same holds for a query in the
262
+ command palette. With a collapse, a root collapsed over its whole group
263
+ stays under the group's name and at its place, where it moved to
264
+ "independent" at the press and came back on expand, taking the keyboard's
265
+ selected row with it. A group with no row on screen is not drawn, and
266
+ "independent" lists only instances with no relation. A header still counts
267
+ the rows shown under it.
268
+
269
+ - **The Desktop accepts OATS CLIs `>=0.25.8 <0.54.0`.** The compatibility band
270
+ admits 0.53. Upgrade the CLI and the Desktop together: a 0.52.0 Desktop
271
+ refuses a 0.53.0 CLI. No new gate on the band. `oats tui` runs the kernel it
272
+ ships with and is held to the same band.
273
+
274
+ - **Desktop: when a spawn works but Claude Code ignores the channel option,
275
+ Desktop says after the spawn that mail and chat will not wake the instance,
276
+ with what OATS reported (#886).** From 0.52.0 a launched spawn's successful
277
+ answer carries `launchPrompts` in the start's shape. With the status
278
+ `flag-ignored` the spawn worked and the instance has no channel delivery.
279
+ After a Start or Restart the Desktop already said so in a notice; a local
280
+ spawn now shows the same notice, from the same reader. It is shown once per
281
+ spawn, also for a replayed one, beside any other notice of that spawn. While
282
+ another workspace is on screen it is held, and shown on return. A
283
+ `--no-launch` spawn, any other status and an answer without `launchPrompts`
284
+ read as before. A spawn routed to a server shows none.
285
+ - The creation receipt of a local spawn (`spawnCreationReceipt` in
286
+ `packages/client/`, and the apply reply of the Desktop's `/api/spawn`)
287
+ gains the optional key `flagIgnored`: `{reason, warnings, omitted}`. It is
288
+ additive. An older side that does not know the key drops it, and the
289
+ receipt stands.
290
+
291
+ - **Desktop: the notice that Claude Code ignored the channel option shows at
292
+ most 16 of the warnings OATS reported, and at most 4096 characters of them,
293
+ and says how many more there are (#886).** After a Start, a Restart or a
294
+ spawn, the notice's Details hold the warnings of the kernel's answer in the
295
+ order given while both bounds hold, each whole, and with more a last line
296
+ such as "3 more not shown." The cut is by position: no warning is picked,
297
+ matched or dropped by its words. OATS puts its own sentence last, so
298
+ warnings that fill the bound before it leave it out: the notice still says
299
+ what happened, without OATS's own advice on what to check.
300
+
301
+ - **`oats update` and `oats doctor` cover every pi folder of the deployment**
302
+ ([#991](https://github.com/awebai/oats/issues/991)). Until now they read the pi
303
+ bridge (`@awebai/oats-pi`) of `~/.pi/agent` only. A launch configuration
304
+ that sets its own `PI_CODING_AGENT_DIR` has its own folder, so a pi
305
+ instance launched through it kept an old bridge against a new kernel, with
306
+ nothing saying so. Now both look at the default folder, at this shell's
307
+ `PI_CODING_AGENT_DIR`, and at the folder of each pi launch configuration of
308
+ the deployment; two names for one folder are one folder.
309
+ [docs/upgrading.md](../upgrading.md) is the new page that owns this.
310
+ - **`oats doctor` prints one `version skew` warning per folder**, naming
311
+ the folder and why it is looked at (`the default`, `launch configuration
312
+ work`). A folder it cannot look at is a warning too; one that does not
313
+ exist or holds no bridge is not. `oats doctor --json` is unchanged.
314
+ - **`oats update` lists the folders in its plan**, each with the bridge
315
+ found there and what it does: move it, leave it alone, or not touch it,
316
+ with the reason and the command to run there. It does not touch a folder
317
+ it cannot resolve (a `{fromEnv: NAME}` not set where it runs, a path that
318
+ is not absolute), a bridge it cannot read, or a folder named only by
319
+ launch configurations that run their own `executable`: it runs no
320
+ wrapper. It creates no folder and installs no first bridge.
321
+ - **`oats update --dir <deployment>`** names the deployment from anywhere.
322
+ With no deployment at or above the working directory it still moves the
323
+ default folder and this shell's, and its last line says that no launch
324
+ configuration was looked at.
325
+ - The text of the warning and of the plan changed. Nothing in OATS parses
326
+ either.
327
+
328
+ - **Desktop: the rules for other machines and the switcher's words are in
329
+ `packages/client/`.** What an answer of `oats server roster --json` becomes
330
+ when it fails or cannot be read, how a machine that stops answering keeps
331
+ its place in its workspace, and the words the workspace switcher shows for
332
+ a view are now functions in `packages/client/` that keep nothing, where a
333
+ second client can call them. The Desktop shows and stores what it did:
334
+ `/api/panel`, `/api/workspaces`, `remote-identity.json` and every sentence
335
+ are unchanged. The panel's functions there now read no clock at all: a
336
+ remote deployment's panel takes the time of its call.
337
+
338
+ - **Desktop: a deployment the kernel refuses to read says so in the kernel's
339
+ words, attributed.** When `oats status` or `oats workspace status` answers
340
+ with an error, the deployment's line now reads "OATS answered with an error
341
+ (`<code>`). It says: `<message>`", where it read "`<code>`: `<message>`".
342
+ The message is shown as one line, and withheld whole ("[Detail withheld]")
343
+ when it looks like a credential or holds control characters. The Desktop's
344
+ own failures to read a deployment (no compatible CLI, a timeout, an answer
345
+ it cannot read) read as before. `oats tui`, which reads a deployment from
346
+ this version on, shows the same sentence in its notice.
347
+
348
+ - **Desktop: the Spawn dialog says an unmatched launch preference in its own
349
+ words, and quotes OATS under Details**
350
+ ([#1015](https://github.com/awebai/oats/issues/1015)). From 0.53.0 OATS
351
+ refuses a spawn that names no launch while `oats-local.yaml` `souls.launch`
352
+ holds a key that names no soul. The dialog read "OATS couldn't work out this
353
+ soul's defaults. Try again, or see Details.", with OATS's message under
354
+ Details and its fix nowhere. It now reads "This machine's launch
355
+ preferences name a soul this workspace doesn't offer, so OATS won't choose
356
+ a launch for this soul. To spawn now, pick a harness above, or a launch
357
+ configuration in Developer settings. To fix it for every spawn, correct
358
+ the preference (Details)." Details hold the code, then "OATS says:
359
+ `<message>`", then the fix on its own line. Each text is one line and
360
+ whole; one that looks like a credential reads "[Detail withheld]", and
361
+ "OATS says:" then stands before the other.
362
+ - **At a press**, when the key appeared after the dialog had read its
363
+ preview, the notice read "OATS couldn't complete the spawn. Try again, or
364
+ see Details. Nothing was created." It now reads "This machine's launch
365
+ preferences name a soul this workspace doesn't offer, so OATS won't
366
+ choose a launch for this soul. To spawn now, pick a harness or a launch
367
+ configuration for this spawn. To fix it for every spawn, correct the
368
+ preference. Nothing was created.", with the code under its details. A
369
+ dialog still open reads the preview again and shows the first sentence.
370
+ - **Unchanged:** a spawn routed to another machine shows that host's
371
+ refusal as before, and a spawn already sent that OATS then refuses with
372
+ this code still reads as an outcome to check.
373
+ [The spawn dialog](../../packages/desktop/docs/desktop-spawn-preview.md#an-unmatched-launch-preference)
374
+ has the whole of it.
375
+
376
+ - **Desktop: a soul's launch problem says who is speaking**
377
+ ([#1015](https://github.com/awebai/oats/issues/1015)). The soul page and
378
+ the soul panel show a box when a spawn of that soul with no launch chosen
379
+ would be refused: a harness that is not installed, a launch configuration
380
+ that is gone or ambiguous, and from 0.53.0 a launch preference that names
381
+ no soul, which every soul with no entry of its own then carries. The box
382
+ showed OATS's message and its fix as two paragraphs, with no word on whose
383
+ they were. It now starts with the Desktop's own line, "A spawn of this soul
384
+ with no launch chosen would be refused here.", then reads "OATS says:
385
+ `<message>`" and the fix under it, with the code under Details as before.
386
+ Each of OATS's two texts is one line and whole; one that looks like a
387
+ credential reads "[Detail withheld]", and "OATS says:" then stands before
388
+ the other. This is so for every launch problem, not only the new one.
389
+
390
+ - **A pull request writes its release-notes entry in a file of its own**
391
+ ([#1018](https://github.com/awebai/oats/issues/1018)). The entry goes in
392
+ one file under `docs/release-notes/next/` and no longer into the version's
393
+ notes file, so two pull requests that share no code no longer conflict over
394
+ their entries. `node scripts/assemble-release-notes.mjs --tag vX.Y.Z`, run
395
+ in the release-prep pull request, moves the entries into the notes file and
396
+ removes the entry files. **A tag is refused while an entry file exists**,
397
+ by the release workflow and by `scripts/release-lane.mjs build`, before
398
+ anything is built or published.
399
+ [Release-notes entries](../release-lane.md#release-notes-entries) has the
400
+ rule.
401
+
402
+ - **On btrfs, a retire that went through with an empty directory where its
403
+ recovery copies one file is now refused
404
+ ([#1029](https://github.com/awebai/oats/issues/1029)).** With an empty
405
+ directory at `info/attributes`, at the stash's log or at the log of a
406
+ nested repository's branch, `oats retire` completed there. It now answers
407
+ `E_WORK_PRESERVATION_FAILED`, the code every other file system already
408
+ gave for it. On every file system, such a path whose parent directory
409
+ cannot be searched is refused the same way, where it was left out of the
410
+ copy. See the entry under Fixed.
411
+
412
+ - **A retire that was refused for a work tree with no index file now
413
+ completes ([#1048](https://github.com/awebai/oats/issues/1048)).** For an
414
+ instance whose own tree has no index file, `oats retire` answered
415
+ `E_WORK_PRESERVATION_FAILED`, with `--force` and with
416
+ `--discard-worktree` as without them. It now completes and writes a
417
+ recovery whose `repo/` has no index file either. No code, no key of the
418
+ receipt and no warning is new. See the entry under Fixed.
419
+
420
+ - **The `fix` of a launch refusal names `oats soul launch`, not the file**
421
+ ([#1049](https://github.com/awebai/oats/issues/1049)). Three answers still
422
+ told the operator to change `souls.launch` in `oats-local.yaml`, the hand
423
+ edit that `oats soul launch set|remove` replaced: `E_HARNESS_UNAVAILABLE`
424
+ (a harness that is not installed), `E_LAUNCH_CONFIG_UNKNOWN` as a soul's
425
+ `launch.problem`, and `E_LAUNCH_CONFIG_AMBIGUOUS`. Their `fix` now gives the
426
+ command, for example "install codex, or pin this soul to another launch
427
+ (oats soul launch set <soul> --launch-config <name> | --harness <h>)", and
428
+ where `souls.launch."*"` decided the launch it gives the command for `'*'`
429
+ first. The message of `E_HARNESS_UNAVAILABLE` and of
430
+ `E_LAUNCH_CONFIG_AMBIGUOUS` ends with its `fix`, so it changed with it. No
431
+ code, no `details` field and no API version changed. A `fix` is a sentence
432
+ for a person: its wording may change between releases, so a client shows it
433
+ and never parses it
434
+ ([Launch preferences](../desktop-cli-api.md#launch-preferences)). The
435
+ function that renders the command also holds one rule for every text of a
436
+ launch answer: none carries a character the kernel never prints, whatever
437
+ key it is handed
438
+ ([#1064](https://github.com/awebai/oats/issues/1064)). The schema of
439
+ `oats-local.yaml` already admits no such key, so nothing an operator could
440
+ reach changes.
441
+ - **A listing says that a launch would be refused, not that one was**
442
+ ([#1049](https://github.com/awebai/oats/issues/1049)). On `oats souls` and
443
+ `oats inspect --soul`, the `launch.problem` of a soul that
444
+ `E_LAUNCH_PREFERENCE_UNMATCHED` reaches carried the refusal's own sentence
445
+ ("it is refused, and nothing was created or started", then the remedy),
446
+ about a launch nobody had asked for. Its `message` now states the
447
+ condition and ends "it would be refused."; the remedy is its `fix`, as
448
+ before. The refusal a spawn gets is unchanged, and so is the shape of
449
+ `problem`.
450
+
451
+ - **A Git failure the kernel cannot classify reads `unknown`, with Git's own
452
+ line, where it read `network`**
453
+ ([#1059](https://github.com/awebai/oats/issues/1059)). `E_REMOTE_UNREADABLE`
454
+ called every failure it did not recognise `network`, which sent people to
455
+ look at a network that was fine. `details.reason` is now `network` only for
456
+ what Git's text shows to be the network, and `unknown` otherwise; the
457
+ message of an `unknown` failure ends with Git's last line (`cannot read
458
+ remote <url> (unknown): <line>`), one line of at most 300 characters with
459
+ control characters and the user information of any URL removed. No value
460
+ was added to `details.reason` and no field changed
461
+ ([Workspace](../desktop-cli-api.md#workspace)). The Desktop shows "Couldn't
462
+ reach <host>" for `network` and `timeout` only, and the message in full for
463
+ the rest.
464
+
465
+ - **Desktop: the Retire dialog reads from the plan whose tree `work/` is**
466
+ ([#1071](https://github.com/awebai/oats/issues/1071)). The dialog decided
467
+ it from the instance's record, which can disagree with what is at `work/`.
468
+ Under a record that says `worktree`, a link to another instance's tree, or
469
+ a directory of the home, was promised to be kept as a worktree and offered
470
+ for deletion. From a kernel that lists `retire-plan-own-worktree` (0.53.0)
471
+ the dialog reads the plan's `facts.ownWorktree` instead:
472
+ - **The tree is the instance's own and was read:** as before.
473
+ - **It is the instance's own and could not be read** (nothing, or a file,
474
+ is at `work/`, or Git failed): "Keeps its worktree, moved aside, if there
475
+ is one. It couldn't be checked." With **Also delete the worktree**
476
+ checked: "Deletes its worktree, if there is one. It couldn't be checked.",
477
+ and under the choice "Deletes the worktree folder, if there is one, with
478
+ any uncommitted changes (a recovery copy is saved first). It couldn't be
479
+ checked." No branch is named. Before, these sentences promised a tree and
480
+ named the branch of the record.
481
+ - **It is not the instance's own:** "It has no worktree of its own, so no
482
+ worktree is kept or deleted. A tree it links to is not touched." **Also
483
+ delete the worktree** is not offered, and a confirmation that carries it
484
+ is refused before any command: "Only an instance with its own worktree
485
+ can delete it. Review the choice again." When a fresh plan says so while
486
+ the choice is checked, the choice stays so that it can be undone, and no
487
+ warning stands under it.
488
+
489
+ A retire plan from such a kernel that does not carry the key is refused as
490
+ malformed, as every other malformed fact of a plan. A plan relayed from a
491
+ server is read by its host's features, not this computer's. From a kernel
492
+ that does not list the word every sentence stays as before, from the
493
+ record. See [Whose tree `work/` is](../../packages/desktop/docs/desktop-lifecycle-confirmations.md#whose-tree-work-is).
494
+
495
+ - **Desktop: the Retire dialog no longer shows another instance's tree as
496
+ the one being retired.** When the plan says the tree at `work/` is not the
497
+ instance's own (an attached, a checkout or a workspace instance; a link or
498
+ a directory of the home under a record that says `worktree`), Current
499
+ state shows no "Uncommitted work", no "Branch", no sentence about the
500
+ branch it was spawned on and no "Pull request" row, and the dialog makes
501
+ no Git or forge read for one. Those rows described the tree the link leads
502
+ to, which the retire does not touch. From a kernel that does not list
503
+ `retire-plan-own-worktree` these rows stay as before.
504
+
505
+ - **A retire that was refused for a nested repository with no commit now
506
+ completes ([#1078](https://github.com/awebai/oats/issues/1078)).** For an
507
+ instance whose work tree holds a repository whose `HEAD` has no commit,
508
+ `oats retire` answered `E_WORK_PRESERVATION_FAILED`, with `--force` and
509
+ with `--discard-worktree` as without them. It now completes, and the
510
+ recovery holds that repository under the class nested repositories
511
+ already have. No code, no key of the receipt and no warning is new. Where
512
+ such a `HEAD` names no local branch the retire is refused as before, and
513
+ the message is now the kernel's, naming the repository, where it was
514
+ Git's. See the entry under Fixed.
515
+
516
+ - **`oats tui` (preview): an instance's reason says who gave it (#855).**
517
+ In an instance's detail, the reason under `state` was a quote in
518
+ quotation marks that named nobody. It now reads after the words that say
519
+ who gave it: `OATS says: …` for a kernel,
520
+ `oats tui's terminal check says: …` for the check of the terminals, and
521
+ `oats tui's read of other machines says: …` for the read of the other
522
+ machines. A reason whose speaker is not known is still in quotation
523
+ marks. A reason that is withheld is `[withheld]` alone, with no speaker
524
+ in front and no quotation marks. One sentence stands as it is, with
525
+ neither: the one about a session backend OATS no longer has, for an
526
+ instance whose OATS is too old to give its own. It is still a preview:
527
+ its screens and its configuration file may change without notice.
528
+ [docs/tui.md](../tui.md) has the rest.
529
+
530
+ - **A stop whose claim cannot be written reads it instead, and stops (#946).**
531
+ Since 0.52.0 a stop holds the home's claim, so a stop whose claim could
532
+ not be written was refused before it signalled anything
533
+ (`E_LIFECYCLE_FAILED`). A full disk is the likely case, and one of the
534
+ reasons a person presses Stop. Now `oats instance stop --apply`, and it
535
+ alone, reads the claim where it cannot write it, and goes on when nobody
536
+ holds it.
537
+ - **When:** the write fails with `ENOSPC` (the file system is full),
538
+ `EDQUOT` (the quota is spent), `EROFS` (it is read-only), or `EACCES` or
539
+ `EPERM` (the claims directory is not writable by this user). What stops
540
+ this stop from writing there stops a retire or another stop of the same
541
+ user as well. Any other failure is refused as before.
542
+ - **Beside a holder nothing changes:** a retire or a stop that holds the
543
+ claim, a holder whose liveness cannot be read, and a file that is no
544
+ readable claim are answered with the same code, sentence and `details`
545
+ as for a stop that can write, and nothing is signalled. The claim is
546
+ read once more just before the first signal.
547
+ - **It says so.** One line per such target on stderr, in text and in JSON
548
+ mode: `oats: warning: <instance>: stopping without its claim: <lock>
549
+ could not be written (<CODE>), and nobody holds it. A retire or a stop
550
+ of <instance> that starts while this one runs will not see it.` The
551
+ receipt has no new field. Through `--server` the warning does not reach
552
+ the caller, as no warning of a stop does (#952).
553
+ - **The limits.** Nothing on the home shows such a stop, so a retire or a
554
+ stop that starts while it runs and that can write its claim is not
555
+ refused: space freed a moment later, or a process of another user. If
556
+ the warning says `EACCES` or `EPERM`, fix the permissions of the claims
557
+ directory (`<instances>/.oats-retirement/claims`); do not live with the
558
+ warning.
559
+ - **On a full disk** the stop cannot write its own record and receipt
560
+ either. The session is stopped, and that target's row is `ok: false`,
561
+ `E_SESSION_STOP_FAILED`, `… its harness was signalled (SIGTERM) and has
562
+ exited`, `stillRunning: []`: read `stillRunning`. The receipt is not
563
+ stored, so the same key is not replayed: the same apply again answers
564
+ `E_PLAN_STALE`, and with the fresh revision `alreadyIdle`.
565
+ - A retire, and a retire's stop of a recorded child, need their claim as
566
+ before.
567
+ - A claim that could not be written leaves no private file
568
+ (`<lock>.tmp-<pid>-<nonce>`) behind when its write fails after the file
569
+ was created, as on a full disk.
570
+
571
+ [A stop whose claim cannot be written reads it instead](../desktop-cli-api.md#stop-claim-write).
572
+
573
+ - **A scheduled self-retire that does not complete says so, and no longer
574
+ leaves the instance reading as retiring when nothing of its home was
575
+ changed (#954).** `oats retire <instance> --self` only schedules: a
576
+ detached completion runs the retire a few seconds later, with nobody at a
577
+ terminal. A completion that was refused or that failed left its pending
578
+ marker behind, so the instance read `RETIRING` in `oats status`, and `oats
579
+ instance stop --apply` and `oats session start` answered
580
+ `E_INSTANCE_RETIRING`, for a retire that was not happening.
581
+ - **The marker follows how far the retire got.** It stays when a retire
582
+ hook was started or the removal of the home began: the home is owed a
583
+ retire, and `oats retire <instance>` continues. Otherwise the completion
584
+ removes it, and the instance is a stopped or a running instance like
585
+ any other: a start works, and a wake schedule may start it.
586
+ - **The outcome stays, as before:** `.oats-retired-<instance>.json` and
587
+ its log beside the home, listed by `oats status` (`retireFailures`)
588
+ until a retire of the instance completes. Nothing retries by itself.
589
+ - **A new event kind, `retire-refused`,** `data: {code, homeChanged,
590
+ reason}`, written once by such a completion and by nothing else.
591
+ `code` is a kernel code, or `null` for a cleanup that did not finish.
592
+ `reason` is the sentence the retire answered, on one line and at most
593
+ 2048 UTF-16 code units. The row is in the workspace's log. A client
594
+ that does not know the kind reads the row as any unknown kind.
595
+ - **A scheduling that the host held up** for longer than its completion
596
+ waited for it (3 s) made that completion give up: the self-retire did
597
+ not happen, and the marker, written afterwards, stayed. A completion now
598
+ waits for its own scheduling for up to ten minutes, then retires the
599
+ instance. A `--self` whose completion has already ended when the
600
+ marker is written (it was killed, or the ten minutes passed and its
601
+ retire was refused) answers `E_SELF_RETIRE_SCHEDULE_FAILED`, removes
602
+ the marker it wrote, and schedules nothing.
603
+ - **A retire hook of a scheduled self-retire no longer inherits
604
+ `OATS_RETIRE_INTENT`:** the variable is the completion's own input, and
605
+ the completion takes it out of its environment before it runs anything.
606
+ - **Homes already stuck by a completion refused under 0.52.0 or earlier**
607
+ keep their marker. To retire such an instance after all, run `oats
608
+ retire <instance>`. To keep it, no command does this: once the
609
+ completion the marker names is gone (its pid is `completionPid` in the
610
+ marker), remove by hand `.oats-retire-pending-<instance>.json`,
611
+ `.oats-retired-<instance>.json` and `.oats-retired-<instance>.log`
612
+ beside the home. The kernel does not do this for a home whose refusal
613
+ it cannot date.
614
+
615
+ [A completion that does not complete](../souls-and-instances.md#self-retire-not-completed),
616
+ [the `retire-refused` event](../desktop-cli-api.md#retire-refused-event).
617
+
618
+ - **Three answers a client reads are different for some homes, by the fix of
619
+ #962 under Fixed.**
620
+ - A retire plan's `defaults.retainWorktree`. A record with no work mode
621
+ whose `work/` Git confirms is a registered linked worktree has
622
+ `defaults.retainWorktree: true` in its plan, where it was `false`; the
623
+ retire already retained that tree. For a home whose record says
624
+ `worktree` while its spawn's receipt says that no tree was given, a real
625
+ directory at `work/` is a directory of the home, and its plan has
626
+ `defaults.retainWorktree: false` where it was `true`.
627
+ - A refusal's code. A `directory` instance whose record was changed to say
628
+ `worktree` is refused with `E_WORK_INSPECTION_FAILED` (the record
629
+ disagrees with the spawn's receipt) with `--force` as without it; with
630
+ `--force` the code was `E_WORK_PRESERVATION_FAILED`. Nothing is stopped,
631
+ run or removed in either case, as before.
632
+ - `E_NO_WORKTREE` where an enclosing checkout was read. For a real
633
+ directory at `work/` that is not the top level Git names for it, `oats
634
+ instance git` and `oats instance diff` answer `E_NO_WORKTREE`, and a
635
+ stop plan's and a retire plan's `work` is `{observed: false, reason:
636
+ "E_NO_WORKTREE"}`.
637
+
638
+ See [what `work/` is at retire](../souls-and-instances.md#what-work-is-at-retire).
639
+
640
+ - **A retire that was refused for a link at `work/` now completes (#973).**
641
+ For a home whose record says `worktree` and whose `work/` is a symbolic
642
+ link, `oats retire` was refused with `E_WORK_PRESERVATION_FAILED`,
643
+ `--force` included. It now completes, removes no tree, with
644
+ `--discard-worktree` as without it (`retention: null`, `worktreeRemoved:
645
+ false`), and says in the receipt's `warnings` where the link led. Its
646
+ plan has `defaults.retainWorktree: false` where it was `true`, and a plan
647
+ of it read before the upgrade is stale. See the entry under Fixed.
648
+ - **A retire plan no longer gives two notes for a tree that is not the
649
+ instance's own (#973).** The plan of an attached, a checkout or a
650
+ workspace instance gave `N changed and M untracked file(s) would be
651
+ retained with the worktree` and `the worktree is on <branch>, not the
652
+ recorded <branch>` for the tree its link leads to, which the retire
653
+ neither keeps nor moves. Both are now given for the instance's own tree
654
+ alone. `facts.work` is unchanged.
655
+ - **`oats retire` spells what a terminal would act on in a warning
656
+ (#973).** The retire's text (without `--json`) prints each warning of the
657
+ receipt on one line, and a control character (an escape, a newline), a
658
+ line separator or a bidi override in it is spelled `\u{<hex>}`. The text
659
+ of a warning that holds such a character differs from before, a retire
660
+ hook's own warning included; every other warning is printed as it was.
661
+ The JSON does not change: a receipt's strings are what they are.
662
+
663
+ - **Desktop: a roster row's message says who made it**
664
+ ([#982](https://github.com/awebai/oats/issues/982)). A row can carry a
665
+ message it did not get from the Desktop: OATS's own, the Desktop's check of
666
+ the terminals, or the Desktop's read of the other machines. It was shown
667
+ bare, so a sentence from OATS read like the Desktop's. Now its speaker
668
+ stands in front: "OATS says: …", "Desktop's terminal check says: …" or
669
+ "Desktop's read of other machines says: …". This is in the row's tooltip
670
+ and description when it cannot open, in the hover card's Status, in the
671
+ actions menu (its button when the row offers nothing, Start's reason and
672
+ Open in split's reason on a Herdr row) and in the notice when a terminal
673
+ cannot open. A sentence the Desktop writes itself reads as before. Such a
674
+ message is now one line: several lines are shown as one, and a message
675
+ that holds control characters or looks like a credential reads "[Detail
676
+ withheld]", with no speaker in front.
677
+
678
+ - **Desktop: the start dialog says who made the message that stops a
679
+ start.** When an instance's state is not known, the dialog's status showed
680
+ the row's message bare. It now reads "OATS says: …" or "Desktop's terminal
681
+ check says: …", as one line, withheld whole under the same rule.
682
+
683
+ - **Desktop: the context panel's Start says who gave a Herdr row's reason.**
684
+ Its tooltip reads "OATS says: E_HERDR_REMOVED: …" when OATS gave the
685
+ reason, and the Desktop's own sentence, as before, for a row of an older
686
+ OATS.
687
+
688
+ - **Desktop: the overview says who made a Herdr row's reason.** The Terminal
689
+ and Restart tooltips of a Herdr row read "OATS says: …" when OATS gave the
690
+ reason.
691
+
692
+ - **Desktop: the overview's notice of a failed read with no rows puts
693
+ OATS's message after its own sentences.** It read "Roster unavailable:
694
+ `<message>`. No current observation." It now reads "Roster unavailable. No
695
+ current observation. OATS says: `<message>`", the message as one line of
696
+ at most 300 characters, and the announcement reads "Couldn't refresh
697
+ roster. OATS says: `<message>`". A message that is withheld reads "[Detail
698
+ withheld]" in its place with no "OATS says:"; with no message the notice
699
+ is "Roster unavailable. No current observation." When an earlier
700
+ observation is still on screen, "Showing the last observation, not current
701
+ state; actions disabled." stands where "No current observation." does.
702
+ Another machine's message has no speaker and stays inside the sentence,
703
+ as before.
704
+
705
+ - **Desktop: the overview's note over rows kept after a failed read puts
706
+ OATS's message after its own sentence.** It read "Roster unavailable:
707
+ `<message>`. Showing a reported observation, not current state; actions
708
+ disabled." It now reads "Roster unavailable. Showing a reported
709
+ observation, not current state; actions disabled. OATS says:
710
+ `<message>`", the message as one line of at most 300 characters. A
711
+ message that is withheld reads "[Detail withheld]" in its place with no
712
+ "OATS says:"; with no message the note is the Desktop's sentence alone.
713
+ Another machine's message has no speaker and stays inside the sentence,
714
+ as before.
715
+
716
+ - **Desktop: the roster's failure notice says who made the message it
717
+ keeps.** When this computer's deployment could not be read again and its
718
+ last rows are kept, the notice's tooltip and Details, the line of a cache
719
+ problem and, with nothing observed yet, the failed block and its
720
+ announcement now read "OATS says: `<message>`". Another machine's message
721
+ reads as before. Either is one line, withheld whole under the same rule.
722
+
723
+ - **A stale deployment's reason puts OATS's message after the client's
724
+ sentence.** When a deployment's re-read fails and its last rows are kept,
725
+ its reason read "This deployment's last read failed: `<message>`. It shows
726
+ what was last observed.", with the message as it came. It now reads "This
727
+ deployment's last read failed. It shows what was last observed. OATS says:
728
+ `<message>`", the message as one line. A message that holds control
729
+ characters or looks like a credential reads "[Detail withheld]" in its
730
+ place, with no "OATS says:". The Desktop shows the reason on its
731
+ Deployments page and in a deployment's heading; `oats tui` shows the same
732
+ sentence in its notice ([docs/tui.md](../tui.md)).
733
+
734
+ - **A deployment whose re-read failed is stale whatever the failure's
735
+ message holds.** A failure with an empty message read as a live
736
+ deployment: its rows kept their actions and no notice said the read had
737
+ failed. Now the failed read alone decides it. The deployment is `stale`,
738
+ its reason is "This deployment's last read failed. It shows what was last
739
+ observed.", and the Desktop's roster and overview show their failure
740
+ notices and disable the rows' actions, with a message, with none, and
741
+ with one that is withheld.
742
+
743
+ - **`packages/client/`: a text a client shows carries its speaker.** For
744
+ another client of the shared home. A row with a `runtimeError` carries
745
+ `runtimeErrorOrigin` (`kernel`, `terminal-probe` or `roster-read`); a
746
+ reason of `rowReason` and `instanceActs` carries `origin` exactly when its
747
+ sentence is the row's own text, with `unattributed` for a text nobody
748
+ attributed; the entry `failedEntry` keeps carries `errorOrigin: "kernel"`
749
+ beside `error`, and `error` is then always a string. Each is an added,
750
+ optional key. `originLead(origin, terms)`, new on the stable surface,
751
+ answers the words to put in front of such a text. The keys are written by
752
+ the shared home only and are never taken from an answer.
753
+ [Who made a shown text](../../packages/desktop/docs/desktop-deployment-model.md#who-made-a-shown-text)
754
+ has the speakers, their words and which text gets which.
755
+
756
+ - **A `souls.launch` key that names no soul refuses the launches it might
757
+ have pinned** ([#989](https://github.com/awebai/oats/issues/989)). A key
758
+ of `oats-local.yaml` `souls.launch` that is the key of no soul the
759
+ workspace offers (a soul that moved to another package, a misspelled name,
760
+ `<member>/<soul>`) was never read: the soul it was written for ran on
761
+ `souls.launch."*"`, the soul's own `launch:` or the host default, with no
762
+ word. While the file holds such a key, a new launch that names none, of a
763
+ soul with no entry of its own, is now refused with
764
+ `E_LAUNCH_PREFERENCE_UNMATCHED` (`details: {soul, from, at, keys, fix}`,
765
+ `keys` each with the nearest soul keys). The kernel cannot tell which soul
766
+ the key was meant to pin, so it cannot say that this launch is not the one.
767
+ - **Refused:** `oats spawn`, preview and apply, and `oats session
768
+ start|restart --reselect-launch`, before anything is created, stopped or
769
+ started. `--model` alone names no launch.
770
+ - **Unchanged:** a spawn of a soul with its own entry; a launch named with
771
+ `--launch-config` or `--harness`; a plain start or restart of an
772
+ existing home.
773
+ - **The remedy, in this order:** `oats soul launch set <soul>
774
+ --launch-config <name>` (or `--harness <h>`) for the soul the key was
775
+ meant for, then `oats soul launch remove <key>`. Removing first ends the
776
+ refusal and leaves that soul on the fall-through.
777
+ - **Every reader says it.** `oats souls` and `oats inspect --soul` carry it
778
+ as `launch.problem` on each soul a spawn would refuse, and `oats souls`
779
+ lists one `problems` row per key. `oats doctor` lists each key with its
780
+ remedy, from this machine's last read of the souls; a spawn reads the
781
+ workspace itself and is the authority.
782
+ - **A key the kernel could not check refuses nothing**: its member is not
783
+ confirmed, a soul failed to read, or its package is declared and not
784
+ locked. `oats doctor` says so in an information line
785
+ (`launch-preference-unchecked`), which changes no exit status. The key
786
+ of a soul in `souls.disabled` matches. `"*"` is never reported, and no
787
+ configuration key changes.
788
+
789
+ - **`oats launch-config set|remove` and `oats schedule|trigger
790
+ enable|disable` take the lock of `oats-local.yaml`, and answer its two
791
+ codes ([#998](https://github.com/awebai/oats/issues/998)).** Every kernel
792
+ command that rewrites `oats-local.yaml` now does it one way: under
793
+ `<deployment>/.agents/locks/local.lock`, from the file as it is under that
794
+ lock. These four commands can therefore answer what `oats teams` and
795
+ `oats soul launch` already answer: `E_LOCAL_BUSY` (`details: {path,
796
+ lock}`) when the lock is still held after 5 s, and `E_LOCAL_CHANGED`
797
+ (`details: {path}`) when the file kept changing while the edit ran.
798
+ Nothing was written in either case, and the same command can be run
799
+ again. Their other answers are unchanged: the receipts, the codes and the
800
+ texts. `oats launch-config set` reads and judges its arguments and its
801
+ definition before it takes the lock, so when two refusals apply at once,
802
+ that one is now the one answered. The text of `E_LOCAL_BUSY` no longer
803
+ lists commands: it says to remove the lock "if no oats command that edits
804
+ this file is running". See [`oats teams`](../desktop-cli-api.md#oats-teams)
805
+ for what the lock covers.
806
+ - **`oats schedule|trigger enable|disable` replaces an `oats-local.yaml`
807
+ that is a symbolic link ([#998](https://github.com/awebai/oats/issues/998)).**
808
+ A symlinked `oats-local.yaml` is replaced by a regular file with the
809
+ target's permission bits, and the target is left as it was. `oats teams`,
810
+ `oats soul launch` and `oats launch-config` already did so; `oats
811
+ schedule|trigger enable|disable` wrote through the link before. A
812
+ deployment that keeps its local file elsewhere behind a link finds the
813
+ opt-out in the deployment's own file from then on, not in the linked one.
814
+
815
+ ## Fixed
816
+
817
+ - **`oats update` removes nothing it cannot replace**
818
+ ([#852](https://github.com/awebai/oats/issues/852)). It ran `pi uninstall`
819
+ and then `pi install`: run right after a release, the install failed on a
820
+ version the registry did not list yet, and the host was left with no bridge
821
+ at all. Now:
822
+ - **It runs one `pi install` over the installed bridge, and no
823
+ `pi uninstall`.** pi replaces a package it already holds, and an install
824
+ that fails leaves the old one in place.
825
+ - **Before any step, the CLI's own install included, it asks the registry
826
+ for the bridge's exact version**, with npm told to revalidate its cache.
827
+ If the version does not resolve, it stops with nothing changed and says
828
+ to run it again in a few minutes. `--check` does not make this lookup.
829
+ - **A failed step names the folder and the exact step to run again**, says
830
+ what the folder holds now (the old bridge, or none) and lists the folders
831
+ not reached. It stops at the first failure.
832
+ - A pi folder whose path has a space in it is one argument: the steps are
833
+ run as arguments, never as a split line.
834
+ - **`oats retire --plan`: the text no longer reads as if another instance's
835
+ tree were removed (#959).** For an instance with no work tree of its own,
836
+ the plan's `defaults:` line printed `retain worktree false`. For an
837
+ attached instance that read as if its owner's tree were removed. It is
838
+ not. The line now says what is true of the work mode: `no work tree of its
839
+ own (work/ links to its owner's tree and that tree is not touched)` for an
840
+ attached instance, the same of the shared checkout and of the deployment
841
+ directory for a checkout and a workspace instance, and `no work tree
842
+ (work/ is the home's own directory: copied to recovery when not empty and
843
+ then removed with the home)` for a directory instance. A record with no
844
+ work mode says `work mode not recorded`, and one with a work mode the
845
+ kernel does not know says `work mode not known to this kernel`, without
846
+ the value, unless `work/` is the instance's own tree or a real directory
847
+ of the home: the line then says that, whatever the mode (#962). A
848
+ `worktree` instance's line is unchanged (`retain worktree true`), unless
849
+ its `work/` is a link, which the line then says (#973). The rest of the
850
+ line and the plan's JSON are unchanged too: `defaults.retainWorktree` is
851
+ the default of one option, whether the instance's own work tree is
852
+ retained, and is `true` only when `work/` is that tree: in `worktree`
853
+ mode unless `work/` is a link (#973), and for a record with no work mode
854
+ whose `work/` Git confirms is a registered linked worktree (#962). See
855
+ [the retire plan](../desktop-cli-api.md#retire).
856
+
857
+ - **`oats teams add|remove|default` and `oats soul launch set|remove` write
858
+ an `oats-local.yaml` that is JSON.** The kernel reads a file that opens
859
+ with `{` as strict JSON. A `teams` write to such a file ended in a decoder
860
+ error with no answer, and nothing was written. Both verbs now write it
861
+ back as JSON: the keys keep their order, the final newline stays as it
862
+ was, and the indentation becomes two spaces. A rewrite the kernel could
863
+ not read back is refused (`E_WORKSPACE_SCHEMA`) and nothing is written.
864
+
865
+ - **A Claude Code instance on a Homebrew node keeps reporting that it waits on
866
+ you after `brew upgrade node`
867
+ ([#997](https://github.com/awebai/oats/issues/997)).** oats.core wrote the
868
+ path of the node its hook ran under into the waiting hooks of
869
+ `<home>/.claude/settings.json`. On Homebrew that is the versioned keg
870
+ (`…/Cellar/node/<version>/bin/node`), which an upgrade removes: every hook
871
+ of a live home then called a node that was gone, and failed without a
872
+ word, so the Desktop and `oats status` no longer showed the instance as
873
+ waiting. **oats.core now writes `OATS_NODE_BIN`**, which on Homebrew is the
874
+ `opt` link that an upgrade repoints. It is also the kernel's own node, where
875
+ the hook's could be another one found first on `PATH`. It needs this kernel
876
+ and the oats.framework that carries the change; under an older kernel the
877
+ same oats.core writes what it wrote before. For homes that already exist,
878
+ see Upgrade above.
879
+
880
+ - **`oats update` moves forward only, and checks what the registry answers
881
+ before it uses it**
882
+ ([#1011](https://github.com/awebai/oats/issues/1011)).
883
+ - **It proposed a downgrade.** From a CLI ahead of the version npm lists (a
884
+ checkout, a build not published yet), the plan held
885
+ `npm install -g @awebai/oats@<the older version>`, and `--yes` ran it. A
886
+ bridge ahead of that version was moved back the same way. Now the CLI is
887
+ installed only when npm lists a newer version, one line says when the
888
+ installed one is ahead, and a bridge ahead of the version the CLI has
889
+ after the run is left alone. `oats doctor` still warns about such a
890
+ bridge, and says what ends the skew instead of "run `oats update`".
891
+ - **What `npm view` printed went into the steps and onto the screen as it
892
+ came.** Now each of the two lookups must answer one version and nothing
893
+ else. Any other answer stops the update before any step, with nothing
894
+ changed, and the message shows it cut short, with its control characters
895
+ made visible. npm's error output of a lookup is shown the same way, never
896
+ as it came.
897
+ - **A pi folder named only by launch configurations with different
898
+ executables** got a by-hand command with the first one's executable. Now
899
+ the plan prints one command per executable, with the configurations it
900
+ is for.
901
+
902
+ - **`oats setup` records a `node` that survives an upgrade of Node, and
903
+ quotes what it writes
904
+ ([#1003](https://github.com/awebai/oats/issues/1003)).** It wrote the path
905
+ of the `node` it ran under into the capture hooks of every
906
+ `~/.claude*/settings.json` and into the capture watcher's unit. On Homebrew
907
+ that is the versioned keg, which `brew upgrade node` removes: the hooks
908
+ then failed at every stop of every Claude Code session of that user, and
909
+ launchd or systemd kept restarting a watcher that could not start. Now:
910
+ - **It records the path the kernel hands every hook (`OATS_NODE_BIN`):** on
911
+ Homebrew the `opt` link, else a `node` on `PATH` that is the same file,
912
+ else the path as it is.
913
+ - **When there is no stable path it says so,** once, a dry run included:
914
+ the capture hooks and the watcher stop when that `node` goes away, and
915
+ `oats setup` is to be run again after installing a `node` with a stable
916
+ path.
917
+ - **Each path is quoted for what reads it:** a shell word in the hook's
918
+ command, systemd's quoting in `ExecStart`, XML text in the launchd plist.
919
+ A `node` or an install under a path with a space in it no longer splits.
920
+ A path of plain characters is written as before.
921
+ - **A hook is taken for setup's own only when the whole command reads as
922
+ one plain command of its shape.** A command that also carries a second
923
+ command, an operator or a redirection was overwritten, and that part
924
+ lost. It is now left as it is, and setup's hook is added beside it.
925
+ - `turn-record setup`, run without the kernel, records the `node` it runs
926
+ under, as before, with the same quoting.
927
+ - For installs that already exist, see Upgrade above.
928
+
929
+ - **A retire no longer keeps a clean extra tree for a Git operation that has
930
+ ended ([#1008](https://github.com/awebai/oats/issues/1008)).** Git leaves
931
+ `REBASE_HEAD` behind a rebase that stopped on a conflict and was continued,
932
+ and `AUTO_MERGE` or `MERGE_MSG` behind others. A retire read each as "an
933
+ operation is in progress", so the tree stayed on the host under
934
+ `.agents/worktrees/` with its branch. A retire now reads what `git status`
935
+ reads: an open rebase, `git am`, merge, cherry-pick, revert or bisect keeps
936
+ the tree as before, and a tree that holds only such leftovers is removed,
937
+ its branch kept. The recovery of an instance's own worktree and `oats
938
+ doctor` use the same answer.
939
+ [What counts](../souls-and-instances.md#git-operation-in-progress).
940
+
941
+ - **Desktop: the fix OATS sends with a refused preview reaches the Spawn
942
+ dialog** ([#1015](https://github.com/awebai/oats/issues/1015)). When OATS
943
+ refuses the preview of a spawn it may send, beside its message, a fix: what
944
+ to do about it. The Desktop's reader of the CLI's answer kept the code and
945
+ the message and dropped the fix, so no fix reached the dialog from an
946
+ installed OATS. It now keeps the fix beside OATS's own message, as one
947
+ printable line of at most 1,024 characters, and nothing else of the
948
+ refusal's details. What a person sees differently today is in one place:
949
+ the three lines under Details for an unmatched launch preference (under
950
+ Changed) are read from it. A harness that is not installed reads as it did,
951
+ since OATS's message for it already holds its fix.
952
+
953
+ - **Whether a retire refuses no longer depends on the file system
954
+ ([#1029](https://github.com/awebai/oats/issues/1029)).** A recovery copies
955
+ the index, `info/attributes`, the stash's log and a nested repository's
956
+ reflogs each as one file. With an empty directory at one of the last three
957
+ the copy failed on most file systems and the retire refused, but on btrfs
958
+ it wrote an empty file and the retire went through. Nothing was lost
959
+ there: an empty directory at such a path holds nothing that Git reads. A
960
+ retire now looks before it copies and refuses on every file system with
961
+ `E_WORK_PRESERVATION_FAILED`, naming the path and what is there. A link
962
+ at such a path is still followed, as Git follows it.
963
+ [The rule](../souls-and-instances.md#copied-as-one-file).
964
+
965
+ - **An instance whose work tree has no index file can be retired
966
+ ([#1048](https://github.com/awebai/oats/issues/1048)).** A tree made by
967
+ `git worktree add --no-checkout`, or one whose index file was removed,
968
+ reads to Git as a tree whose index lists nothing: every committed file is
969
+ a staged deletion. A retire copies such a tree, as any tree that holds
970
+ work, and the copy refused it: it copies the index as one file, and none
971
+ was there. The instance could not be retired until someone ran
972
+ `git reset` in its tree. The recovery now carries "no index" as no index:
973
+ its `repo/` has no index file, and Git reads it as it read the tree, file
974
+ for file. The same holds for a nested repository that has a commit and no
975
+ index file. `git reset` in the recovery makes an index from `HEAD`. An
976
+ extra tree with no index file was never refused: a retire re-homes it as
977
+ it is, as before.
978
+ [The rule](../souls-and-instances.md#no-index-file).
979
+
980
+ - **A commit is fetched into the remote cache whatever the cache already
981
+ holds** ([#1059](https://github.com/awebai/oats/issues/1059)). A spawn, a
982
+ preview, `oats souls` or `oats workspace status` could fail with
983
+ `E_REMOTE_UNREADABLE … (network)` in a second or two, every time, on a
984
+ network that was fine: the fetch of a pinned package's commit, or of a
985
+ member's new head, into a cache that held another commit of the same
986
+ repository. It needed one file under 64 KiB at the wanted commit whose
987
+ version at a commit the cache held was over 64 KiB, which a file that grows
988
+ or is split produces in any repository. Git then received a pack it could
989
+ not complete and the fetch died; a cache in that state could stay in it, and
990
+ a deleted cache came back to it. The kernel now makes that fetch once more,
991
+ whole, and it succeeds. Nothing needs to be done on a host that was
992
+ affected: the next read fetches the commit.
993
+ - **The pack of a fetch that failed no longer stays in the cache for good**
994
+ ([#1059](https://github.com/awebai/oats/issues/1059)). Each failed fetch
995
+ left a temporary pack file in the cache's object store, which nothing
996
+ removed; a host that retried for an hour held dozens. Every fetch into a
997
+ cache now first removes the temporary files there that are older than the
998
+ longest fetch (11 minutes). It goes by age and not at once, because a file
999
+ that appeared during a fetch cannot be told from one another Git process
1000
+ is still writing.
1001
+
1002
+ - **A work tree that holds a repository with no commit can be retired
1003
+ ([#1078](https://github.com/awebai/oats/issues/1078)).** `git init` in a
1004
+ directory of the work, and no commit in it, was enough to make an
1005
+ instance impossible to retire: the copy of a nested repository read the
1006
+ commit at its `HEAD` before anything else, and that `HEAD` has none. The
1007
+ same held after `git switch --orphan` in a repository that has commits.
1008
+ The recovery now rebuilds such a repository as any other: its `HEAD` is on
1009
+ the same branch with no commit, its other branches, their commits and
1010
+ their logs are there, and its index, what is staged in it and its files
1011
+ are the source's. A `HEAD` with no commit that names no local branch (a
1012
+ ref outside `refs/heads/`, or a branch whose name is not UTF-8) is still
1013
+ refused: a commit there, or `git switch -c <branch>`, makes the work tree
1014
+ retirable.
1015
+ [The rule](../souls-and-instances.md#nested-no-commit).
1016
+
1017
+ - **`oats retire`: a real directory at `work/` is no longer removed without
1018
+ a copy, and is no longer read as a work tree (#962).** A retire decided
1019
+ that an instance had a work tree of its own from any real directory at
1020
+ `<home>/work`, whatever the work mode. For a home that was given a link
1021
+ (an attached, a checkout or a workspace instance) or whose record held no
1022
+ work mode, most retires then refused, and two shapes lost what the
1023
+ directory held: under a record that named no repository, a directory that
1024
+ was a Git repository of its own, or the registered worktree of a spawn
1025
+ that had not finished, was removed with the home and nothing of it was
1026
+ copied. What `work/` is now comes from one reading, which the retire and
1027
+ its plan share:
1028
+ - A real directory that is not the instance's own tree is a directory of
1029
+ the home. The retire copies it to recovery (`workRecovery.path/work`,
1030
+ class `directory work bytes`), checks the copy, and removes it with the
1031
+ home, a `.git` in it included. It is never moved or removed through
1032
+ Git. Three refusals of such a home are now a completed retire with a
1033
+ recovery copy. An entry the copy cannot take (a FIFO, a socket) still
1034
+ refuses before anything is touched.
1035
+ - The instance's own tree is retained as before, under a record with no
1036
+ work mode too when Git confirms that `work/` is a registered linked
1037
+ worktree (its plan's default is under Changed). When the record names no
1038
+ repository, the retire uses the one Git names for the tree, does not
1039
+ write it into the record, and says so in the plan's note and the
1040
+ receipt's `warnings`.
1041
+ What such a tree holds uncommitted is copied to recovery as a `worktree`
1042
+ instance's is. An own tree with no repository at all is refused
1043
+ (`E_WORK_PRESERVATION_FAILED`, nothing stopped, run or removed) and
1044
+ never removed with the home.
1045
+ - A registered worktree that is a directory of the home leaves its entry
1046
+ in its repository until a prune: the receipt's `warnings` name the
1047
+ repository and the command, and its branch and commits are untouched.
1048
+ - The plan's notes and its text's `defaults:` line say the above. No key
1049
+ of the plan or of the receipt is new, and no code.
1050
+ - The plan of a `directory` instance whose `work/` is a Git repository of
1051
+ its own no longer has the note `N changed and M untracked file(s) would
1052
+ be retained with the worktree`: nothing of it is retained. Its bytes are
1053
+ copied to recovery and removed with the home, as the plan's recovery
1054
+ note and its text's `defaults:` line say. The plan's `facts.work` for
1055
+ that home is unchanged.
1056
+
1057
+ See [what `work/` is at retire](../souls-and-instances.md#what-work-is-at-retire).
1058
+ - **`oats instance git` and the plans no longer read an enclosing checkout
1059
+ as an instance's work (#962).** Git answers for any directory inside a
1060
+ work tree, so a plain `work/` in a home whose deployment directory is a
1061
+ Git checkout was reported with that checkout's branch and files. A real
1062
+ directory at `work/` is now the instance's work tree only when it is the
1063
+ top level Git names for it (what is answered otherwise is under Changed).
1064
+ The rule is the path, in every work mode. A `directory` instance in such a
1065
+ deployment has no work tree observed (its retire is unchanged: its bytes
1066
+ are copied to recovery and removed with the home); one whose `work/` is
1067
+ the top level of a repository of its own is observed as before. A `work/`
1068
+ that is a link is read as what it leads to, as before: a `workspace`
1069
+ instance's deployment directory included.
1070
+
1071
+ - **A stop on a full disk leaves no private file in the home (#963).**
1072
+ `oats instance stop --apply` writes its record (`.oats-stop.json`) and the
1073
+ receipt of its key (`.oats-stop-receipt.<key>.json`) through a private file
1074
+ beside each, renamed into place. On a file system with no space the private
1075
+ file was created, its write failed, and nothing removed it: the home kept
1076
+ `.oats-stop.json.tmp-<pid>` and `.oats-stop-receipt.<key>.json.<pid>.tmp`,
1077
+ both empty, and one more of the second for each later apply. Both writers
1078
+ now remove their private file when the write or the rename fails. The error
1079
+ is the one they gave before, and so is the receipt: its row for such a stop
1080
+ is unchanged. An upgrade does not remove the files an earlier version left
1081
+ in a home.
1082
+
1083
+ The record's writer is shared: an `instance.json` or a restart record that
1084
+ cannot be written leaves no `<name>.tmp-<pid>` beside it either.
1085
+ - **The text of a stop no longer says that something is still running when
1086
+ nothing is (#963).** A stop that is not `ok` closed its text with `some
1087
+ targets are still running; nothing was escalated`, also under a row that
1088
+ said `its harness was signalled (SIGTERM) and has exited`: a stop on a full
1089
+ disk, which stops the session and cannot write its record. The closing
1090
+ sentence is now chosen from the rows'
1091
+ [`stillRunning`](../desktop-cli-api.md#still-running), as a client reads
1092
+ them. It is the sentence above when a row that is not `ok` names a process
1093
+ or establishes nothing (`null`, or no `stillRunning`), and `the stop did
1094
+ not complete its record; nothing is still running` when every such row
1095
+ says `[]`. The exit status is 1 in both cases, as before, and the JSON
1096
+ receipt is unchanged.
1097
+
1098
+ See [a stop whose claim cannot be written](../desktop-cli-api.md#stop-claim-write).
1099
+
1100
+ - **`oats retire`: a link at `work/` is never the instance's own tree
1101
+ (#973).** For anything at `<home>/work` that was not a real directory, a
1102
+ retire went by the record's work mode. A home whose record said `worktree`
1103
+ and whose `work/` was a symbolic link was then read as holding the
1104
+ instance's own tree: its plan said `defaults.retainWorktree: true`, and
1105
+ its retire was refused (`E_WORK_PRESERVATION_FAILED`) by a comparison
1106
+ written for something else. Nothing was lost, by accident. The record is
1107
+ a file the instance can write; what the link leads to is not the
1108
+ instance's. Now a link is a link, whatever the record says:
1109
+ - The plan of such a home has `defaults.retainWorktree: false`, the note
1110
+ `the record says work mode worktree, but work/ is a link and not a work
1111
+ tree of the instance's own: the retire removes the link with the home
1112
+ and does not touch what it leads to, with --discard-worktree as well`
1113
+ (a plan takes no option, so the note names the flag), and in its text's
1114
+ `defaults:`
1115
+ line `no work tree of its own (work/ is a link, though the record says
1116
+ worktree: what it leads to is not touched)`. Its `planRevision` binds
1117
+ it: a plan read by an older kernel, or while `work/` was the instance's
1118
+ own tree, is stale.
1119
+ - The retire completes, with every flag (it was refused: see Changed):
1120
+ the link goes with the home, and what it led to is not copied, moved,
1121
+ removed or read through Git, and no branch is deleted. The receipt's `warnings` say where the link led
1122
+ (`<home>/work was a link though the record says work mode worktree:
1123
+ nothing was retained or removed as a work tree, and what it led to
1124
+ (<path>) was not touched`), or that it led nowhere that could be read.
1125
+ The receipt holds the path as the system gave it; the retire's text
1126
+ spells a character a terminal would act on (see Changed).
1127
+ A registered worktree that was moved elsewhere, with a link left in its
1128
+ place, stays registered in its repository.
1129
+ - A link at `work/` that is a directory or a file by the time the retire
1130
+ inspects the home again after its hooks refuses the retire
1131
+ (`E_WORK_INSPECTION_FAILED`) and keeps the home, in every work mode:
1132
+ the home's removal would have taken what replaced the link, uncopied.
1133
+ The message says what is there now and how it ends: for a directory,
1134
+ that `oats retire <instance> --plan` shows what a retire would do with
1135
+ it and that running the retire again does that; for a file, or an entry
1136
+ that is neither a link, a directory nor a file, that no retire removes
1137
+ it, and to move it out of the home or remove it, then run the retire
1138
+ again; for an entry that cannot be read, that the retire reads it again
1139
+ when it is run again.
1140
+ - The two notes about a worktree that is retained are given for the
1141
+ instance's own tree alone (see Changed).
1142
+ - No key of the plan or of the receipt is new, and no code. A `worktree`
1143
+ record whose `work/` is gone, or is a file, answers as before.
1144
+
1145
+ See [what `work/` is at retire](../souls-and-instances.md#what-work-is-at-retire).
1146
+
1147
+ - **One long text with no space no longer slows the Desktop and the TUI
1148
+ ([#976](https://github.com/awebai/oats/issues/976)).** Both show the
1149
+ kernel's free text through one filter, which withholds a text that looks
1150
+ like a credential. Its check for a URL with credentials took time that grew
1151
+ with the square of a run of letters: one 8192-letter message with no space
1152
+ cost from a tenth of a second to most of a second each time it was shown,
1153
+ depending on the machine, in the Desktop on each render and in the TUI on
1154
+ each paint. The check now takes time that grows with the length of the
1155
+ text: the same message takes about a millisecond or less. The filters of
1156
+ the readiness view and of an instance's activity had the same check and
1157
+ take the same fix. **What is withheld and what is shown are the same as
1158
+ before.**
1159
+
1160
+ - **Two commands that rewrite `oats-local.yaml` no longer drop each other's
1161
+ change ([#998](https://github.com/awebai/oats/issues/998)).** `oats
1162
+ launch-config set|remove` read the file when it started and wrote it back
1163
+ without the file's lock, and `oats schedule|trigger enable|disable` took no
1164
+ lock either. Either could overwrite what `oats teams`, `oats soul launch`
1165
+ or the other had written in between: a team, a soul's launch preference, a
1166
+ launch configuration or an opt-out was gone, with no error. All of them
1167
+ now write under one lock, each from the file as it is then.
1168
+ - **`oats schedule|trigger enable|disable` of a workspace item writes
1169
+ `oats-local.yaml` whole, and leaves its long lines alone
1170
+ ([#998](https://github.com/awebai/oats/issues/998)).** The file was written
1171
+ in place, so a command killed during the write could leave half of it; it
1172
+ is now written beside and renamed in. A line longer than 80 columns
1173
+ elsewhere in the file was folded onto several lines by the write, and
1174
+ stays as written now. A deployment whose `oats-local.yaml` is written as
1175
+ JSON could not opt out at all (the command failed with
1176
+ `invalid-declaration` and wrote nothing): the opt-out is now written, and
1177
+ the file stays JSON.
1178
+ - **A kernel command that rewrites `oats-local.yaml` keeps the file's
1179
+ permission bits ([#998](https://github.com/awebai/oats/issues/998)).**
1180
+ `oats teams`, `oats soul launch` and `oats launch-config set|remove`
1181
+ replace the file by a rename, and the new file got the bits the process's
1182
+ umask gives: a file its operator had made private (`0600`) came back
1183
+ readable by others (`0644` under the usual umask). The new file now has
1184
+ the bits of the one it replaces, from before its first byte is written.
1185
+ `oats schedule|trigger enable|disable` keeps them too, as it did when it
1186
+ wrote in place.
1187
+
1188
+ ## Removed
1189
+
1190
+ - **Desktop: the Spawn dialog's sentence for `E_REQUIREMENT_INACTIVE` is gone**
1191
+ ([#1047](https://github.com/awebai/oats/issues/1047)). No OATS from 0.26.0
1192
+ raises this code, and with an older OATS on this computer the Desktop reads
1193
+ no deployment and lists no soul to spawn. The two keys for the code leave
1194
+ the shared home.
1195
+
1196
+ ## Provider updates
1197
+
1198
+ - **oats.okf 5.0.3: installing the host timer is the operator's step in
1199
+ `okf-trigger-setup` (awebai/oats-okf#73, awebai/oats-okf#74).** The agent checks with
1200
+ `oats schedule host status` and hands a missing timer's install command to
1201
+ the operator, to run in their own terminal from the deployment directory
1202
+ and outside every instance home. It checks status again after installation
1203
+ and reports what is waiting if no operator is present. The agent must not
1204
+ install the timer or offer its own `--print` output as a preview. The
1205
+ generated mirror and package pins move together to the released tag;
1206
+ compatibility remains OATS >=0.29.0.
1207
+
1208
+ - **oats.framework: installing the host timer is the operator's step in the
1209
+ `oats-automations` and `oats-onboarding` skills (#967).** Both skills had the
1210
+ agent run `oats schedule host install`. The unit records the `PATH` and the
1211
+ node of the shell that installs it, and an agent's shell can carry a
1212
+ session's own. The skills now have the agent hand the operator the exact
1213
+ command, with the flags they want, to run in their own terminal, outside
1214
+ every instance home, and check the result afterwards with
1215
+ `oats schedule host status`. Until the operator runs it, the timer stays as
1216
+ it is. The skills' other schedule and trigger steps are unchanged.
1217
+
1218
+ - **oats.engineering 1.9.1: the reviewer's spawn line, and retire before you
1219
+ remove a worktree**
1220
+ ([oats-engineering#13](https://github.com/awebai/oats-engineering/pull/13)).
1221
+ The official catalog, the reference workspace and the generated mirrors
1222
+ (`mirrors/oats-developer`, `mirrors/oats-code-review`,
1223
+ `mirrors/oats-engineering-expert`, `mirrors/oats-maintainer`) take published
1224
+ `v1.9.1` at `bb420197329b3a88251b06ab67fb4af0b082f67d`; each mirror's tree
1225
+ equals the tag's. Only `oats.developer`'s instructions change; the other
1226
+ three capabilities only change version. What a developer now does:
1227
+ - **It spawns its reviewer with `--parent "$OATS_INSTANCE"` and
1228
+ `--repo <repository>`**, for `<home>/work` and for an extra worktree
1229
+ alike. `<repository>` is the absolute path of the clone the worktree
1230
+ belongs to. Without the two flags, OATS up to 0.52.0 refuses an attached
1231
+ spawn on an extra worktree (`<home>/.work-<purpose>`) twice, first for the
1232
+ repository and then for the owner
1233
+ ([#958](https://github.com/awebai/oats/issues/958)).
1234
+ - **It retires every instance attached to a worktree before it removes the
1235
+ worktree.** The usual case is the reviewer. Removed first, the worktree
1236
+ leaves that instance with a work link to a path that is gone
1237
+ ([#964](https://github.com/awebai/oats/issues/964)).
1238
+ - **A worktree an instance is attached to stays until that instance is
1239
+ retired.** A developer still removes its other extra worktrees before it
1240
+ hands back; the reviewer and its worktree go after the expert accepts.
1241
+
1242
+ The requirement is unchanged: OATS 0.30.0 or later. These instructions are
1243
+ right on OATS 0.52.0 and stay right with #958 and #964; the package depends
1244
+ on neither. Running instances keep what they were spawned with; new spawns
1245
+ pick 1.9.1 up after `oats sync`.
1246
+
1247
+ - **oats.aweb 1.27.1** fixes resident custody-unit conflicts and Node paths
1248
+ ([#111](https://github.com/awebai/oats-aweb/issues/111),
1249
+ [#112](https://github.com/awebai/oats-aweb/issues/112)). `resident create`
1250
+ refuses recognised same-root units under another label before writing and
1251
+ names the unit and platform retirement steps. Running-custody errors name a
1252
+ recognised foreign unit when found, or tell the operator to stop the outside
1253
+ supervisor. Discovery remains `ai.aweb.custody.<namespace>.<resident-name>`;
1254
+ the command never adopts or removes a foreign unit.
1255
+ The unit PATH uses the kernel's absolute `OATS_NODE_BIN` (available from
1256
+ OATS 0.53.0), keeping the previous fallback on older supported kernels.
1257
+ After updating the provider, rerun `oats aweb resident create <name>` from
1258
+ the deployment, with the original `--root` if used, to refresh an existing
1259
+ unit. The selected absolute `aw` path still needs reinstalling and refreshing
1260
+ if it lives inside a Node version that will be removed.
1261
+ OATS >=0.52.0 and aw >=1.36.33 remain the floors. The catalog, reference
1262
+ workspace and generated mirror take the same published tag.
1263
+
1264
+ - **oats.framework 1.9.4: oats.core 2.5.3, oats.setup 2.5.2.** One change to
1265
+ oats.core's hook script and instruction text in three oats.setup skills; no
1266
+ schema or provider contract changes, and the capability floors are
1267
+ unchanged (oats.core `>=0.40.0`, oats.setup `>=0.30.0`).
1268
+ - oats.core's hook writes into a Claude Code home's waiting hooks the node
1269
+ the kernel hands it (`OATS_NODE_BIN`, from OATS 0.53.0), a path that
1270
+ survives a Node upgrade. Under an older kernel, which does not set the
1271
+ variable, it writes its own process's node as before
1272
+ ([#997](https://github.com/awebai/oats/issues/997)).
1273
+ - `oats-automations` and `oats-onboarding` (oats.setup): installing the host
1274
+ timer is the operator's step, as the entry above says
1275
+ ([#967](https://github.com/awebai/oats/issues/967)); `oats-onboarding`
1276
+ names oats.okf 5.0.3.
1277
+ - `oats-workspace-config` (oats.setup) says that from OATS 0.53.0
1278
+ `souls.launch` is written by `oats soul launch set` and
1279
+ `oats soul launch remove`
1280
+ ([#990](https://github.com/awebai/oats/issues/990)), and lists
1281
+ `E_LAUNCH_PREFERENCE_UNKNOWN`, `E_LAUNCH_PREFERENCE_UNMATCHED`
1282
+ ([#989](https://github.com/awebai/oats/issues/989),
1283
+ [#1049](https://github.com/awebai/oats/issues/1049)) and `E_LOCAL_BUSY`
1284
+ with `E_LOCAL_CHANGED`
1285
+ ([#998](https://github.com/awebai/oats/issues/998)), each with its remedy.
1286
+ The remedies of `E_HARNESS_UNAVAILABLE` and `E_LAUNCH_CONFIG_UNKNOWN` now
1287
+ name `oats soul launch set`, from OATS 0.53.0; on an older kernel the
1288
+ remedy is still to edit `souls.launch` in `oats-local.yaml`.