@awebai/oats 0.48.0 → 0.50.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.
- package/bin/oats.mjs +326 -28
- package/docs/capabilities.md +425 -8
- package/docs/capability-manifest.schema.json +60 -5
- package/docs/configuration.md +103 -0
- package/docs/desktop-cli-api.md +542 -47
- package/docs/desktop.md +85 -5
- package/docs/execution-targets.md +50 -9
- package/docs/implementation.md +74 -1
- package/docs/integrations.md +7 -5
- package/docs/knowledge.md +167 -197
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +28 -14
- package/docs/release-lane.md +41 -0
- package/docs/release-notes/v0.49.0.md +770 -0
- package/docs/release-notes/v0.50.0.md +279 -0
- package/docs/schedules.md +289 -53
- package/docs/servers.md +7 -0
- package/docs/souls-and-instances.md +450 -60
- package/docs/workspaces.md +3 -3
- package/injects/work-checkout.md +17 -11
- package/injects/work-worktree.md +19 -13
- package/lib/capability-contract.mjs +100 -11
- package/lib/capability-show.mjs +18 -2
- package/lib/core.mjs +1374 -394
- package/lib/instance-events.mjs +9 -10
- package/lib/instance-git.mjs +19 -10
- package/lib/instance-inspect.mjs +58 -18
- package/lib/instance-lifecycle.mjs +106 -16
- package/lib/instance-resolution.mjs +15 -3
- package/lib/launch-prompt-policy.mjs +17 -3
- package/lib/packages.mjs +1 -0
- package/lib/real-path.mjs +27 -0
- package/lib/refused-text.mjs +17 -0
- package/lib/resolve.mjs +4 -4
- package/lib/retained-after-retire.mjs +387 -0
- package/lib/retire-output.mjs +6 -1
- package/lib/schedule.mjs +9 -2
- package/lib/servers.mjs +32 -6
- package/lib/tree-copy.mjs +18 -7
- package/lib/trigger-sources.mjs +234 -0
- package/lib/triggers.mjs +705 -108
- package/lib/workspace.mjs +20 -5
- package/lib/worktree-hooks.mjs +392 -0
- package/lib/worktree.mjs +655 -0
- package/package-catalog.json +3 -3
- package/package.json +1 -1
- 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.
|