@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.
Files changed (47) hide show
  1. package/bin/oats.mjs +326 -28
  2. package/docs/capabilities.md +425 -8
  3. package/docs/capability-manifest.schema.json +60 -5
  4. package/docs/configuration.md +103 -0
  5. package/docs/desktop-cli-api.md +542 -47
  6. package/docs/desktop.md +85 -5
  7. package/docs/execution-targets.md +50 -9
  8. package/docs/implementation.md +74 -1
  9. package/docs/integrations.md +7 -5
  10. package/docs/knowledge.md +167 -197
  11. package/docs/official-catalog.md +4 -4
  12. package/docs/packages.md +28 -14
  13. package/docs/release-lane.md +41 -0
  14. package/docs/release-notes/v0.49.0.md +770 -0
  15. package/docs/release-notes/v0.50.0.md +279 -0
  16. package/docs/schedules.md +289 -53
  17. package/docs/servers.md +7 -0
  18. package/docs/souls-and-instances.md +450 -60
  19. package/docs/workspaces.md +3 -3
  20. package/injects/work-checkout.md +17 -11
  21. package/injects/work-worktree.md +19 -13
  22. package/lib/capability-contract.mjs +100 -11
  23. package/lib/capability-show.mjs +18 -2
  24. package/lib/core.mjs +1374 -394
  25. package/lib/instance-events.mjs +9 -10
  26. package/lib/instance-git.mjs +19 -10
  27. package/lib/instance-inspect.mjs +58 -18
  28. package/lib/instance-lifecycle.mjs +106 -16
  29. package/lib/instance-resolution.mjs +15 -3
  30. package/lib/launch-prompt-policy.mjs +17 -3
  31. package/lib/packages.mjs +1 -0
  32. package/lib/real-path.mjs +27 -0
  33. package/lib/refused-text.mjs +17 -0
  34. package/lib/resolve.mjs +4 -4
  35. package/lib/retained-after-retire.mjs +387 -0
  36. package/lib/retire-output.mjs +6 -1
  37. package/lib/schedule.mjs +9 -2
  38. package/lib/servers.mjs +32 -6
  39. package/lib/tree-copy.mjs +18 -7
  40. package/lib/trigger-sources.mjs +234 -0
  41. package/lib/triggers.mjs +705 -108
  42. package/lib/workspace.mjs +20 -5
  43. package/lib/worktree-hooks.mjs +392 -0
  44. package/lib/worktree.mjs +655 -0
  45. package/package-catalog.json +3 -3
  46. package/package.json +1 -1
  47. package/skills/oats-getting-started/SKILL.md +1 -1
