@awebai/oats 0.69.17 → 0.69.19

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 (61) hide show
  1. package/README.md +1 -1
  2. package/bin/oats.mjs +14 -13
  3. package/docs/capabilities.md +8 -1
  4. package/docs/container.md +345 -18
  5. package/docs/design/2026-09-23-workspace-module-contracts.md +8 -2
  6. package/docs/design/2026-09-27-team-model-v2.md +2 -2
  7. package/docs/design/2026-09-28-automations-trust.md +1 -1
  8. package/docs/desktop-cli-api.md +100 -53
  9. package/docs/desktop.md +53 -24
  10. package/docs/execution-targets.md +66 -48
  11. package/docs/implementation.md +8 -7
  12. package/docs/integrations.md +2 -2
  13. package/docs/knowledge.md +5 -5
  14. package/docs/official-catalog.md +7 -7
  15. package/docs/packages.md +13 -13
  16. package/docs/release-lane.md +30 -23
  17. package/docs/release-notes/v0.69.18.md +358 -0
  18. package/docs/release-notes/v0.69.19.md +172 -0
  19. package/docs/servers.md +5 -3
  20. package/docs/souls-and-instances.md +51 -27
  21. package/docs/trust-model.md +119 -0
  22. package/docs/tui.md +8 -8
  23. package/docs/upgrading.md +45 -19
  24. package/docs/workspaces.md +3 -3
  25. package/injects/work-directory.md +27 -2
  26. package/injects/work-workspace.md +32 -6
  27. package/lib/command-flags.mjs +1 -1
  28. package/lib/core.mjs +26 -11
  29. package/lib/errors.mjs +1 -1
  30. package/lib/home-owner.mjs +25 -0
  31. package/lib/host-run-admission.mjs +21 -0
  32. package/lib/host-run-child.mjs +31 -0
  33. package/lib/host-run-work.mjs +150 -0
  34. package/lib/host-run.mjs +43 -29
  35. package/lib/instance-naming.mjs +26 -44
  36. package/lib/packages.mjs +0 -43
  37. package/lib/pi-bridge.mjs +18 -6
  38. package/lib/schedule.mjs +5 -3
  39. package/lib/servers.mjs +4 -3
  40. package/lib/session-end.mjs +9 -0
  41. package/lib/session-resume-contract.mjs +1 -1
  42. package/lib/session-resume.mjs +144 -51
  43. package/lib/session-seen.mjs +16 -11
  44. package/lib/triggers.mjs +3 -1
  45. package/lib/worktree.mjs +5 -2
  46. package/package-catalog.json +3 -3
  47. package/package.json +4 -2
  48. package/packages/client/above-tested-notice.mjs +30 -0
  49. package/packages/client/above-tested.mjs +225 -0
  50. package/packages/client/cli-locator.mjs +67 -52
  51. package/packages/client/deployment-label.mjs +4 -4
  52. package/packages/client/instance-name.mjs +5 -29
  53. package/packages/client/instance-presentation.mjs +2 -2
  54. package/packages/client/instance-tree.mjs +18 -7
  55. package/packages/client/session-start.mjs +31 -3
  56. package/packages/client/workspace-choices.mjs +1 -1
  57. package/packages/client/workspace-views.mjs +1 -1
  58. package/packages/record/README.md +10 -8
  59. package/packages/record/lib/process-identity.mjs +14 -36
  60. package/packages/tui/lib/read.mjs +19 -3
  61. package/skills/oats-getting-started/SKILL.md +33 -4
