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