@@ -0,0 +1,279 @@
1
+ # OATS 0.50.0
2
+
3
+ 2026-10-10
4
+
5
+ ## Added
6
+
7
+ - **`oats doctor` lists what retires left behind (#703, part 2a).** These are
8
+ information lines only, with no new key. Doctor prints one
9
+ `retained-recovery:` line per recovery copy under each instances directory's
10
+ `.oats-retirement/recovery/`. Each line gives the path, the instance, `phase`
11
+ and `classes` from `recovery.json`, the size and whether `after-hooks/` is
12
+ there. A copy whose `recovery.json` is missing or unreadable is listed and
13
+ says so. Doctor also prints one `retained-worktree:` line per retained
14
+ worktree under `.agents/worktrees/<repo>/`, giving its repository, its
15
+ branch (or detached commit), and whether it is clean, with the uncommitted
16
+ classes when it isn't. Each line ends with the reachability fact for the
17
+ HEAD commit: whether a ref of the source repository other than the tree's
18
+ own branch reaches it, or how many commits no other ref reaches. A
19
+ recovery line also names a retained worktree on its branch. These are
20
+ facts to decide with, never "safe to delete". Each kind starts with a line
21
+ giving its total, then at most 50 items, then `… and N more`. In
22
+ `oats doctor --json` they are elements of the existing `information[]`, one
23
+ line each. The reads are read-only and run Git without helpers, so doctor
24
+ refreshes no index and follows no link. It doesn't ask for the status of a
25
+ repository that configures a content filter, and never enters a
26
+ submodule's work tree; the line says so. See [After a retire: inspect,
27
+ restore, dispose](../souls-and-instances.md#after-a-retire-inspect-restore-dispose).
28
+
29
+ - **Capability-declared trigger sources, feature `trigger-sources` (#669).**
30
+ A trigger can now watch more than GitHub pull requests. A capability
31
+ declares **trigger sources** in its manifest (`triggerSources`): each is
32
+ one of its own commands that, at each poll, lists the events due now. A
33
+ trigger names one as `on.source: "<capability>:<source>"`, with `on:
34
+ { source, params?, events, poll? }`, and the kernel keeps everything after
35
+ the list on the same pipeline `github.pull_request` runs on: keys,
36
+ at-least-once recording, pending events, concurrency by subject, the
37
+ instance name, the event file and the spawn. Templates may name
38
+ `{trigger} {source} {subject} {event} {key} {url} {fields.<name>}`, and the
39
+ default purpose is `{trigger}-{subject}`; a `github.pull_request` template
40
+ may now also name `{subject}` and `{key}`. What a trigger means is checked
41
+ against the capability its soul composes at `trigger add`, at every poll
42
+ (before the source runs) and by `trigger test`: a failure is
43
+ `E_TRIGGER_SOURCE {capability, source, pointer?}` or
44
+ `E_TRIGGER_INVALID {field}`, and a poll that finds one shows it as the
45
+ trigger's `invalid: {code, message, field?, at}` in `list` and `status`.
46
+ A param value carrying a control, bidi or invisible character is refused
47
+ (`E_TRIGGER_INVALID`, `on.params.<name>`), and a stored one is printed by
48
+ `trigger list`, `status` and `show` with those characters replaced or
49
+ escaped.
50
+ - **The wire.** One JSON request on stdin, exactly one JSON answer on
51
+ stdout, killed at 30 s, in the environment a `readiness --soul` check
52
+ gets: ambient `OATS_*`, `OAS_*` and `PI_*` removed, no instance, no
53
+ credential from the kernel. A wire failure is `E_TRIGGER_POLL` with
54
+ `details.cause` (`exit`, `result`, `too-many-events`, `timeout`,
55
+ `refused`, `resolution`), records nothing and drops nothing. Each event
56
+ is checked alone (key, subject, event, an `https:` `url` on one of the
57
+ manifest's `urlHosts`, declared `fields`); an invalid one is dropped
58
+ alone and listed in `invalidEvents`. A `url` must be printable ASCII
59
+ with no space as written. A field value longer than 200 characters, or
60
+ carrying a control, bidi or invisible character, is invalid whatever its
61
+ pattern admits. The source's own text (a skipped item's `why`, a refusal's code and message) is capped, has every control,
62
+ bidi and invisible character replaced with U+FFFD, is never composed into
63
+ a task, and is printed only under `source says:`.
64
+ - **How a pending event ends.** By the current state: a good poll that no
65
+ longer lists a pending key drops it; a failed poll drops nothing.
66
+ Retention keeps 500 fired keys per trigger as before, but never evicts a
67
+ key the last good poll listed.
68
+ - **The tick stays inside its minute.** Capability-source polls run after
69
+ the schedules, most overdue first across every deployment the host
70
+ ticks, and only while they can end within 50
71
+ s of the tick's start; the rest are `poll-deferred` and go first next
72
+ tick, so no schedule is missed because of them.
73
+ - **`oats trigger poll <id> --run-source [--max-age <s>]`**, a new read
74
+ verb (on the `--max-age` allow-list), runs a trigger's source once and
75
+ records nothing. It and `oats trigger test <id> --run-source` **execute
76
+ the capability's source command**: "read verb" means records nothing,
77
+ not runs no provider code.
78
+ - **A manual run takes `--run-source`.** Without it, `trigger test` and
79
+ `trigger poll` of a capability source's trigger are refused with
80
+ `E_TRIGGER_SOURCE_RUN` (`details: {capability, source, flag}`, a
81
+ non-zero exit, the command to run again in the message): nothing of the
82
+ capability has executed and nothing has been written. A definition that
83
+ is invalid or whose meaning fails answers that first, flag or no flag.
84
+ The flag is caller intent, never trust consent: with it both run the
85
+ source whatever this host's `automations.trust` and the trigger's
86
+ `runsOn` say, which gate the host tick exactly as before (the tick
87
+ passes the flag to its own child). On a `github.pull_request` trigger
88
+ the flag is accepted and inert. `test` names the placement in `problems`
89
+ ("run manually with --run-source; the tick will not run it here: …") and
90
+ always warns that the source's credential may not be visible to the host
91
+ timer.
92
+ - **Contained.** A malformed `triggerSources` never refuses the
93
+ capability: spawn, preview, readiness, discovery and the lock ignore it.
94
+ It is validated where a source is used, per source, and `oats
95
+ capabilities show --json` adds `triggerSources` as declared and
96
+ `triggerSourceProblems`. A provider declaring `triggerSources` does not
97
+ need to raise `compatibility.oats`: every workspace-model kernel ignores
98
+ the key, and only the host that runs a trigger naming the source needs
99
+ this release. An older kernel reading the same deployment refuses such a
100
+ trigger with `on.params: unknown key`, not with a message about
101
+ `on.source`: `trigger add` stores `on.params` (`{}` when none is given),
102
+ and that kernel checks the keys of `on` first.
103
+ - **Schema tooling.** Until this release the published
104
+ `docs/capability-manifest.schema.json` is closed at the top level
105
+ (`additionalProperties: false`), so any tool that validates a manifest
106
+ against an older copy of the schema flags `triggerSources`: this
107
+ repository's own `validate-project`, the package dry-run checks, a
108
+ provider's CI that pins the schema. The runtime ignores the key;
109
+ schema-validating tooling does not. Validate against this release's
110
+ schema, or declare the key once your tooling uses it.
111
+ - **Output keys are additive and `triggerApi` stays 1.** On a capability
112
+ source's rows only (absent, not `null`, on a `github.pull_request` row,
113
+ whose outputs are unchanged): `status` gains `source`, `invalidEvents`,
114
+ `skipped` and `invalid`, with `lastPoll` counting `events`,
115
+ `invalidEvents`, `skipped` and `filtered` (or `{ok: false, cause, error,
116
+ source?}`); `test` gains `source`, with `repo: null`; `instance.json.trigger`
117
+ gains `fields`, with `repo` and `number` `null`. Readers tell rows apart
118
+ by `on.source` and gate on `trigger-sources`.
119
+ See [schedules.md](../schedules.md#capability-sources),
120
+ [capabilities.md](../capabilities.md#trigger-sources-triggersources) and
121
+ [desktop-cli-api.md](../desktop-cli-api.md#oats-trigger).
122
+
123
+ - **Desktop: capability trigger sources (#669, #802).** With an OATS that
124
+ declares `trigger-sources`, a trigger that takes its events from a
125
+ capability's source shows which source it is and what the trigger passes
126
+ to it, what the source's last poll found or why it failed, and which
127
+ events OATS refused or the source skipped. A capability's page lists the
128
+ trigger sources it declares. Text from a source, from a trigger's file or
129
+ from a capability's manifest is shown as a quote that says whose it is,
130
+ never as the Desktop's own words, and never as a link or a button.
131
+ **Test** on such a trigger runs the capability's source command on this
132
+ computer, so it is no longer one click: it first shows what will run, on
133
+ which computer and with which parameters, and runs it once when you press
134
+ **Run test**. Opening that confirmation runs nothing. Testing records
135
+ nothing, spawns nothing and does not trust or start the trigger.
136
+ `github.pull_request` triggers keep their one-click Test. With an older
137
+ OATS nothing changes.
138
+
139
+ ## Changed
140
+
141
+ - **The Desktop accepts OATS CLIs `>=0.25.8 <0.51.0`.** The compatibility band
142
+ admits 0.50. Upgrade the CLI and the Desktop together: a 0.49.0 Desktop
143
+ refuses a 0.50.0 CLI. The Desktop's informed Test on a capability source's
144
+ trigger is gated on feature `trigger-sources`; the other feature gates are
145
+ unchanged.
146
+
147
+ - **The workspace pins oats.aweb 1.24.0** (tag on a7d976d4). Retire's
148
+ recovery copy no longer keeps an instance's aweb private keys, and retire
149
+ exits nonzero when leaving a joined team fails (except `team_not_hosted`), so
150
+ the home and the key that can still leave the team are kept. Readiness and
151
+ an approved Claude channel launch read the machine's Claude Code managed
152
+ settings and warn whether they admit the aweb channel plugin; the skill
153
+ documents the approved channel route as the recommended unattended setup.
154
+ The package's OATS floor rises to `>=0.42.0`. Homes spawned before this
155
+ version keep what they were spawned with; deployments adopt it with
156
+ `oats sync`.
157
+
158
+ - **The official catalog and `mirrors/oats-aweb` carry oats.aweb 1.24.0.** The
159
+ catalog's ref is `v1.24.0`, and the mirror is the package at that tag
160
+ (a7d976d4), byte for byte, so the workspace pin, the catalog and the mirror
161
+ agree.
162
+
163
+ - **oats.framework 1.9.0: oats.core 2.5.0 and oats.setup 2.5.0.** Instruction
164
+ text only; no kernel, schema or provider contract changes. It also carries
165
+ the skill text for 0.49.0's worktree commands and trigger names, which
166
+ 0.49.0 shipped in the kernel while the package stayed at 1.8.0. The
167
+ official catalog and the workspace pin `oats-framework/v1.9.0`; deployments
168
+ adopt it with `oats sync`, and homes spawned before keep the skills they
169
+ were spawned with.
170
+ - **oats.core 2.5.0:** `oats-operate` covers the extra trees an instance
171
+ makes in its home with `oats worktree add|remove` (from OATS 0.49.0,
172
+ #801), that retiring an instance stops its recorded children first
173
+ (#782), what `oats doctor` lists of what retires left (#836), and the
174
+ event a triggered run reads: its `subject` (#798) and an event from a
175
+ capability's trigger source (#845).
176
+ - **oats.setup 2.5.0:** `oats-automations` covers triggers on a
177
+ capability's source, with `--run-source` for trying one by hand (OATS
178
+ 0.50.0, #845), and how trigger instance names are cut to fit (from OATS
179
+ 0.49.0, #798). `oats-workspace-config` gains the host step "Claude
180
+ channel delivery (approved route)", and `oats-onboarding` points to it
181
+ (#844).
182
+ - Both skills name the kernel version in which each of these starts, so
183
+ the package's floors do not move.
184
+ - A kernel release whose pull requests touched `oats-package/` now ships a
185
+ framework release with it:
186
+ [release-lane.md](../release-lane.md#releasing-oatsframework).
187
+
188
+ ## Fixed
189
+
190
+ - **Retire: a worktree on a long branch is re-homed instead of refused
191
+ (#821).** A retire keeps a worktree (`work/`, or an extra `.work-*` tree) by
192
+ moving it to `<deployment>/.agents/worktrees/<repo>/<leaf>`, the leaf being
193
+ the whole branch name as one path component. A branch whose flattened name
194
+ went over NAME_MAX made `git worktree move` fail with ENAMETOOLONG. The retire
195
+ then refused with `E_WORK_PRESERVATION_FAILED`, until the branch was renamed
196
+ or the worktree discarded with `--discard-worktree`. The leaf is now at most 231 bytes before its `-N`. A
197
+ longer one is cut, its trailing `-` trimmed, and followed by `-` and 6 hex of
198
+ the SHA-256 of the full branch name, so it stays readable and unique per
199
+ branch. A leaf that already fits is unchanged, and the retire plan's
200
+ `movedTo` names the same path the retire uses
201
+ ([souls-and-instances.md](../souls-and-instances.md#extra-trees-at-retire)).
202
+
203
+ - **Retire: a failed recovery copy is cleaned up even when a read-only
204
+ directory in it has a name that isn't UTF-8 (#827).** When a recovery copy
205
+ fails, the retire makes each directory of its staging copy writable and
206
+ removes it. It listed names as text, so it couldn't reach a read-only
207
+ directory (a Go module cache, `0555`) whose name isn't valid UTF-8, and the
208
+ staging directory was left in recovery storage. The refusal was still the
209
+ original `E_WORK_PRESERVATION_FAILED` and named the leftover to remove by
210
+ hand. Nothing was lost. Names are now listed and joined as bytes, as the
211
+ copier writes them, and the staging directory is removed. The refusal text is
212
+ unchanged.
213
+
214
+ - **The process scan reads `/proc` on Linux, and doctor names a host with no
215
+ scan (#625).** Whether a live process works in an instance home came only
216
+ from `lsof`, which many Linux hosts lack. There retire refused whenever it
217
+ needed the scan (a home without its session receipt, a missing recorded
218
+ tmux socket, a Herdr home), and nothing said why before the refusal. Now
219
+ the scan reads `/proc` on Linux (each process's `cwd` link, `comm` and
220
+ `stat`) and runs `lsof` elsewhere, as before; the answer is unchanged: a
221
+ pid and a program name, never an argument list. A process that ends during
222
+ the scan is skipped. A `/proc` that cannot be read fails the scan, never
223
+ answers "none". `oats doctor` (text, and `--json` in `information`, no new
224
+ key) adds a `process-scan-unavailable` line only on a host with neither,
225
+ saying what it blocks and to install `lsof`. A refusal for a missing `lsof`
226
+ now says to install it. The stated limit is unchanged: neither mechanism
227
+ sees a process this user may not inspect (another user's, or a
228
+ non-dumpable one such as `ssh-agent`), so such a process working in a home
229
+ does not stop a retire; refusing whenever one exists would refuse on every
230
+ host. The harness OATS launches runs as the user and is seen. See
231
+ [souls and instances](../souls-and-instances.md#the-process-scan).
232
+
233
+ - **A tmux server whose socket file was removed no longer reads as stopped
234
+ (#624).** A tmux server keeps running when its socket file is removed, and
235
+ tmux then answers as it does after a reboot (`No such file or directory`).
236
+ `oats status` showed such an instance as not running, `oats session
237
+ start`/`restart` created a second server at the recorded socket path and
238
+ launched a second harness in the same home, and `oats instance stop`
239
+ reported it idle. Now a missing socket file counts as stopped only when no
240
+ process works in the home, as retire already required (#622). Otherwise,
241
+ or when the process scan cannot run, status shows the row `running: null`,
242
+ `runtimeState: "unreachable"` with a `runtimeError` that names the
243
+ processes (existing values), start and restart refuse with
244
+ `E_SESSION_UNKNOWN` and create nothing, and stop refuses with
245
+ `E_SESSION_UNAVAILABLE`. Retire, which already scanned, now also scans
246
+ when an older tmux words a missing socket file as `failed to connect to
247
+ server: No such file or directory`; it took that as stopped. The message
248
+ names tmux's own remedy: the server
249
+ recreates its socket file when its process receives `SIGUSR1`. OATS never
250
+ sends it. A socket file that no server listens on is still stopped, with
251
+ no scan, and after a reboot (no process in the home) nothing changes. Any
252
+ process working in the home blocks start and stop while the socket file
253
+ is missing, a shell left in that directory included; the message names its
254
+ pid and program. See [Sessions](../execution-targets.md#missing-socket).
255
+
256
+ ## Documentation
257
+
258
+ - **Claude channel delivery: the approved route, as a host setup step.**
259
+ Claude seats on aweb channel delivery no longer need to stop at Claude's
260
+ “WARNING: Loading development channels” prompt. With the `oats.aweb` setting
261
+ `claudeChannelMode: approved` (host-only) and `delivery: channel`, Claude
262
+ starts with `--channels plugin:aweb-channel@awebai-marketplace` and admits
263
+ the plugin when a root-owned managed-settings file on the machine lists it
264
+ (`/etc/claude-code/managed-settings.json` on Linux,
265
+ `/Library/Application Support/ClaudeCode/managed-settings.json` on macOS,
266
+ with `channelsEnabled: true` and the `aweb-channel` /
267
+ `awebai-marketplace` entry in `allowedChannelPlugins`). It does not depend
268
+ on the Claude version and needs no launch-prompt consent. A human admin
269
+ with sudo writes that file; OATS never does. Setting `allowedChannelPlugins`
270
+ replaces Anthropic's default channel allowlist on the host, and on an
271
+ account governed by server-managed settings or MDM the file is ignored (the
272
+ organization admin sets the keys there). Existing homes keep the mode they
273
+ were spawned with: respawn one to adopt the route. The contract is
274
+ [Claude channel delivery: the approved route](../configuration.md#claude-channel-delivery-the-approved-route);
275
+ the operator's ordered steps, with the banner checks, are the `oats.setup`
276
+ host step “Claude channel delivery (approved route)” in
277
+ `/oats-workspace-config`, which also names the file in its
278
+ where-each-fact-lives table; `/oats-onboarding` card 4 calls the step. No
279
+ kernel or CLI behaviour changes.