@awebai/oats 0.47.0 → 0.49.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 (44) hide show
  1. package/bin/oats.mjs +293 -41
  2. package/docs/capabilities.md +264 -8
  3. package/docs/capability-manifest.schema.json +18 -5
  4. package/docs/configuration.md +7 -1
  5. package/docs/desktop-cli-api.md +439 -40
  6. package/docs/desktop.md +72 -5
  7. package/docs/execution-targets.md +19 -1
  8. package/docs/implementation.md +81 -1
  9. package/docs/integrations.md +7 -5
  10. package/docs/knowledge.md +167 -197
  11. package/docs/official-catalog.md +6 -5
  12. package/docs/packages.md +14 -14
  13. package/docs/release-notes/v0.48.0.md +106 -0
  14. package/docs/release-notes/v0.49.0.md +770 -0
  15. package/docs/schedules.md +62 -39
  16. package/docs/servers.md +7 -0
  17. package/docs/souls-and-instances.md +395 -52
  18. package/docs/workspaces.md +18 -3
  19. package/injects/work-checkout.md +17 -11
  20. package/injects/work-worktree.md +19 -13
  21. package/lib/capability-contract.mjs +100 -11
  22. package/lib/capability-show.mjs +5 -2
  23. package/lib/core.mjs +1147 -319
  24. package/lib/instance-events.mjs +6 -3
  25. package/lib/instance-git.mjs +11 -5
  26. package/lib/instance-inspect.mjs +14 -3
  27. package/lib/instance-lifecycle.mjs +106 -16
  28. package/lib/instance-resolution.mjs +15 -3
  29. package/lib/launch-prompt-policy.mjs +17 -3
  30. package/lib/packages.mjs +1 -0
  31. package/lib/real-path.mjs +27 -0
  32. package/lib/resolve.mjs +4 -4
  33. package/lib/retire-output.mjs +6 -1
  34. package/lib/schedule.mjs +1 -0
  35. package/lib/servers.mjs +32 -6
  36. package/lib/teams-verbs.mjs +40 -9
  37. package/lib/tree-copy.mjs +18 -7
  38. package/lib/triggers.mjs +201 -65
  39. package/lib/workspace.mjs +20 -5
  40. package/lib/worktree-hooks.mjs +392 -0
  41. package/lib/worktree.mjs +655 -0
  42. package/package-catalog.json +12 -5
  43. package/package.json +1 -1
  44. package/skills/oats-getting-started/SKILL.md +1 -1