@@ -0,0 +1,358 @@
1
+ # OATS 0.69.18
2
+
3
+ From this Desktop on, the Desktop and the CLI can be upgraded in either order:
4
+ a Desktop accepts a newer CLI and holds back only what it was not tested with.
5
+ The Desktop's backend now listens on a private socket and checks a per-launch
6
+ credential on every request. Instances are named for their role in the
7
+ coordination (`<descriptive>-<role>`), in the kernel's suggestion, the
8
+ Desktop's spawn dialog and oats.core alike. The team container supervises its
9
+ wake broker. The official catalog pins oats.aweb 1.41.0, oats.okf 6.0.3 and
10
+ oats.framework 1.25.0.
11
+
12
+ ## Upgrade
13
+
14
+ - **From this Desktop on, the Desktop and the CLI can be upgraded in either
15
+ order.** A Desktop newer than 0.69.17 accepts an OATS CLI of a later minor
16
+ or major version and holds back what it was not tested with until it is
17
+ updated. A Desktop of 0.69.17 or older still refuses such a CLI: where one
18
+ is installed, install the new Desktop first
19
+ ([Either order works](../upgrading.md#either-order-works)).
20
+
21
+ - **Start the wake broker before a broker-delivered home's next start.**
22
+ From oats.aweb 1.40.0, `oats spawn` and every start of a home the host
23
+ wake broker delivers to (Codex, `delivery: session`, or a runtime with no
24
+ aweb channel of its own) refuse while no broker runs, with
25
+ `wake-daemon-not-running`. The message names the start for the host:
26
+ `oats aweb wake install` in your own terminal, or `aw wake run` as a
27
+ supervised process where there is no service manager. Check with
28
+ `oats aweb wake status`. Claude and pi homes under channel delivery are
29
+ not affected.
30
+
31
+ - **oats.aweb tests aw 1.36.58** (from 1.36.56, since oats.aweb 1.39.1); the
32
+ floor stays aw 1.36.33. `aw-newer-than-tested` now warns only above 1.36.58, and
33
+ `oats aweb setup --create --namespace` names and, with `--install-aw`,
34
+ installs aw 1.36.58. Install that version on each host where readiness
35
+ asks for it.
36
+ - **Stop an older wake broker before the new aw's starts.** aw 1.36.58's
37
+ broker takes an OS file lock that an earlier broker doesn't hold. Rerun
38
+ `oats aweb wake install` after the aw upgrade: it restarts the unit. A
39
+ broker started by hand is stopped by hand first.
40
+
41
+ - **A deployment that runs `oats` as root, or as an operator account,
42
+ against homes another user owns** must run those commands as the homes'
43
+ owner, with that user's `HOME`: `sudo -H -u '#<uid>' oats session start …`,
44
+ and the same for `oats instance stop`, `oats retire` and
45
+ `oats instance upgrade`. Without `-H` the command may keep the caller's
46
+ `HOME` and use the wrong `~/.oats`. A deployment where one user runs both
47
+ `oats` and the agents, the team container among them, changes nothing.
48
+
49
+ - A legacy lock written before 0.69.15 without `processStart` may need a
50
+ one-time operator clear after a container restart. OATS keeps an unknown
51
+ holder held instead of taking it over: once no holder runs, clear the
52
+ reported lock path and start again.
53
+
54
+ - **An older Desktop keeps appending the soul's role to a typed name until
55
+ it is upgraded.** A Desktop of 0.69.17 or older still sends a typed
56
+ `pricing-page` for `oats-desktop-expert` as `pricing-page-expert`,
57
+ whatever OATS CLI it runs with: the CLI can't tell an appended word from
58
+ one you typed. Upgrade the Desktop to get the name exactly as you type it.
59
+
60
+ - **A host on an older OATS keeps the old suggestion until it is upgraded:**
61
+ a few words for the work, then the soul's last word. A spawn through
62
+ `--server` with `--suggest-name` is named by the host that runs it, so its
63
+ name follows the host's OATS, not the caller's.
64
+
65
+ ## Changed
66
+
67
+ - The [team agent image](../container.md) pins `@awebai/aw` 1.36.58.
68
+
69
+ - **The Desktop accepts a newer CLI and says what it holds back.** Its tested
70
+ bound is the minor of its own version, read from its own manifest; no
71
+ release bumps a ceiling. A released CLI above that bound, with the same
72
+ desktop API, is accepted with `aboveTested` and `testedThrough` on
73
+ `/api/cli`. Reads, terminals, the Spawn preview and apply, Start, Restart,
74
+ the colour and the background stay on. Every other operation, including
75
+ one that does not exist yet, is refused before any CLI process runs, with
76
+ code `cli-above-tested`; the launch resume sweep is skipped with one log
77
+ line naming that code. In the CLI card's place one line says why and what
78
+ is off, and links that version's release:
79
+ `This Desktop was tested with oats CLIs up to <X.Y>; the installed CLI is <version>. Stop, Remove, schedules, triggers and every other change except Spawn, Start, Restart, colour and background are off until you install OATS Desktop <version>.`
80
+ The card's "This Desktop is older than the installed oats CLI" branch is
81
+ now for a CLI of a newer desktop API only. The floor (0.26.0), the
82
+ prerelease rule and the desktop API rule are unchanged
83
+ ([OATS Desktop](../desktop.md), [the probe](../desktop-cli-api.md))
84
+ (oats-project/oats#1879).
85
+ - **`oats update`'s line for a CLI of another minor or major version** now
86
+ reads `An OATS Desktop older than <X.Y> holds actions back with this CLI.`,
87
+ then the Desktop's own held-back sentence for that version, then
88
+ `(An OATS Desktop of 0.69.17 or older refuses this CLI until then.)`. It
89
+ replaces `OATS Desktop refuses a CLI newer than its own minor version: if you
90
+ use it, install OATS Desktop <version> first.`
91
+ ([Upgrading](../upgrading.md#either-order-works)) (oats-project/oats#1879).
92
+
93
+ - **The official catalog pins oats.aweb 1.41.0** (from 1.39.0, through 1.39.1
94
+ and 1.40.0), and OATS's own workspace takes it. The aw floor stays 1.36.33;
95
+ the tested aw is 1.36.58.
96
+ - **A broker-delivered home needs a running broker** (1.40.0). A Codex or
97
+ `delivery: session` home used to spawn with no broker running, and was
98
+ then never woken. It is now refused at spawn and at each start.
99
+ - **An interrupted join is settled.** A join killed after aw accepted its
100
+ invite no longer leaves a membership the home doesn't know about: the
101
+ join writes its intent ahead, and the next `oats aweb join`, `leave` or
102
+ retire finishes or releases it. A start warns.
103
+ - **The roster marks retired certificates.** `oats aweb roster` marks the
104
+ certificates a retire on this host had to leave in a team whose
105
+ controller key people hold, and prints the command the team's
106
+ controller removes them with.
107
+ - **A refused wake stream is named** (1.39.1, 1.41.0). With aw 1.36.58 a
108
+ stream the server refused shows as `refused` and is retried; readiness
109
+ reports it as `wake-stream-unavailable`, naming the phase, aw's cause and
110
+ the next attempt.
111
+
112
+ Nothing a deployment must change. The mirrors under `mirrors/oats-aweb*`
113
+ are copied from the v1.41.0 tag
114
+ ([oats.aweb's CHANGELOG](https://github.com/awebai/oats-aweb/blob/v1.41.0/CHANGELOG.md)).
115
+
116
+ - **A Codex or session-delivery machine starts its wake broker before the
117
+ setup expert is spawned.** The getting-started skill's step 9 has a new
118
+ last item: when the setup expert is woken by the host wake broker (Codex,
119
+ or `delivery: session`), the person runs `oats aweb wake install` in
120
+ their own terminal, or `aw wake run` as a supervised process where there
121
+ is no service manager, and the agent goes on to the spawn only once
122
+ `oats aweb wake status` reports the daemon running. oats.aweb refuses to
123
+ spawn or start such a home while no broker runs, so the broker can no
124
+ longer be left for the setup expert to install. `/oats-host-delivery`
125
+ Choice 2 now says the same: a broker-delivered home is refused with
126
+ `wake-daemon-not-running`, not left unwoken.
127
+
128
+ - **OATS Desktop's backend now requires the app's per-launch credential on
129
+ every request, and listens on a private socket.** The app's main process
130
+ starts its own backend server at every launch, always, on a Unix domain
131
+ socket in a directory of its own (owned by you, closed to group and
132
+ others), and hands it a fresh credential over a private pipe. Every request
133
+ carries that credential; one without it is refused (`401`
134
+ `E_UNAUTHORIZED`). The backend opens no TCP port, and the app never uses a
135
+ server it did not start. The Host and Origin guards stay. See
136
+ [Security posture](../desktop.md#security-posture).
137
+ - **The CLI binary is chosen only through the app's own file dialog.**
138
+ **Choose oats…** saves the pick where the backend reads it at each probe;
139
+ `POST /api/cli/reprobe` takes no binary (its body is `{}` or empty,
140
+ anything else is `400` `E_BAD_ARGS`).
141
+ - **Starting the backend or the view harness by hand.** A developer starting
142
+ `packages/desktop/server/oats-web.mjs` passes `--socket <path>` (in a
143
+ directory you own with mode 0700) and `--token-file <path>` (a regular
144
+ file you own, mode 0600, holding 43 base64url characters); the server
145
+ refuses to start otherwise, and refuses `--port`. The dev harness
146
+ (`renderer/harness-server.mjs`) takes `--api-socket <path>
147
+ --token-file <path>` in place of `--api <url>` and prints its own URL,
148
+ with a token of its own the page sends; `harness.html`'s `?api=` mode is
149
+ gone. The steps are in `packages/desktop/README.md`.
150
+
151
+ - **The Desktop no longer appends the soul's role to a name you type.** In
152
+ the spawn dialog, a typed name goes to OATS as typed, in lowercase:
153
+ `desktop-improvements` stays `desktop-improvements`, and
154
+ `Pricing-Page-Lead` becomes `pricing-page-lead`. The soul is shown beside
155
+ the instance. What to name an instance is oats.core's rule (oats-souls,
156
+ "Name the instance"): `<descriptive>-<role>`, the role being the
157
+ instance's role in your coordination. The Name field's example now reads
158
+ "e.g. pricing-page-lead". The 64-character limit applies to the typed name
159
+ itself. A spawn on a server takes the typed name the same way. With an
160
+ OATS older than 0.26.0 on either side, what you type is still a purpose,
161
+ named `<soul>-<purpose>` ([Desktop](../desktop.md)).
162
+
163
+ - **`oats.framework` 1.25.0: `oats.core` 2.13.0 and `oats.setup` 2.15.2.**
164
+ - `oats.core`'s `/oats-souls` and `/oats-operate` name an instance
165
+ `<descriptive>-<role>`, with its role in the coordination last and
166
+ nothing appended, at most five words. A suggested name follows the same
167
+ form from OATS 0.69.18.
168
+ - `oats.setup`'s `/oats-host-delivery` says that, from oats.aweb 1.40.0, a
169
+ home the wake broker delivers to is refused at spawn and at each start
170
+ while no broker runs. `/oats-onboarding` names `oats.okf` 6.0.3, the
171
+ release the catalog pins.
172
+
173
+ No capability needs a newer OATS.
174
+
175
+ - **A lifecycle command is refused on a home its user does not own.**
176
+ `oats session start` (and a resume), `oats instance stop`, `oats retire`
177
+ and `oats instance upgrade` run what a home contains: its hooks, its
178
+ harness, the Git of its repositories. Run as another user they would lend
179
+ that user's authority to whoever can write the home. Each now answers
180
+ `E_HOME_NOT_OWNED` before it writes anything when the user it runs as does
181
+ not own the home, with the two uids in `details` and the command to run
182
+ instead. Root is refused like any other user. This is rule 3 of the
183
+ [trust model](../trust-model.md#the-line), held by the kernel.
184
+
185
+ - **oats.core names an instance for its role in your coordination, not for
186
+ its soul.** `oats-souls` "Name the instance" now says: `--name
187
+ <descriptive>-<role>`, where the role is the new instance's role in your
188
+ coordination as your landing rules and coordination skills name it
189
+ (`lead`, `developer`, `reviewer`), or one word for what it does when there
190
+ is no coordination; at most five words; nothing appended, since the soul is
191
+ shown beside the name. It no longer tells agents to end a name in the last
192
+ word of the soul's name (`desktop-improvements-developer` for a lead's
193
+ developer, not `desktop-improvements-expert` for any expert soul). A task
194
+ written for a spawn states the new instance's role in its first lines,
195
+ because a suggested name reads it from there. `oats-operate` "Naming" points
196
+ at that rule. `--purpose` (`<soul>-<purpose>`) and the numbered fallback are
197
+ unchanged: schedules and triggers still name their runs that way. An
198
+ instance spawned with an older oats.core keeps the old rule until it is
199
+ respawned or its package modules are upgraded (`oats instance upgrade`).
200
+
201
+ - **The official catalog pins oats.okf 6.0.3** (from 6.0.2), and OATS's own
202
+ workspace takes it. A lock that a recreated container left in a host
203
+ cache can now be released by hand with `oats okf unlock --lock PATH
204
+ --token TOKEN --host-gone HOST`, naming the owner's host exactly; nothing
205
+ releases it on its own or by age. A concept merged without its id under an
206
+ old node no longer refuses every proposal on its base (`W_ID_MISSING`), and
207
+ the subject verbs warn `W_BASE_INVALID` on a base that fails validation
208
+ instead of saying nothing. The generated mirror under `mirrors/oats-okf*`
209
+ is finalized from the v6.0.3 tag
210
+ ([oats.okf's CHANGELOG](https://github.com/oats-project/oats-okf/blob/v6.0.3/CHANGELOG.md)).
211
+
212
+ - **A suggested name now ends in the role the task gives.** `oats spawn
213
+ --suggest-name` (a preview or an apply) and `oats instance suggest-name` ask
214
+ the model for the whole name, `<work>-<role>`, with the role last, as the
215
+ task gives it. The kernel keeps that name: nothing appends the soul's role
216
+ any more. A reply for `oats-engineering-expert` of `pricing-page-lead` names
217
+ the instance `pricing-page-lead`, not `pricing-page-lead-expert`. Over five
218
+ words, or over 64 characters, the descriptive words nearest the role are
219
+ dropped, and the role is always kept. A one-word reply is `invalid-reply`,
220
+ and the instance is numbered as before. The JSON and the reasons are
221
+ unchanged ([The suggested name](../desktop-cli-api.md#the-suggested-name-feature-spawn-suggest-name)).
222
+ - **`oats instance suggest-name --soul` no longer affects the name.** It is
223
+ optional now. When given, it is still checked as a soul name's shape
224
+ (`E_BAD_ARGS`), because installed Desktops send it.
225
+
226
+ - The team container starts a persistent wake broker before opening SSH or
227
+ resuming agents. Its supervisor reports broker exits and stops host run
228
+ before the broker, keeping delivery available while agents drain.
229
+ - Host-run shutdown gives active launches 10 seconds to finish, then fences
230
+ new admissions and cancels owned work within a further 5-second phase
231
+ before stopping agents. Interrupted launches retain their conservative
232
+ unknown/reconcile accounting. The container still needs a 45-second stop
233
+ window; the runtime's final kill is a failure boundary, not a clean stop.
234
+
235
+ - **OATS's own copy of the engineering template moves to template-v3.1.1: the
236
+ lead leads the whole effort and delegates well.** This changes the texts
237
+ this workspace's own souls are composed from, not the kernel or any package.
238
+ - An expert leads its effort and decides who does each piece. "Build it
239
+ yourself by default" is gone: the cases in `/plan-and-spec` decide, and
240
+ neither is the default. Its briefing now says what an effort is and where
241
+ it ends.
242
+ - A helper is usually an expert, of the soul whose knowledge the task
243
+ needs, the lead's own included. A developer or the code reviewer gets
244
+ only a task about a named piece of code, and the code reviewer no longer
245
+ reads a plan or a design in prose.
246
+ - A lead may keep a standing specialist: a child that stays for the effort
247
+ in one area, one closed task at a time, retired when the plan has no more
248
+ work there. At most three at once.
249
+ - Exploration is a task once it has bounds: the decision it serves, where
250
+ to look, when to stop and what to send back.
251
+ - The dispatcher says "one effort, one lead".
252
+ - After a change to the landing rules, a lead tells all its running
253
+ children, a standing specialist included, not only its developers
254
+ (template-v3.1.1).
255
+
256
+ A running instance keeps the texts it was spawned with; a new spawn takes
257
+ these. `capabilities/TEMPLATE-RELEASE` records the release and its commit.
258
+
259
+ - **OATS's own copy of the engineering template moves to template-v3.1.3:
260
+ instances are named for their task and role, and no child runs below a
261
+ model floor.** This changes the texts this workspace's own souls are
262
+ composed from, not the kernel or any package.
263
+ - Every instance a coordination text spawns is named `<task>-<role>` with
264
+ `--name`: the task first, and last the role it plays in the effort (lead,
265
+ developer, reviewer, helper, specialist, maintainer, dispatcher), never
266
+ its soul, which the sidebar already shows. Five words at most, the role
267
+ included. A name is used once: when it is taken, the task's part gets
268
+ more specific, a later review round carries its number
269
+ (`<change>-r2-reviewer`), and a retired maintainer's successor puts its
270
+ count before the role (template-v3.1.2, template-v3.1.3).
271
+ - The landing rules set a floor for the models children run on, OATS
272
+ children and native subagents alike: a Claude model of the Opus tier or
273
+ above, an OpenAI model of the Sol tier or above, and in any other family
274
+ its strongest tier. The floor comes before model diversity, and it binds
275
+ the model a child would actually launch on: a soul's default or a
276
+ machine's `souls.launch` override below it is not used, and the parent
277
+ tells its person once. The template leaves the floor to each
278
+ organisation; this is OATS's answer (template-v3.1.3).
279
+
280
+ A running instance keeps the texts it was spawned with; a new spawn takes
281
+ these. `capabilities/TEMPLATE-RELEASE` records the release and its commit.
282
+ The catalog's rows for the research and the scientific research templates
283
+ move to template-v2.1.2, which carry the same two changes.
284
+
285
+ ## Fixed
286
+
287
+ - **`oats worktree add`'s `E_BRANCH_EXISTS` carries its remedy when it loses
288
+ a race too.** When another `add` or another git makes the branch between
289
+ the check before the tree is made and this add's `git switch -c`, the
290
+ refusal's `details` now carry `clone` and `remedy` (`<instance>/<branch>`)
291
+ beside `branch`, and its message names the remedy, as the earlier check's
292
+ always did. Both are built in one place, so they stay the same. The change
293
+ is additive. The [errors of `oats worktree add`](../desktop-cli-api.md#oats-worktree)
294
+ now also say that a racing `add` can end in either code: a switch that
295
+ meets the branch's ref lock while another git holds it answers
296
+ `E_GIT_FAILED` with Git's message, because a lock left by a git that
297
+ crashed looks the same and the branch does not exist yet. A caller that
298
+ retries once the branch exists gets `E_BRANCH_EXISTS`, with its remedy
299
+ (oats-project/oats#1865).
300
+
301
+ - Linux lock holders and readers use the kernel boot UUID consistently,
302
+ including SSH commands and the entrypoint sharing a container's PID
303
+ namespace. Unmarked PID sandboxes keep the host's boot string; holder
304
+ liveness still requires a visible pid, without cross-namespace translation.
305
+ Historical qualified UUIDs remain compatible with visible live holders across
306
+ upgrades. Crash budgets and refusals carry across same-kernel container
307
+ restarts; successful restores after a host stop neither consume nor reset
308
+ that budget and cannot be suppressed by its ceiling. A validated
309
+ current-start host-stop timestamp excludes downtime from the in-boot
310
+ eligibility gap, preserving clean restores after more than 24 hours;
311
+ other loss/refusal guards remain. See
312
+ [Session recovery](../execution-targets.md#which-losses-come-back).
313
+
314
+ - **A routed spawn whose `oats` on the server was killed can be retried
315
+ safely.** When the server's `oats` ended without an answer
316
+ (`E_REMOTE_ENVELOPE`) the error did not carry the decision and the key of
317
+ the attempt, so the same spawn run again created a second instance. It now
318
+ carries them as a dropped link (`E_SSH`) does: the message ends with the
319
+ fix, and `--json` has `error.details: {decision, idempotencyKey, fix}`.
320
+
321
+ ## Removed
322
+
323
+ - **`OATS_DESKTOP_PORT`.** The Desktop's backend has no port to choose: it
324
+ listens on the private socket the app makes for it. A launch that still sets
325
+ the variable, to any value, gets one line on stderr saying that it is ignored.
326
+
327
+ - **Installing the kernel no longer installs pi's aweb extension and its
328
+ harness dependencies.** The kernel never imported `@awebai/pi`; the aweb
329
+ capability installs that extension into pi separately. The pi SDK remains
330
+ a development dependency for adapter tests, at its existing version.
331
+
332
+ - **The 27 pre-workspace refusal exports in `lib/packages.mjs` are gone.**
333
+ Their implementations were removed in 0.25.0; the 26 function shims and
334
+ `REQUIREMENT_MANAGERS` proxy only threw `E_REMOVED`. Old named imports now
335
+ fail at module loading; namespace imports no longer contain those names.
336
+ Use workspace `packages:` plus `oats sync`; capability requirements and
337
+ configuration belong to their provider, not the removed
338
+ package-install/config-merge APIs. The same-named live APIs in
339
+ `lib/resolve.mjs` (`lockedPackageCapabilities`) and `lib/core.mjs`
340
+ (`packageSpecIdentity`) remain available. See the
341
+ [package module contract](../design/2026-09-23-workspace-module-contracts.md#43-trust-and-removed-apis).
342
+
343
+ ## Documentation
344
+
345
+ - **What the capability trust check checks.** [Capabilities](../capabilities.md#mental-model)
346
+ and the kernel's own comment now say that trust is decided where the
347
+ workspace declares a member or a package, and that the kernel's later check
348
+ only confirms that what it runs is the copy made at spawn. The
349
+ [trust model](../trust-model.md#the-line) names the one piece of the package
350
+ that runs as root, the harness-credential receiver, and why rule 3 does not
351
+ cover it. No behaviour changes.
352
+
353
+ - **[The trust model](../trust-model.md) says who OATS trusts with what.**
354
+ Everything that runs as one operating-system user is one trust group, the
355
+ kernel included. The page gives the five rules that follow, what OATS does
356
+ not promise inside a group, and which keys are held outside it.
357
+ [The team container](../container.md#one-team-one-trust-group) now states
358
+ in full that a container is the unit of compromise and holds one team.
@@ -0,0 +1,172 @@
1
+ # OATS 0.69.19
2
+
3
+ The official catalog pins oats.aweb 1.42.1, which makes retained seats safer
4
+ and shortens the always-loaded messaging instructions, and oats.framework
5
+ 1.25.2. Instances in `workspace` and `directory` mode can make extra trees of
6
+ their own for repository work. `oats host run` runs the resume sweep each
7
+ minute, and the sweep retries a refused start and counts a home's starts per
8
+ hour. The Desktop's sidebar lists instances newest first. oats.okf stays
9
+ 6.0.3.
10
+
11
+ ## Upgrade
12
+
13
+ - **Either order of the Desktop and the CLI works** from a Desktop newer than
14
+ 0.69.17 ([Either order works](../upgrading.md#either-order-works)). A
15
+ Desktop of 0.69.17 or older still goes first.
16
+ - **Package pins:** oats.aweb 1.42.1 (from 1.41.0) and oats.framework 1.25.2
17
+ (from 1.25.0). oats.okf stays 6.0.3. `oats sync` takes them; the two oats.aweb
18
+ steps below apply only where they match.
19
+ - **A retained seat reads its aweb service only from its own record.** If
20
+ you set `OATS_AWEB_URL` for a retained seat, record the server in the seat
21
+ with `aw workspace connect --service <server>`, run in the seat's parent
22
+ directory, then unset the variable. A seat whose `workspace.yaml` already
23
+ names its server is unchanged.
24
+ - **A non-boolean `identity.e2ee` or `identity.takeOver` is refused** at spawn
25
+ and start. `true`, `false` and the strings `"true"`/`"false"` are accepted,
26
+ and an empty value reads as unset. Set any other value to `true` or `false`.
27
+ - **Scripts that read `oats session resume --json`:** the row reason
28
+ `refused-this-boot` is gone. A refused start waiting for its next attempt
29
+ is `start-refused-retrying`, and `keeps-getting-lost` now means 3 starts in
30
+ the last hour (details under Changed). The Desktop doesn't depend on these
31
+ reasons.
32
+ - **Respawn instances** to take the shorter aweb text and the extra-trees
33
+ briefing of the `workspace` and `directory` modes: a running instance keeps
34
+ the text it was composed with.
35
+
36
+ ## Added
37
+
38
+ - **Team image acceptance in CI.** Pull requests now build the team agent image
39
+ from their exact head commit and run the existing container acceptance script
40
+ on an amd64 runner with a private Compose fixture and no inference credentials.
41
+ Release image publication is prepared after the OATS release, by digest with an
42
+ exact release retention tag. The run and release notes record the immutable
43
+ reference. Publication remains disabled pending the registry decision and
44
+ requires a stable OATS release tag of at least 0.69.18 plus a committed final
45
+ aw image pin of at least 1.36.59.
46
+
47
+ - Manual verification of an image built with its selected commit's own packed
48
+ kernel, with exact installed-file paths, sizes, modes and hashes checked
49
+ against HEAD. A separate proof compares the default installed payload with
50
+ and without the read-only build-context mount. Packed mode remains manual
51
+ until the compatible image baseline lands; publication stays disabled.
52
+ With the committed baseline, the packed job refuses; positive real
53
+ packed-image acceptance is **NOT RUN** until that compatible baseline lands.
54
+
55
+ ## Changed
56
+
57
+ - **The catalog pins oats.aweb 1.42.1** (from 1.41.0). 1.42.0 is never
58
+ pinned: a comment in it named the kernel's private module, which the mirror
59
+ check refuses. 1.42.1 requires OATS >=0.68.0, the aw floor stays 1.36.33,
60
+ and the tested aw is 1.36.58. Most of
61
+ the release is about retained seats: an atomic seat lock, a lock held on
62
+ another host refuses with its release, a killed or failed spawn never
63
+ deletes the standing identity's workspace, and a seat with no membership of
64
+ its team is refused before any effect. The captured-execution variables are
65
+ now ignored, with one warning each. The always-loaded messaging
66
+ instructions are shorter, and new spawns get the new text.
67
+
68
+ - **The Desktop's Add machine dialog gives an invented host as its example.**
69
+ The host field's placeholder now reads "ssh host alias, e.g. devbox"; it
70
+ named one deployment's own machine. Nothing else in the dialog changes.
71
+
72
+ - **The `directory` work mode teaches extra trees.** Its briefing granted
73
+ none, while the instance-boundary block says repository work happens "there,
74
+ or in the extra trees your mode block grants", and `oats worktree add`
75
+ already worked from a directory home. `./work` stays an owned directory
76
+ that never becomes a repository; repository work that needs a branch goes in
77
+ an extra tree of the instance's own, with the same "Extra trees" section as
78
+ the `workspace` briefing:
79
+ `oats worktree add --purpose <p> --branch <b> --base <remote-branch> --repo <repo>`.
80
+ `--repo` is always named: the home's recorded repository is configuration
81
+ context, the deployment directory by default, so `add` without it is
82
+ refused there (`E_CLONE_MISSING`). A directory instance's `TASK.md` says the
83
+ same ("Work in ./work; do repository work only in your extra trees.")
84
+ ([work modes](../souls-and-instances.md#directory--independent-execution)).
85
+ Existing homes keep the briefing they were composed with; a new spawn picks
86
+ this one up.
87
+
88
+ - **`oats.framework` 1.25.2: `oats.core` 2.13.2** (through 1.25.1).
89
+ `oats.core`'s `/oats-operate` says that `workspace`- and `directory`-mode
90
+ instances can make extra trees too: work that needs a branch goes in an
91
+ extra tree of the instance's own, made with `oats worktree add --repo
92
+ <repo>`. Member clones stay read-only, and a directory instance's `./work`
93
+ never becomes a repository.
94
+
95
+ No capability needs a newer OATS: `oats worktree add --repo` has worked
96
+ from those homes since OATS 0.49.0.
97
+
98
+ - **`oats host run` runs the resume sweep each minute, not only at its
99
+ start.** An agent whose session is lost while the host runs (its harness
100
+ crashed or was killed) is started again by the sweep of the next minute,
101
+ within the sweep's own bounds: at most 3 starts of a home in an hour, a
102
+ refused start retried with backoff, and a home given up after 3 such hours
103
+ in a row. Before, a container that stayed up never started a lost agent
104
+ again; only a restart of the container did.
105
+
106
+ A home the sweep started counts as seen running for that start. A home
107
+ that is lost again within the minute, before any read saw it running, is
108
+ therefore started again and counted, not left as `not-seen-recently`.
109
+
110
+ The sweep replaces the listing `oats host run` ran each minute, and records
111
+ what that listing recorded. A sweep that still runs at the next minute is
112
+ not run beside itself. Progress says a sweep only when its outcomes differ
113
+ from those of the sweep before. The answer's `sweep` is the first sweep's.
114
+ Stopping is unchanged: a sweep that runs gets the same 10 seconds, and the
115
+ admission fence stops its further starts.
116
+
117
+ - **`oats session resume` tries a refused start again, and counts a home's
118
+ starts per hour.** A start the sweep ran and that was refused (a launch
119
+ variable not set, no wake broker running yet) launched nothing and says how
120
+ the host was at that moment. It no longer answers the loss for good: the
121
+ sweep tries that home again no sooner than 1 minute later, doubling to 15
122
+ minutes at most, until the loss is 24 hours old. A home that keeps getting
123
+ lost is still started at most 3 times, now in an hour instead of in a boot,
124
+ and a sweep starts it again when the oldest of those starts is an hour old.
125
+ A home that uses up its starts 3 hours in a row is given up until a person
126
+ starts it.
127
+ Both the count and the delays are kept for one boot. On upgrade, a home's
128
+ count of starts for the current boot begins at zero once: the earlier
129
+ kernel's note holds no start times.
130
+
131
+ **Contract change for clients of `oats session resume --json`**
132
+ ([the machine sweep](../desktop-cli-api.md#the-machine-sweep-oats-session-resume)):
133
+ - the row reason `refused-this-boot` is no longer emitted. A refusal that
134
+ is waiting for its next attempt is `start-refused-retrying`, with the
135
+ refusal's `code` and `message`;
136
+ - `start-refused`, `start-refused-retrying` and `keeps-getting-lost` rows
137
+ carry `nextAttemptAt`, an ISO time (not on a host without a boot id,
138
+ where nothing is noted);
139
+ - `keeps-getting-lost` keeps its name and now means 3 starts in the last
140
+ hour, not in this boot. It is final only without `nextAttemptAt`: after
141
+ 3 such hours in a row;
142
+ - a refused start and `keeps-getting-lost` no longer make later sweeps
143
+ answer the home `not-seen-recently`.
144
+
145
+ - **The Desktop's sidebar lists instances newest first.** The instance tree
146
+ is in spawn order, newest on top, instead of by name, at every level: a
147
+ group of related instances by its first instance, the children under a
148
+ parent the same way. Spawning a child doesn't move its group, and starting
149
+ or stopping an instance still moves nothing. The TUI's list and the command
150
+ palette's never-focused rows follow the same order.
151
+
152
+ - Release image preparation installs the exact kernel version just published,
153
+ preserves unrelated committed lock entries and retains the generated inputs.
154
+ Acceptance verifies the installed version before registry login. Publication
155
+ remains disabled; its prepared path adds only the exact release retention tag,
156
+ refuses tag conflicts and records an immutable digest receipt with explicit
157
+ build/startup coverage and unrun agent and containment checks.
158
+
159
+ - **The `workspace` work mode teaches extra trees.** Its briefing no longer
160
+ lists worktrees among the Git operations it forbids, which contradicted the
161
+ instance-boundary block ("repository work happens there, or in the extra
162
+ trees your mode block grants"). Member clones stay read-only through
163
+ `./work`; work that needs a member's branch goes in an extra tree of the
164
+ instance's own, made with
165
+ `oats worktree add --purpose <p> --branch <b> --base <remote-branch> --repo <member>`,
166
+ which moves none of the clone's refs. `--repo` is always named in this mode:
167
+ the home's recorded repository is the deployment directory, so `add` without
168
+ it is refused (`E_CLONE_MISSING`). A workspace instance's `TASK.md` says the
169
+ same. What work an instance takes on stays its role's and its task's call
170
+ ([work modes](../souls-and-instances.md#workspace--cross-repo-coordinator)).
171
+ Existing homes keep the briefing they were composed with; a new spawn picks
172
+ this one up.
package/docs/servers.md CHANGED
@@ -246,7 +246,7 @@ symlinks. Neither the caller's command nor stdin chooses a destination path.
246
246
  ## Connect a machine
247
247
 
248
248
  ```bash
249
- oats server connect altair-aweb --ssh altair --dir '~/acme' --install-oats
249
+ oats server connect devbox-aweb --ssh devbox --dir '~/acme' --install-oats
250
250
  ```
251
251
 
252
252
  Run from a deployment, `server connect` puts that deployment's workspace on
@@ -508,7 +508,9 @@ carries it as `--name`; the answer keeps the preview's `naming`. This needs
508
508
  the server's `spawn-suggest-name` and `spawn-name` too.
509
509
 
510
510
  - **A link that fails under the second call** (a lost connection, a
511
- timeout) is `E_SSH`, and the server may have started the spawn. The
511
+ timeout) is `E_SSH`, and a server `oats` that ends without an answer (it
512
+ was killed) is `E_REMOTE_ENVELOPE`. Either way the server may have started
513
+ the spawn. The
512
514
  message ends with the fix, and `--json` carries it:
513
515
  `error.details: {decision, idempotencyKey, fix}`. Run the same spawn again
514
516
  with `--expect-decision <decision.revision> --idempotency-key
@@ -567,7 +569,7 @@ registration.
567
569
  **Capability commands.** Any capability command routes with `--server`:
568
570
 
569
571
  ```bash
570
- oats aweb setup --join aweb --invite-stdin --soul dev --server altair-aweb < invite.txt
572
+ oats aweb setup --join aweb --invite-stdin --soul dev --server devbox-aweb < invite.txt
571
573
  ```
572
574
 
573
575
  The host runs the same argv, minus `--server <id>` (or `--server=<id>`;