@@ -0,0 +1,770 @@
1
+ # OATS 0.49.0
2
+
3
+ 2026-10-09
4
+
5
+ ## Capabilities set up the Git trees the kernel creates (#796)
6
+
7
+ - **Capabilities can set up the Git trees the kernel creates: the
8
+ `worktree` hook event, feature `worktree-event` (#796).** A capability
9
+ manifest may declare `hooks.worktree`, as a command string or
10
+ `{ command, required }`. It fires once for `./work` of a `work: worktree`
11
+ spawn (after the spawn hooks succeed, inside the spawn's transaction) and
12
+ once for each tree `oats worktree add` makes. It never fires for another
13
+ work mode, for a tree made with raw Git, or at start, restart, resume or
14
+ retire. It runs differently from other hooks, which are unchanged:
15
+ - its cwd is the new tree, stdin is `/dev/null` and it has no terminal;
16
+ - it runs detached, in its own process group, with a fixed 30-minute
17
+ timeout that ends the whole group;
18
+ - its output goes to `<home>/.oats/logs/worktree-<purpose|work>-<cap>.log`
19
+ (0600, truncated per run), and on `oats worktree add` also to stderr,
20
+ never stdout (a caller that closes its pipes only stops that copy: the
21
+ add completes); receipts, records, markers and events carry the log's path
22
+ only, never its content;
23
+ - the result is the exit status; of its last JSON line only `warning` is
24
+ read, and `env` is a contract error.
25
+
26
+ `required: true` is now valid on `spawn` and `worktree`. A required
27
+ `worktree` hook that fails or times out fails the spawn through the
28
+ existing rollback, or makes `oats worktree add` remove the tree and delete
29
+ the branch while it is still where `add` created it. A spawn's rollback
30
+ deletes the home that held the hook's log, so its answer names no log path
31
+ (`details.hooks[].log` is `null`); `add` keeps its logs. A non-required one
32
+ warns, and the tree is kept. The kernel runs only the hooks of the
33
+ instance's own capabilities: no file in the repository is run or trusted.
34
+ See [capabilities.md](../capabilities.md#the-worktree-event).
35
+
36
+ - **The hook environment of the event.** Besides the standard hook variables,
37
+ a `worktree` hook gets `OATS_TREE`, `OATS_TREE_CLONE`, `OATS_TREE_REMOTE`,
38
+ `OATS_TREE_MEMBER`, `OATS_BRANCH`, `OATS_TREE_BASE`, `OATS_TREE_BASE_OID`,
39
+ `OATS_PURPOSE` (empty for `./work`) and `OATS_TREE_ORIGIN` (`spawn` or
40
+ `add`). `OATS_TREE_REMOTE` is `origin`'s URL without credentials: a
41
+ URL-style remote loses its whole userinfo, an scp-style remote its `user@`.
42
+ Only that form is ever recorded, printed, logged or passed on. The
43
+ environment is otherwise inherited from whoever ran the command (inside a
44
+ session, the session's own); the kernel adds no credentials.
45
+
46
+ - **`oats worktree add|remove`: extra trees made by the kernel.** From an
47
+ instance home, `oats worktree add --purpose <p> --branch <b> --base
48
+ <remote-branch> [--repo <member key|clone path>] [--preview] [--json]` makes
49
+ `<home>/.work-<p>` with the same three Git steps the work-mode briefing
50
+ taught (the clone's refs are not moved), fires the `worktree` hooks, records
51
+ `<home>/.oats/trees/<p>.json` and appends a `worktree-added` instance event.
52
+ Run again with the same arguments, it does nothing (`resumed: true`). An
53
+ interrupted `add` rolls back; one killed outright leaves its record, and the
54
+ next `add` or `remove` of that purpose completes the rollback. A rollback
55
+ deletes the branch only when that `add` created it, no worktree has it
56
+ checked out, and it still points where `add` created it. Otherwise the
57
+ branch is kept and the answer says why (`branchKept`, `branchKeptReason`).
58
+ Commands on one purpose are serialized by a claim,
59
+ `<home>/.oats/trees/<p>.lock`. A claim left by a killed command is taken
60
+ over by the next one once its holder is verified gone, and any git step
61
+ the killed command left running is ended before the next one acts.
62
+ `oats worktree remove --purpose <p>` runs `git worktree remove`, which
63
+ refuses a tree with uncommitted work, keeps the branch and fires no hook. A tree `add` made is
64
+ an ordinary extra tree to retirement. The `worktree` and `checkout`
65
+ briefings and `/oats-operate` now teach these commands in place of the raw
66
+ Git recipe, and tell agents that `add` may take minutes where a capability
67
+ sets up the tree. New spawns get the new briefing.
68
+
69
+ - **Two error codes.** `E_INTERRUPTED`: SIGINT, SIGTERM or SIGHUP during
70
+ `oats worktree add`'s hooks or a spawn's `worktree` hooks; the kernel ends
71
+ the hook's process group, rolls back and exits 128 + the signal number.
72
+ `E_WORKTREE_DIRTY`: `oats worktree remove` on a tree Git refuses as dirty,
73
+ with Git's message; the record is kept. Commit and push, or discard, then
74
+ retry. `add` otherwise reuses existing codes (`E_BRANCH_EXISTS`,
75
+ `E_PLACEMENT_TAKEN`, `E_LIFECYCLE_BUSY`, `E_CLONE_MISSING`,
76
+ `E_CLONE_MISMATCH`, `E_REMOTE_UNREADABLE`, `E_BASE_UNKNOWN`,
77
+ `E_GIT_FAILED`, `E_REQUIRED_HOOK_FAILED`, `E_HOOK_ENVIRONMENT_CONTRACT`, `E_BAD_ARGS`,
78
+ `E_INSTANCE_RETIRING`).
79
+
80
+ - **Additive JSON fields.** `spawn --preview` has a top-level `worktreeHooks`:
81
+ `[{capability, required}]` for a `worktree` spawn, `null` for every other
82
+ mode (the `worktree` path string is unchanged); the text preview prints
83
+ `worktree hooks: …` or `worktree hooks: none`. The spawn result and the
84
+ `spawned` event carry `worktreeHooks` (the hooks' receipt) only when
85
+ `worktree` hooks ran. A spawn running its `worktree` hooks holds the
86
+ quarantine marker `.oats-rollback-incomplete.json` with a new optional
87
+ `inProgress: {pid, processStart, startedAt, branch, baseOid, hookPgid?, hookStart?}`; while
88
+ that process is verifiably alive, its `oats status --json` row carries
89
+ `spawnInProgress: true` and no `rollbackIncomplete`, and `oats retire`
90
+ refuses with `E_LIFECYCLE_BUSY`. Whether a process exists is the operating
91
+ system's answer (`kill -0`), on every host; only then is its start read,
92
+ from `/proc`, or with `ps` in a fixed `LC_ALL=C`, `TZ=UTC` environment
93
+ (macOS). A start
94
+ that cannot be read is never taken for gone, nor shown in progress: the row
95
+ carries `rollbackIncomplete` (its `inProgress` names the pid), and retire refuses, naming the pid and `oats retire
96
+ <instance> --force`, which then keeps the branch. Once it is gone, `oats retire` ends the
97
+ hook process group it left and completes the rollback (below). It
98
+ signals that group only while the group's leader runs with its recorded
99
+ start time. A group whose leader has exited is never signalled, and a
100
+ warning names it. A group with members whose leader's start cannot be
101
+ read is not signalled either: retire refuses, naming the group and
102
+ `oats retire <instance> --force`, and so do `oats worktree add` and
103
+ `remove` for a hook or git step an interrupted command left. A new instance
104
+ event kind, `worktree-added`. See
105
+ [desktop-cli-api.md](../desktop-cli-api.md#oats-worktree).
106
+
107
+ - **One exception to "no retire deletes a branch".** When a spawn was
108
+ killed (SIGKILL, or its rollback cut short) while its `worktree` hooks ran,
109
+ its marker's `inProgress` records the branch and the commit the spawn
110
+ created it at (`inProgress.branch`, `inProgress.baseOid`). Once that
111
+ process is verified dead, `oats retire` ends the leftover hook process
112
+ group, runs the retire hooks, removes the worktree and verifies the
113
+ removal, and only then deletes the branch with an atomic compare-and-delete
114
+ (`git update-ref -d refs/heads/<b> <baseOid>`), finishing the spawn's own
115
+ compensation. A branch still at its creation commit holds no work. If the
116
+ tip moved, the branch is checked out in any worktree, or the ref cannot be
117
+ read, the branch is kept and the retry stays incomplete with the usual
118
+ "branch left" item naming it (the home is kept). Every other quarantine
119
+ keeps its branch. The retire result keeps `branchDeleted: false` and
120
+ reports the step in an additive `spawnCompensation`: `{branch,
121
+ branchDeleted: true}` or `{branch, branchDeleted: false, reason}`, present
122
+ only when the step was reached.
123
+
124
+ - **Limit: spawns from triggers and schedules.** A trigger or schedule spawn
125
+ still runs as a child with a 5-minute timeout, which does not change. A
126
+ `work: worktree` soul with a slow `worktree` hook is supported from a tick
127
+ only if the whole spawn finishes in that time; otherwise the child gets
128
+ SIGTERM, rolls back, and the tick records a failure.
129
+
130
+ - **Adopting the event.** A kernel before 0.49.0 refuses a manifest that
131
+ declares `hooks.worktree`, and with it the whole capability. In order:
132
+ 1. Upgrade the kernel on every host that composes the capability.
133
+ 2. Only then declare `hooks.worktree`, with `compatibility.oats:
134
+ ">=0.49.0"`, so an older host refuses with `E_CAPABILITY_INCOMPATIBLE`
135
+ naming the release, not with a schema error.
136
+ 3. The blast radius is every soul that composes the capability, on every
137
+ host below the release, as in lfx-oats-workspace#22, where one
138
+ capability took down every developer soul.
139
+ 4. To limit it, put the hook in a small capability composed only by the
140
+ souls that need the setup.
141
+ 5. Declare it `required` when the tree is unusable without the setup.
142
+
143
+ ## oats.okf 5.0: proposals at checkpoints, not a harvest engine
144
+
145
+ 0.48.1 was not released on its own: the oats.okf 5.0 pin it described ships
146
+ in 0.49.0, and its notes are these two sections.
147
+
148
+ The official catalog and reference workspace pin oats.okf 5.0.0. Working
149
+ instances update their notes at important checkpoints, write their own
150
+ proposal, and directly spawn `oats.okf/knowledge-harvester`. The harvester
151
+ checks the actual source, accepted knowledge and open/recent harvest PRs,
152
+ then opens a normal Git PR for maintainer review. No host harvest setting,
153
+ scheduled harvest jobs, source capture/worker/drain machinery or automatic
154
+ retirement harvest remains. Transcripts are not a default input.
155
+
156
+ The sole opt-out is in the soul: `knowledge: { harvest: off }`. Consultation
157
+ still works, no checkpoint-harvest direction is given, and the harvester
158
+ refuses that source in its required spawn hook. Directory bases remain
159
+ consultable, but harvesting requires a Git base with a reviewed PR path.
160
+
161
+ ## oats.okf 5.0 cutover — order matters
162
+
163
+ 1. **While still using oats.okf 4.2, finish or explicitly dispose of any
164
+ registered 4.x sources.** Settle active harvesters and held drains, and
165
+ decide the disposition of remaining private inputs and open PRs. Do not
166
+ silently delete or re-import old custody. A registered old source retired
167
+ after the pin can refuse with `E_HARVEST_CONSENT_UNKNOWN` and retain its
168
+ home; finish that old-provider work before changing the pin.
169
+ 2. **Pin and sync oats.okf 5.0.0**, using the deployment's normal reviewed
170
+ package update and approval process. This makes the new administration
171
+ command available; it does not replace modules in running homes.
172
+ 3. **Before any new spawn, remove explicit legacy host settings** using the
173
+ new, guard-exempt command, from the deployment directory and with a soul
174
+ that selects oats.okf:
175
+
176
+ ```sh
177
+ oats okf setup --remove-legacy-settings --soul <soul> --plan --json
178
+ oats okf setup --remove-legacy-settings --soul <soul> --json
179
+ ```
180
+
181
+ The plan writes nothing. Applying removes only the explicit host keys
182
+ `settings.oats.okf.harvest`, `harvest-runtime` and `harvest-model`, keeps
183
+ the file's permissions, and never changes the soul opt-out. Unsupported
184
+ YAML shapes refuse without writing; report them to the deployment owner.
185
+ **Between steps 2 and 3, a new spawn with those old host keys refuses
186
+ with `E_REMOVED`; the refusal names this cleanup command as the fix.**
187
+ The cleanup command did not exist in 4.2: it cannot run before step 2.
188
+ 4. **Respawn homes that should propose knowledge.** Existing homes keep
189
+ their copied modules, skills and briefings; their own commands, hooks and
190
+ checks still run those old modules. A source record with an explicit
191
+ host-origin legacy key continues to be refused by the 5.0 harvester even
192
+ after host cleanup, until the source is respawned. A recorded 4.x
193
+ `manifest-default` is nobody's decision and is ignored by the 5.0 reader;
194
+ it alone does not require respawn, but the new proposal briefing does.
195
+
196
+ A proposal must contain exactly one `Source: instance <name>, home <path>,
197
+ soul <name>` line naming an actual recorded source. Spawn the harvester with
198
+ `--relation unrelated` alone, never with `--relative-to`; source-pair
199
+ consistency does not establish proposer authorship. Claims are untrusted
200
+ data and enter commit/PR message files, not shell command text.
201
+
202
+ This package pin changes no production kernel contract. Package mirrors are
203
+ generated from the exact pinned payload; the clean-room and provider-facing
204
+ tests exercise the 5.0 contract rather than restoring removed 4.x machinery.
205
+
206
+ ## Added
207
+
208
+ - **Remote roster groups carry each host's kernel features, feature
209
+ `server-probe-features`.** `oats status --json` now has a top-level
210
+ `features`: the running kernel's own list, the same array as
211
+ `oats version --json` `features` (emitted at output time, never from a
212
+ reused `--max-age` observation; the human output is unchanged). `oats server
213
+ roster --json` relays it from the status answer it already pulls, as each
214
+ group's `probe.features`, so the Desktop can tell what a host supports
215
+ without probing it: no extra ssh, no `version --json`, nothing stored. The
216
+ host's answer is untrusted and is relayed only as an array of at most 256
217
+ entries, each a string of at most 64 characters matching
218
+ `^[a-z0-9]+(?:-[a-z0-9]+)*$`, in the host's order, duplicates kept;
219
+ anything else, even one bad entry, is `null` (never a filtered list). `null`
220
+ means unknown; `[]` is a valid answer, not unknown. A failed probe stays
221
+ `{ok: false, error}` with no `features` key. A host before 0.49.0 answers no
222
+ `features`, so its group reads `null`: a false negative for a host running
223
+ 0.46.0 to 0.48.0, whose `version --json` does advertise, for example,
224
+ `soul-composed-instructions`. Its features are unknown until it runs
225
+ 0.49.0.
226
+
227
+ - **Desktop: a spawn whose capabilities set up its worktree finishes, and every
228
+ outcome is reported for what it is (#802, feature `worktree-event`).** A
229
+ `worktree` hook can run for up to 30 minutes, but the Desktop ended every
230
+ spawn after 60 s, which made the kernel roll it back, and then reported
231
+ "Outcome unknown". Now the deadline comes from the preview the operator
232
+ confirmed (60 s, plus 30 minutes per hook and 60 s), the request answers
233
+ within 50 s and the Desktop follows the spawn until it settles, and up to 4
234
+ spawns run at once (one per workspace and soul). The spawn dialog's
235
+ **Setup** fact names the capabilities that will set up the worktree. A
236
+ spawn that was interrupted, or whose required hook failed, reads as rolled
237
+ back with nothing created, and one whose cleanup was owed says to retire it.
238
+ The roster shows a spawn running its hooks as **Setting up worktree…** with
239
+ no actions, a home whose spawn or retire didn't finish as **Spawn didn't
240
+ finish** or **Retire didn't finish** with only **Retire instance…**; the
241
+ retire result names a branch an interrupted spawn left, and the events list
242
+ gains **Worktree added**. A server spawn whose worktree hooks take more than
243
+ about a minute is not yet supported from the Desktop: use the CLI on the
244
+ server.
245
+
246
+ - **What to do with what a retire leaves behind (#703, part 1).** A new
247
+ section, [After a retire: inspect, restore,
248
+ dispose](../souls-and-instances.md#after-a-retire-inspect-restore-dispose),
249
+ says what a recovery copy's `recovery.json` records (`phase`, `classes`,
250
+ `afterHooks`), how to inspect one (`git -C <recovery>/repo status` and
251
+ `log`, the copied home and outputs), how to restore from it (fetch the
252
+ branch from the recovery's clone into the source repository under a new
253
+ name, or copy files back) and how to remove one by hand; how to list and
254
+ remove a retained worktree under `<deployment>/.agents/worktrees/`; and
255
+ that the `retired` event keeps the recovery's path. The retire summary's
256
+ recovery block ends with a line pointing to it. Nothing in the receipt or
257
+ the plan changes, and nothing removes a recovery or a retained worktree
258
+ for you.
259
+
260
+ - **Desktop: a soul's page shows its instructions.** A new **Instructions**
261
+ section, after Capabilities, reads the soul's own `AGENTS.md` the way a
262
+ capability's page reads its injected instructions: a navigation tree, then
263
+ the file with its front matter as a table, its Markdown rendered strictly and
264
+ its code highlighted. The path shown is the file's place in the soul's
265
+ repository. It comes from the page's existing inspection (no new CLI call),
266
+ and **Refresh** keeps the selection, focus and scroll position. The capability
267
+ page's Contents and this section now share one reader and one keyboard model.
268
+ With OATS 0.46.0 or later, the section also shows the soul's composed
269
+ `AGENTS.md`, what a new instance spawned here would be given: the soul's own
270
+ text, then each part OATS and its capabilities inject, each headed with where
271
+ it comes from and its file, with **Open capability** on a capability's part
272
+ and **Copy composed AGENTS.md** for the exact file. The page asks for it
273
+ (`oats inspect --soul … --instructions`) only when the installed OATS
274
+ supports it. For a soul on another machine (a server workspace), the page
275
+ asks only when that server supports it, as the server reports in the remote
276
+ roster (`probe.features`, feature `server-probe-features`): a server that
277
+ reports nothing (older than 0.49.0, or not reached) shows only the soul's own
278
+ `AGENTS.md`. The Desktop decides from the roster it already reads; it never
279
+ probes a server for this.
280
+ - **Desktop: capability warnings and the new trigger fields are shown
281
+ (#802).** A capability that declares a hook event this kernel does not run
282
+ (`hook-event-unsupported`) now shows a **Warnings** list, in the kernel's
283
+ own words, on the capability page, the soul page, readiness, the instance
284
+ Soul tab, the spawn preview and Workspace › Sources. Each warning is marked
285
+ by the word "Warning" and an icon, keeps its code and path under
286
+ **Details**, and, on the soul page, in readiness and in Sources, has **Open
287
+ capability**. A warning blocks nothing and changes no ready state or count;
288
+ past 32, the list says how many more. A trigger's page now shows its last
289
+ poll, the events waiting (newest first), the instances live now, and its
290
+ last error with its code; events are named by their `subject`. Its **Test**
291
+ card shows the instance each event would spawn and says when the name was
292
+ shortened to fit. An older kernel sends none of these, and the pages read as before.
293
+
294
+ ## Changed
295
+
296
+ - **The Desktop accepts OATS CLIs `>=0.25.8 <0.50.0`.** The compatibility band
297
+ admits 0.49; existing feature gates remain unchanged.
298
+
299
+ - **Trigger events carry `subject` (#669).** Events carry `subject` (a PR's
300
+ number); `perKey` counts by subject; added to the event file,
301
+ `instance.json.trigger` and `trigger status`/`test`. `subject` is a string:
302
+ `"42"` for PR 42. The keys are added beside the existing ones, and
303
+ `triggerApi` stays 1: `trigger status` rows in `pending[]`, `fired[]` and
304
+ `live[]`, `lastRun` in `trigger list`/`show`, and `trigger test`'s
305
+ `wouldFire[]` (with `instance` and `nameCut`). A home spawned before 0.49.0
306
+ has no `subject` in its record and still counts toward `perKey` by its PR's
307
+ repo and number; a pending event an older kernel recorded is given its
308
+ number as `subject` when it is read. See
309
+ [desktop-cli-api.md](../desktop-cli-api.md).
310
+
311
+ - **Desktop: identity marks show two letters.** Soul, capability and workspace
312
+ marks used the name's first letter, so every `oats-…` soul read "O". A mark
313
+ now drops a package qualifier and, from three words, a leading namespace
314
+ word, then takes two words' initials or a one-word name's first two letters:
315
+ `oats-desktop-expert` is DE, `oats-okf--knowledge-harvester` KH, `oats.aweb`
316
+ OA. Colours are unchanged, and the mark stays decorative beside the name.
317
+ Where marks stack (a capability's *Used by*, a team's members), they now
318
+ overlap by 1px, so no letter hides under the next mark.
319
+ - **A capability that declares a hook event this kernel does not run still
320
+ composes (lfx-oats-workspace#22).** Until now an unknown event in `hooks`
321
+ dropped the whole capability from discovery, and every soul composing it
322
+ stopped on that host. From 0.49.0, an unknown event declared as a command,
323
+ `{ command }` or `{ command, required: false }` is ignored and never runs;
324
+ the capability composes and carries the warning `hook-event-unsupported`
325
+ (`capability <id> declares hook "<event>", which this kernel does not
326
+ run`). The warning appears, in JSON and in text, in `oats sync`, `oats
327
+ workspace status`, `oats capabilities show`, `oats inspect`, `oats
328
+ readiness` and `oats doctor`, each in a `warnings` array (new, and always
329
+ present, in `capabilities show`, `inspect` and `readiness`; new in
330
+ `doctor --json`), and as its message in the `warnings` strings of `oats
331
+ spawn --preview` and `oats spawn`. Doctor without `--soul` reads the
332
+ deployment's capabilities from this machine's cache, and names what it
333
+ could not check (`hook-events-unchecked`). `oats capabilities` lists only
334
+ the hook events this kernel runs. An unknown event declared
335
+ `required: true` is still refused, exactly as before, since skipping a hook
336
+ its author declared essential would fail open. The tolerance covers the
337
+ event's name only: a malformed declaration (no or empty command, an unknown
338
+ key, a non-boolean `required`, a script outside the capability) is refused
339
+ as for a known event. Approved events are unchanged.
340
+ `docs/capability-manifest.schema.json` accepts additional `hooks` keys with
341
+ the same value shape. The limit: it helps from this release on only.
342
+ Kernels before 0.49.0 still refuse every unknown event, so a capability
343
+ that must load on them declares only the events they run.
344
+ - The text form of `oats spawn --preview` now prints its `warnings`
345
+ (`WARNING: …`), including the launch-prompt notice that was JSON-only
346
+ before.
347
+ - **`oats spawn --json`: a required spawn-hook failure answers its typed
348
+ code, no longer `E_SPAWN_FAILED`.** A required `spawn` hook that fails
349
+ used to answer `E_SPAWN_FAILED`, with no details. It now answers
350
+ `E_REQUIRED_HOOK_FAILED`, or `E_HOOK_ENVIRONMENT_CONTRACT` when the hook
351
+ answered an `env` outside its contract, with `details.hooks` (the hooks'
352
+ receipt, paths only), as a required `worktree` hook's failure does.
353
+ Anyone matching `E_SPAWN_FAILED` for that case must update.
354
+ `details.unconfirmed: true` still means the rollback could not confirm the
355
+ spawn's effects; `details` never carries `home`. See
356
+ [desktop-cli-api.md](../desktop-cli-api.md).
357
+ - **The release-workflow test no longer runs the Desktop suite nested inside
358
+ a root shard.** `test/release-workflow.test.mjs` ran Desktop's `npm test`
359
+ as a third, unsharded copy of a suite that already runs twice; it used
360
+ about 270 s of its 300 s budget and timed out on trees where every test it
361
+ reached passed. It now checks that the Desktop scripts the release invokes
362
+ exist. The Desktop suite's release gate is the `desktop-standalone` CI job,
363
+ which runs the release's `npm ci && npm test` inside `packages/desktop`, and
364
+ the root shards also run it. The failure-message helper from #644 (also
365
+ reported as #750 and #794) stays for any nested `node --test` run.
366
+
367
+ - **A detached checkout or attached spawn records no branch, never `"HEAD"`
368
+ (#641).** `oats spawn` of a checkout or attached instance whose tree is on
369
+ a detached HEAD, or on a branch whose name is not valid UTF-8, records
370
+ `branch: null` in `instance.json`, where it recorded the word `"HEAD"`
371
+ (or the name with replacement characters). The Desktop now sees `branch:
372
+ null` instead of `"HEAD"` for such a new spawn in `oats status --json` and
373
+ in the spawn result. A home spawned earlier may still record `"HEAD"`:
374
+ `oats instance git` reports it as `recorded.branch: null` with `drift:
375
+ false`, and the retire plan's `facts.recordedBranch` is `null`, so neither
376
+ the plan's notes nor the Desktop's Remove dialog say any more that the
377
+ worktree is "not the branch it was spawned on (HEAD)". See
378
+ [desktop-cli-api.md](../desktop-cli-api.md#instancejson).
379
+
380
+ ## Fixed
381
+
382
+ - **Desktop: the bundled server ends with the app that started it (#698).**
383
+ On Linux, quitting or upgrading Desktop could leave the old app's server
384
+ (`server/oats-web.mjs start --port 4820`) running in the old app's
385
+ `app-…scope`, still answering on 4820 with the old version, while the new
386
+ app served from 4821. The app stopped its server only at the end of a
387
+ clean quit, so a crash, a kill or a failure earlier in the quit left it
388
+ running. Now the app starts its server with its stdin as a pipe that only
389
+ the app holds, and the server exits as soon as that pipe closes, which the
390
+ operating system does when the app ends by any path. A server started by
391
+ hand is unchanged. CLI commands the server is running when it exits get no
392
+ signal and finish, as on a normal quit. The startup log also names the
393
+ case: a server of this app at another version on the port is reported with
394
+ the version found, this app's version, and that it was not started by this
395
+ app and is left running, then the port this app uses instead (it was
396
+ reported as "not the requested workspace"). The app never stops a server
397
+ it did not start. **One-time cleanup:** a server left running by an
398
+ earlier Desktop does not have this tie and stays until it is stopped once
399
+ by hand: stop the process listening on 4820 (Linux: `ss -ltnp 'sport =
400
+ :4820'`, or `systemctl --user stop` its `app-…scope`; macOS: `lsof
401
+ -iTCP:4820 -sTCP:LISTEN`), then restart Desktop. See the Troubleshooting
402
+ table in [desktop.md](../desktop.md#troubleshooting).
403
+
404
+ - **Desktop: a deployment attached to a workspace identity matches its own
405
+ server (#807).** Desktop decides whether a running server serves its
406
+ workspaces by comparing each workspace's directory with the views the server
407
+ lists. An attached deployment is listed under its workspace's id
408
+ (`ws:<hash>`), with its path among the view's deployments, and only the id
409
+ was compared. So a server of the same version serving that deployment was
410
+ not reused (logged as "not the requested workspace") and a second one
411
+ started. If the attach was observed before the app's new server first
412
+ answered, startup could also stop with "spawned backend serves … does not
413
+ cover …". A directory now matches a view when it is, or lies under, the
414
+ view's id or one of its deployments.
415
+
416
+ - **Desktop: the soul page's Teams card shows a server's refusal as the
417
+ context panel does (#680).** For an instance on a registered server, a
418
+ refusal of listing, refreshing, joining or leaving teams now reads the same
419
+ in both views: a headline naming the server (for `E_REMOTE_INCOMPATIBLE`,
420
+ the missing feature and the update), with the kernel's code and message
421
+ under Details. The soul page showed the kernel's raw message.
422
+
423
+ - **A home's session receipt is found whatever the letter case of its path
424
+ (#780).** On a case-insensitive filesystem (the macOS default),
425
+ `.../agents/...` and `.../Agents/...` are one directory, but the receipt was
426
+ keyed by the path as the caller spelled it. So a healthy home addressed with
427
+ a different case was refused with `E_RUNTIME_ENDPOINT_UNKNOWN` by
428
+ `session inspect`, `start`, `restart` and `stop`. Retire then read it as a
429
+ home of unknown provenance, and a directory-work home was refused with
430
+ `E_WORK_INSPECTION_FAILED`. A spawn now keys the receipt and records its home
431
+ by the on-disk spelling, and every reader compares spellings on disk. A
432
+ receipt a kernel before 0.49.0 wrote keeps working where it is (nothing is
433
+ moved or rewritten). It is found from the spelling its spawn used, and from
434
+ the on-disk spelling when the two are the same. Any other spelling of such a
435
+ home still misses it: address the home as `oats status` prints it. The
436
+ missing-receipt message names the on-disk receipt path, and the older path
437
+ for the caller's spelling when that differs. Case-sensitive filesystems are
438
+ unchanged: two spellings there are two directories.
439
+
440
+ - **Retire sees a session working in a home whatever the letter case of its
441
+ path (#789).** Before it removes a home without a usable session receipt
442
+ (and on a lost tmux server, or for a home opened in Herdr), retire checks
443
+ that no tmux pane and no process works there. tmux and lsof report those
444
+ working directories in their on-disk spelling, which was compared with the
445
+ caller's spelling of the home. On a case-insensitive filesystem (the macOS
446
+ default), a home addressed in another letter case therefore looked empty
447
+ while a session still worked in it, and retire went on to remove it. Both
448
+ checks now compare on-disk spellings. So do the checks that find a home's
449
+ `.work-*` extra trees: under another spelling they were missed, so a
450
+ detached extra tree's own commits could be left reachable from no ref.
451
+ Such a tree is now kept as a worktree, as under the home's own spelling.
452
+
453
+ - **Paths given in another letter case no longer lead the kernel astray
454
+ (#789).** On a case-insensitive filesystem (the macOS default), several
455
+ checks compared a path that git, Claude or an operator had recorded in its
456
+ on-disk spelling with the caller's spelling of the same directory. The
457
+ serious one failed open: a deployment root inside a linked Git worktree,
458
+ given in another letter case, was not mapped to the primary checkout, so a
459
+ spawn created its home in the linked worktree, the misplacement that check
460
+ exists to prevent. Now:
461
+ - the root maps to the primary checkout whatever its spelling;
462
+ - retire's check that a removed worktree is no longer registered compares
463
+ on-disk spellings;
464
+ - launch prompt consent recorded under one letter-case spelling of a home
465
+ applies under another (an exactly spelled key still decides, and several
466
+ case-variant keys with no exact one give no consent);
467
+ - Codex's trust key is written in the home's on-disk spelling, which Codex
468
+ compares with its working directory;
469
+ - a project-scoped Claude plugin is found from any spelling of its project.
470
+
471
+ - **A triggered spawn no longer fails on the length of its instance name
472
+ (#669).** A trigger asked spawn for `<stem>-<purpose>`, and spawn refuses a
473
+ name over 64 characters and never rewrites one. For a soul with a long agent
474
+ name (a package soul's is `<package>--<soul>`), every event of the trigger
475
+ failed with `E_INSTANCE_NAME_INVALID`, stayed pending, and failed again at
476
+ every poll. The trigger now fits the name itself, keeping three of the 64
477
+ characters for spawn's `-2`, `-3`, … suffix. A triggered instance whose name
478
+ would be 62–64 characters is now named with a cut purpose and a 6-character
479
+ hash of the event key; a name over 64, which used to fail with
480
+ `E_INSTANCE_NAME_INVALID` and stay pending, now spawns. Names of 61
481
+ characters or fewer are unchanged. When a name needs cutting but the soul's
482
+ stem leaves no room even for the hash (a stem over 54 characters), the event
483
+ still does not spawn; it stays pending with `lastError.code:
484
+ E_INSTANCE_NAME_INVALID`, which now says the soul name is too long for a
485
+ triggered spawn and names the stem and its length. (A stem over 62
486
+ characters fails already in the preview: the message says the same, then
487
+ quotes the preview's refusal, which names `<stem>-1` and its length.)
488
+ To find affected triggers: `oats trigger test <id> --json` shows each
489
+ would-fire event's `instance` and `nameCut`; `oats trigger status <id>`
490
+ shows a pending event with `lastError.code: E_INSTANCE_NAME_INVALID` for a
491
+ trigger that was stuck. To learn the stem, the tick now runs one
492
+ `oats spawn <soul> --preview` per trigger per tick in which that trigger
493
+ fires, with the trigger's own `launchConfig`, `harness`, `model`, `backend`
494
+ and `yolo` (before, only for a trigger with `spawn.teams`, once per event,
495
+ and with none of them).
496
+ See [schedules.md](../schedules.md#triggers).
497
+
498
+ - **Retire's Git reads no longer rewrite the index they inspect (#662).**
499
+ Every `git status` a retire ran (the inspection, its classes, the copy's
500
+ verification, the outputs listing) ran with optional locks on, so Git could
501
+ refresh and rewrite the inspected worktree's index while reading it. Every
502
+ Git command the retire runs on the work, its repository, a repository under
503
+ it and a recovery clone now runs with `--no-optional-locks` and
504
+ `GIT_OPTIONAL_LOCKS=0`, with fsmonitor, hooks, an external diff and lazy
505
+ fetch (`GIT_NO_LAZY_FETCH=1`, Git 2.44 or later) turned off, and without the caller's repository-local Git variables (`GIT_DIR`,
506
+ `GIT_INDEX_FILE`, `GIT_WORK_TREE`, `GIT_CONFIG_PARAMETERS`, …), so an
507
+ inherited `GIT_DIR` or `GIT_INDEX_FILE` no longer redirects what the retire
508
+ reads. The operator's global and system Git configuration are still read,
509
+ so what status reports, and so the spawn baseline comparison, is unchanged.
510
+ A filter driver that the repository's own configuration names and its
511
+ `.gitattributes` select can still run during `git status`. See
512
+ [souls-and-instances.md](../souls-and-instances.md).
513
+
514
+ - **Retire's `work/` step runs Git helper-free, and verifies a removal
515
+ (#679).** The default re-home ran `git worktree move` with the ambient
516
+ environment, and `--discard-worktree` (or a quarantine that owes the
517
+ worktree) ran `git worktree remove --force` and `git worktree prune` through
518
+ a shell, so a helper the repository's own configuration names (fsmonitor,
519
+ hooks) could run during the retire. These commands, and a quarantine
520
+ retry's checks, now run helper-free against the repository's common Git
521
+ directory, as the `.work-*` extra-tree step already did. A removal was not
522
+ verified: a `worktree remove` that failed was swallowed, recorded as
523
+ `removed`, and `work/` was then deleted with the home, leaving a dangling
524
+ admin entry. The removal is now verified (nothing at `work/`, not in
525
+ `git worktree list`); one that did not happen refuses with
526
+ `E_WORK_PRESERVATION_FAILED` and keeps the home, `--force` included. This
527
+ changes what `--discard-worktree` does when Git refuses the removal (a
528
+ locked worktree, for example): it now refuses and keeps the home instead. When nothing is at `work/` and its repository
529
+ cannot be read, the worktree is recorded `absent`, never `removed`, and a
530
+ quarantine retry keeps `could not verify removal` as an incomplete item.
531
+
532
+ - **Retire refuses a `work/` whose `core.worktree` names another directory
533
+ (#648).** A worktree's per-worktree configuration can point Git at another
534
+ directory: its status then described that directory, while the retire
535
+ read, copied and removed `<home>/work`. A clean status there meant no
536
+ recovery, and `--discard-worktree` removed a `work/` nobody had inspected.
537
+ Before any status is trusted, each inspection now checks that Git's top
538
+ level for `work/` is `<home>/work` (in its on-disk spelling, so a symbolic
539
+ link or another letter case on a case-insensitive filesystem is the same
540
+ path), and refuses with `E_WORK_INSPECTION_FAILED`, naming both paths. The
541
+ first inspection does so before the session is stopped or any retire hook
542
+ runs: nothing was stopped, run or removed.
543
+
544
+ - **Git reads of an instance's work never fetch a missing object.** A
545
+ repository's own configuration can make it a promisor of another one: a
546
+ read of an object it lacks then fetched it, running the remote helper, ssh
547
+ command or credential helper that configuration names, and writing the
548
+ object into the observed repository. `oats instance git`, `oats instance
549
+ diff` (and the Desktop views that read them) and retire now run Git with
550
+ `GIT_NO_LAZY_FETCH=1`. Visible effect: for a partial clone that lacks an
551
+ object a read needs, `oats instance git` and the diff report a failure
552
+ (`E_GIT_FAILED`) instead of fetching it, and a retire refuses
553
+ (`E_WORK_INSPECTION_FAILED` or `E_WORK_PRESERVATION_FAILED`) and keeps the
554
+ home. The protection needs Git 2.44 or later; an older Git ignores the
555
+ variable, and nothing else changes for it.
556
+
557
+ - **A retire by name cleans its wake schedules again (#693).** Without
558
+ `--home`, `oats retire <instance>` handed the wake-schedule cleanup the
559
+ instance record instead of its home path. As soon as any wake schedule
560
+ existed the cleanup threw, the retire printed `wake schedules not cleaned:
561
+ The "paths[0]" argument must be of type string. Received an instance of
562
+ Object`, and the retiree's wake schedules stayed. The cleanup now gets the
563
+ home the retire selected, with or without `--home`; the receipt is
564
+ unchanged.
565
+
566
+ - **A recovery holds every stash entry, not just the latest (#654).** The
567
+ copy of a worktree and of each nested repository fetched `refs/stash` only,
568
+ while it copied the stash's log whole: `stash@{1}` and older were listed in
569
+ the copy and their commits were not there. Every commit the copied stash
570
+ log names is now fetched into the copy and checked there.
571
+
572
+ - **A recovery holds the blobs of a resolved conflict (#655).** The index was
573
+ copied whole, resolve-undo records included, but only its staged blobs were
574
+ restored: a conflict side that is in no commit was missing, so
575
+ `git checkout -m <path>` could not recreate the conflict in the copy. The
576
+ blobs the copied index's resolve-undo records name are now restored and
577
+ checked too.
578
+
579
+ - **The recovery copier reads the files Git reads (#647).** It trimmed white
580
+ space off the paths Git printed for it (the Git directory, the common
581
+ directory, `core.excludesFile`, the top level), so for a path that really
582
+ ends in white space it read another file, or none; and it took the staged
583
+ blobs to carry from Git's own index rather than from the index file it
584
+ copied. It now reads each path exactly as Git prints it, takes the blobs
585
+ from the index file it copies (`GIT_INDEX_FILE`), and reads a worktree's
586
+ `.git` file as Git does (the `gitdir: ` prefix, the trailing line feeds
587
+ and carriage returns removed, nothing else). A `.git` file that Git would
588
+ not read (`gitdir:` without its space, or a path with a trailing space
589
+ that does not exist) now reads as a worktree whose admin entry is gone:
590
+ the retire keeps the directory and the home and does not complete.
591
+
592
+ - **A nested repository's recovery is on its branch, with its branches and
593
+ reflogs (#657).** Its copy had a detached `HEAD` even when the source was
594
+ on a branch, kept no other branch name, and lacked commits only a reflog
595
+ reached. The copy's `HEAD` is now on the source's branch (detached only
596
+ when the source's is), every local branch exists under its name at its
597
+ commit, and the reflogs of `HEAD` and of each branch are carried, with
598
+ every commit they name. Its local configuration is still not carried beyond
599
+ the six status settings: remotes, `branch.*` upstreams, `user.*` and the
600
+ rest are dropped, so that the recovery stays inert to inspect (its
601
+ configuration could name hooks, an fsmonitor, a credential helper or a
602
+ filter that would run there). See
603
+ [souls-and-instances.md](../souls-and-instances.md).
604
+
605
+ Each of these objects is collected, restored or fetched, and checked again
606
+ before a copy is accepted; one the source cannot supply (a partial clone
607
+ that lacks it) refuses the copy with `E_WORK_PRESERVATION_FAILED`, naming
608
+ it, where before the copy went through without it.
609
+
610
+ - **A recovery of a worktree with an uncommitted top-level deletion or rename
611
+ is verified (#656).** The copy is a clone with the worktree's files put
612
+ over it, and only the top-level entries the worktree had were replaced. A
613
+ tracked top-level file, directory or link the worktree had deleted or
614
+ renamed stayed in the copy as the clone checked it out, so the copy's
615
+ verification disagreed and the retire refused with
616
+ `E_WORK_PRESERVATION_FAILED` until the deletion was committed or undone.
617
+ Each top level of the copy (the worktree's, and each nested repository's)
618
+ is now made the source's: what the source lacks is removed, `.git` aside,
619
+ then what it has is copied.
620
+
621
+ - **A work copy's verification compares every `.git` it does not rebuild
622
+ (#663).** It passed over every entry named `.git`, at any depth, so a
623
+ dangling `.git` link, or the Git directory of a repository inside a nested
624
+ one, was copied but never compared. It now leaves out only the worktree's
625
+ own `.git` and those of the nested repositories the copy rebuilds from a
626
+ clone, by their exact paths, and compares every other entry named `.git`
627
+ as bytes.
628
+
629
+ - **A file whose name is not valid UTF-8 no longer stops a retire (#645).**
630
+ The recovery copier read names as text, so such a file in the home (a
631
+ scratch repository's ref or reflog, for example) or among a worktree's
632
+ untracked or ignored files could not be opened by its decoded name, and the
633
+ retire refused with `ENOENT` until someone removed the file by hand. The
634
+ copier now reads, joins and writes names as bytes, and the copy holds such
635
+ a file under its own name, and the receipt counts its bytes (it counted
636
+ them as 0). Names shown to a person (a receipt's
637
+ `paths`, a message) stay text, with replacement characters for such bytes.
638
+ One case still refuses, now with a message that says what to do: a nested
639
+ repository whose own path is not valid UTF-8, because Git cannot be given
640
+ that path; rename the directory, then retire again. See
641
+ [souls-and-instances.md](../souls-and-instances.md).
642
+
643
+ - **Desktop: starting or restarting an instance is held to its window's
644
+ workspace (#818).** The app's main process pins every workspace-scoped
645
+ request with no `?ws=` to the workspace of the window that sent it, and
646
+ refuses one naming a workspace the server does not serve (404
647
+ `E_WORKSPACE_NOT_SERVED`) without sending it. `POST
648
+ /api/start/<instance>` and `/api/restart/<instance>` were not in that set,
649
+ so they got neither. Nothing was ever started in the wrong workspace: the
650
+ server resolves an instance only inside the workspace it is given, refuses
651
+ an ambiguous bare name and finds nothing in a workspace it does not serve.
652
+ The two routes now get the same pin and refusal as every other privileged
653
+ instance request.
654
+
655
+ - **An untracked link or a name that is not UTF-8 is compared by what it
656
+ holds (#660).** The spawn baseline's digest of a worktree's untracked and
657
+ ignored paths took them from the status decoded as text and tested each
658
+ with a call that follows links. So an untracked symbolic link whose target
659
+ does not exist, and a path whose name is not valid UTF-8, read as missing
660
+ at spawn and at retire whatever they held: a change to such a path alone
661
+ added no class, and the retire wrote no recovery for it. A new spawn's
662
+ baseline now takes the paths from the status's bytes and tests each
663
+ without following a link, so a link is compared by its target and such a
664
+ name by its file. Such a path that cannot be read (an entry under it
665
+ without permission) refuses the retire with `E_WORK_INSPECTION_FAILED`,
666
+ naming it, before anything is stopped, run or removed. A baseline written
667
+ before 0.49.0 keeps the old digest until the instance is respawned. See
668
+ [souls-and-instances.md](../souls-and-instances.md).
669
+
670
+ - **The spawn baseline's digests no longer depend on the locale, and two
671
+ different trees no longer give the same digest (#661).** The digests a
672
+ spawn baseline stores, of the home and of a worktree's untracked and
673
+ ignored paths, ordered names by the locale and wrote file contents without
674
+ their length, so a retire under another locale could read an unchanged
675
+ home as changed (which adds a copy attempt), and a file whose bytes spell
676
+ the entry after it read like those two entries. A new spawn records
677
+ `digestVersion: 2` in its baseline and writes digests that order names by
678
+ their bytes and frame every name, file and link target with its length.
679
+ The home copy's verification uses them too. A baseline written before
680
+ 0.49.0 keeps the old digests until the instance is respawned, and is
681
+ compared with them exactly as before. The baseline's own `version`, which
682
+ also gates the start and retire authority of every existing instance, is
683
+ unchanged.
684
+
685
+ - **A retire plan's notes fit what the Desktop reads (#658).** The Desktop
686
+ refuses a plan with a note over 4096 characters or more than 64 notes, and
687
+ Remove then failed with `E_CLI_PROTOCOL`. The recovery note's list of
688
+ declared roots that are not copied is now bounded to about 1024 characters
689
+ (the rest is `, and N more`), and a recovery path too long for the note is
690
+ never cut: the note says the retire receipt (`workRecovery.path`) and the
691
+ summary name it. An extra tree's note keeps the tree's path whole and leaves
692
+ its longest other parts to `facts.extraWorktrees` in the plan JSON; more
693
+ extra trees than fit in 64 notes end in `and N more extra worktrees`. A
694
+ drift note with two long branch names, or a session note with a long
695
+ reason, points to the plan JSON's field for what does not fit. The plan's
696
+ shape is unchanged.
697
+
698
+ - **Retire refusals after the hooks say what has happened, and a failed copy
699
+ keeps its cause (#659).** A recovery that cannot be completed after the
700
+ retire hooks now ends, as a refusal before them does, with what the retire
701
+ has done: the hooks have run; the home, its work and the pre-hook recovery
702
+ (if any) are kept; and whether this retire stopped the session. A copy
703
+ that fails verification while the work holds a read-only directory (a Go
704
+ module cache, for example) used to end in a bare `EACCES` from its cleanup,
705
+ losing the cause and leaving a partial copy in recovery storage: the
706
+ cleanup now makes the staged directories writable before removing them,
707
+ never replaces the original error, and names a staging directory it could
708
+ not remove.
709
+
710
+ - **The manifest checks `retirement.disposable.work` as spawn does (#659).**
711
+ A work root must be a relative path under `work/` with no empty, `.` or
712
+ `..` segment (a leading `./` and a trailing `/` are dropped first, as spawn
713
+ does). An absolute one, a Windows one such as `C:/x` included on any host,
714
+ is refused where the manifest is read: in discovery (`E_WORKSPACE_SCHEMA`),
715
+ package manifests (`E_PACKAGE_MANIFEST`) and the kernel's loader, at
716
+ `/retirement/disposable/work/<i>`; so are two entries of one manifest that
717
+ overlap. Before, any non-empty string loaded and the spawn failed later.
718
+ Spawn still refuses a declared root that is a symbolic link in the work (a
719
+ link whose target is missing too, which it used to accept) and roots of two
720
+ capabilities that overlap, now with the code `E_CAPABILITY_BROKEN`; `oats
721
+ spawn --json` still reports it as `E_SPAWN_FAILED`, with the same message.
722
+ The published schema states the same grammar.
723
+
724
+ - **Attached children follow a retained worktree (#718).** Retiring an
725
+ instance whose worktree is retained left each attached child's `work` link
726
+ pointing at the removed home. Each attached child the retire stopped is now
727
+ repointed to the retained worktree, atomically, as the last step before the
728
+ home is removed; the summary says so per child, and a relink that fails is
729
+ a warning with the command to repoint it, without undoing the retire. A
730
+ child linked through an alias of the tree (its `--work-dir`) counts too. The
731
+ retire plan names the attached children in one note, which also says that
732
+ with `--discard-worktree` their link would dangle. No receipt or
733
+ `instance.json` field is added; the child's AGENTS.md and TASK.md still
734
+ name the old path.
735
+
736
+ - **`oats instance events` answers for a retired instance (#642).** An
737
+ instance's rows outlive its home in
738
+ `<deployment>/.agents/events/<agent>--<instance>.jsonl`, but the command
739
+ looked only for a live home and answered `E_SESSION_UNKNOWN`. When no live
740
+ home resolves, it now answers from that log, in the same shape, with the
741
+ home source `absent` and `incarnation: null`. When the logs of two agents
742
+ hold an instance of that name, it refuses with `E_AMBIGUOUS_INSTANCE` and
743
+ lists the candidates; `--home <agents root>/<agent>/instances/<instance>`
744
+ picks one. A removed `--home` answers only at that path and only when that
745
+ agent's log exists; any other is still `E_HOME_MISMATCH`.
746
+
747
+ ## Removed
748
+
749
+ - **Desktop: the unused transcript route of the local server (#627).**
750
+ `GET /api/chat/<instance>` returned a parsed transcript of an instance's
751
+ harness session log, read from under the user's home. Nothing in the
752
+ Desktop used it: its terminals are viewers of the instance's session, and
753
+ the separate chat view it served was dropped. The path now answers as any
754
+ unknown route does (`404`, `not found`), behind the same Host and Origin
755
+ guards, and the Desktop no longer pins a workspace onto it. The instance
756
+ menu no longer sends an action it has no handler for to the server as
757
+ `POST /api/<action>/<instance>`; no menu action took that path, and one
758
+ would now be refused in the app. Closes
759
+ [#627](https://github.com/awebai/oats/issues/627).
760
+
761
+ - **Desktop: the dedicated harvest route of the local server (#818).**
762
+ `POST /api/harvest/<instance>` ran the knowledge provider's harvest for one
763
+ instance. Nothing in the Desktop called it once the instance menu stopped
764
+ sending actions it has no handler for (#627). Harvest is still available
765
+ where a soul's capability offers it: the soul page runs any provider
766
+ operation, `knowledge:harvest` included, through `/api/capabilities`, and a
767
+ schedule can run it. The path now answers as any unknown route does
768
+ (`404`, `not found`), behind the same Host and Origin guards. The Desktop's
769
+ "no compatible CLI" card and log now say Spawn, Start and other changes
770
+ need the CLI, instead of naming a Harvest action it no longer has.