@awebai/oats 0.69.17 → 0.69.18

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 (52) hide show
  1. package/README.md +1 -1
  2. package/bin/oats.mjs +14 -13
  3. package/docs/capabilities.md +7 -0
  4. package/docs/container.md +172 -18
  5. package/docs/design/2026-09-23-workspace-module-contracts.md +8 -2
  6. package/docs/desktop-cli-api.md +73 -33
  7. package/docs/desktop.md +40 -18
  8. package/docs/execution-targets.md +36 -33
  9. package/docs/implementation.md +7 -6
  10. package/docs/integrations.md +2 -2
  11. package/docs/knowledge.md +5 -5
  12. package/docs/official-catalog.md +7 -7
  13. package/docs/packages.md +13 -13
  14. package/docs/release-lane.md +24 -19
  15. package/docs/release-notes/v0.69.18.md +358 -0
  16. package/docs/servers.md +3 -1
  17. package/docs/souls-and-instances.md +18 -16
  18. package/docs/trust-model.md +119 -0
  19. package/docs/upgrading.md +39 -19
  20. package/docs/workspaces.md +3 -3
  21. package/lib/command-flags.mjs +1 -1
  22. package/lib/core.mjs +24 -9
  23. package/lib/errors.mjs +1 -1
  24. package/lib/home-owner.mjs +25 -0
  25. package/lib/host-run-admission.mjs +21 -0
  26. package/lib/host-run-child.mjs +31 -0
  27. package/lib/host-run-work.mjs +150 -0
  28. package/lib/host-run.mjs +20 -11
  29. package/lib/instance-naming.mjs +26 -44
  30. package/lib/packages.mjs +0 -43
  31. package/lib/pi-bridge.mjs +18 -6
  32. package/lib/schedule.mjs +5 -3
  33. package/lib/servers.mjs +4 -3
  34. package/lib/session-end.mjs +9 -0
  35. package/lib/session-resume.mjs +19 -9
  36. package/lib/session-seen.mjs +13 -8
  37. package/lib/triggers.mjs +3 -1
  38. package/lib/worktree.mjs +5 -2
  39. package/package-catalog.json +3 -3
  40. package/package.json +2 -2
  41. package/packages/client/above-tested-notice.mjs +30 -0
  42. package/packages/client/above-tested.mjs +225 -0
  43. package/packages/client/cli-locator.mjs +67 -52
  44. package/packages/client/deployment-label.mjs +4 -4
  45. package/packages/client/instance-name.mjs +5 -29
  46. package/packages/client/session-start.mjs +31 -3
  47. package/packages/client/workspace-choices.mjs +1 -1
  48. package/packages/client/workspace-views.mjs +1 -1
  49. package/packages/record/README.md +10 -8
  50. package/packages/record/lib/process-identity.mjs +14 -36
  51. package/packages/tui/lib/read.mjs +19 -3
  52. 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.
package/docs/servers.md CHANGED
@@ -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
@@ -328,23 +328,25 @@ oats spawn release-manager --provider oats.aweb identity.source=/abs/path/to/ret
328
328
  ```
329
329
 
330
330
  An instance is named exactly `--name <slug>`, or `<soul>-<purpose>` with
331
- `--purpose`; with neither, the kernel numbers it. The convention for a name a
332
- person or an agent chooses is `<descriptive>-<role>` through `--name`: a few
333
- words for the instance's work, then the soul's role, the last word of the
334
- soul's name after any package qualifier (`--name desktop-improvements-expert`
335
- for an `oats-desktop-expert`). `--purpose` derives the name from the soul, for
331
+ `--purpose`; with neither, the kernel numbers it. A typed `--name` is used
332
+ exactly as given. How a person or an agent chooses one is the oats.core
333
+ skill oats-souls, "Name the instance"
334
+ ([its rule](../oats-package/capabilities/oats-core/skills/oats-souls/SKILL.md#name-the-instance)).
335
+ `--purpose` derives the name from the soul, for
336
336
  automations and scripts that know only the soul and a purpose.
337
337
  Names are unique per deployment (a workspace-model deployment has one agents
338
338
  root): a derived name in use gets `-2`, `-3`…; an explicit `--name` in use is
339
- refused (`E_INSTANCE_NAME_TAKEN`). The Desktop's spawn dialog adds the role to
340
- a typed name.
339
+ refused (`E_INSTANCE_NAME_TAKEN`). The Desktop's spawn dialog sends a typed
340
+ name as typed, lowercased.
341
341
  `oats spawn <soul> --preview --suggest-name --task-file <f>` asks the soul's
342
- own harness for the descriptive words, from the task, in one call that starts
342
+ own harness for the whole name, `<work>-<role>` with the role as the task
343
+ gives it, from the task, in one call that starts
343
344
  none of the user's MCP servers, hooks, plugins or extensions. Claude Code's
344
345
  built-in plugins, the host's managed-policy hooks and pi's credential commands
345
346
  are the stated exceptions; a claude login through `apiKeyHelper` is not read,
346
347
  so that user's name stays numbered (`harness-failed`). The preview then answers for
347
- `--name <descriptive>-<role>`, de-duplicated the same way. On claude and pi
348
+ `--name <that name>`, de-duplicated the same way; nothing appends the soul's
349
+ role. On claude and pi
348
350
  only; any other harness, and any failure of the call, leaves the name numbered
349
351
  and says why
350
352
  ([The suggested name](desktop-cli-api.md#the-suggested-name-feature-spawn-suggest-name)).
@@ -355,16 +357,16 @@ at spawn (`.oats-background.json`), so a later soul edit moves no existing
355
357
  instance; `oats instance background <instance> on|off` does. Both flags
356
358
  together are `E_BAD_ARGS`.
357
359
  An apply takes `--suggest-name` too (without `--name` or `--purpose`): the
358
- machine that spawns makes the same call, names the instance
359
- `<descriptive>-<role>`, de-duplicated the same way, and numbers it on any
360
+ machine that spawns makes the same call, names the instance with the reply's
361
+ name, de-duplicated the same way, and numbers it on any
360
362
  failure; the result's `naming` says which, and the apply may take up to 20 s
361
363
  longer ([On an apply](desktop-cli-api.md#on-an-apply-feature-spawn-apply-suggest-name)).
362
364
  Without the flag an apply is numbered, as before.
363
- `oats instance suggest-name --soul <soul> --task-file <f>` asks for the same
364
- words on this machine for a spawn that will land on another (the Desktop's
365
- dialog, spawning through `--server`): the soul only gives the role and needn't
366
- exist here, nothing is written or reserved, and the name is not made unique,
367
- which the landing host does
365
+ `oats instance suggest-name --task-file <f>` asks for the same name on this
366
+ machine for a spawn that will land on another (the Desktop's dialog, spawning
367
+ through `--server`): nothing is written or reserved, and the name is not made
368
+ unique, which the landing host does. `--soul <soul>` is optional: when given it
369
+ is checked as a soul name's shape and does not change the name
368
370
  ([A name for a spawn elsewhere](desktop-cli-api.md#a-name-for-a-spawn-elsewhere-oats-instance-suggest-name)).
369
371
 
370
372
  From a deployment (where `oats-local.yaml` is), a spawn: reads the local file →
@@ -0,0 +1,119 @@
1
+ # Trust model
2
+
3
+ Everything that runs as one operating-system user is one trust group, the
4
+ kernel included. OATS draws no line inside a user, and must never run with
5
+ more authority than the agents whose homes it reads.
6
+
7
+ ## The parties
8
+
9
+ - The **operator**: the person, or the control plane acting for them, who
10
+ decides which agents exist and with what configuration.
11
+ - The **kernel**: `oats` commands and `oats host run`. It has no authority of
12
+ its own. It runs as whoever started it.
13
+ - An **agent**: a harness process and everything it starts. It can write its
14
+ own home, and anything else its user can write.
15
+ - A **capability**: code copied into an agent's home at spawn, which the
16
+ kernel runs as hooks and commands.
17
+
18
+ ## The line
19
+
20
+ The line is the user boundary and, for a hosted team, the container around
21
+ it ([container.md](container.md)). Inside it nothing protects one agent from
22
+ another, or the kernel's own state from an agent: an agent can read and write
23
+ what the kernel reads and writes.
24
+
25
+ 1. **A trust group is the unit of compromise.** If one agent in it is
26
+ subverted, treat every agent, seat and credential in it as subverted.
27
+ 2. **One team, one trust group.** Agents that must not be able to read each
28
+ other's identities or affect each other's work do not share a container or
29
+ a user. Nothing in OATS makes that safe. A container holds one team, never
30
+ several.
31
+ 3. **The kernel takes no authority across the line.** It is never run as
32
+ root, as a different user, or on another machine against a home that an
33
+ agent on the far side of the line could write. A command given
34
+ `--server` runs `oats` on the home's side
35
+ ([servers.md](servers.md)); the Desktop and the TUI start the local `oats`
36
+ and run no kernel code of their own on what a remote home contains.
37
+ The kernel holds itself to this: a start, a resume, a stop, a retire or
38
+ an upgrade of a home that the user running it does not own is refused
39
+ with `E_HOME_NOT_OWNED` before anything is written, root included.
40
+ One piece of the package does run as root, and it is outside this rule:
41
+ the harness-credential receiver `share/oats-login-receive`
42
+ ([servers.md](servers.md#harness-credentials)). It runs under a forced
43
+ command, reads only its standard input, writes only the credential file
44
+ its root-owned configuration names and touches no home, so it is not the
45
+ kernel acting on a home.
46
+ 4. **An agent's home is untrusted as data, and trusted as code only inside
47
+ its own group.** The kernel executes what it finds there, such as
48
+ lifecycle hooks and a module's commands, because doing so gives the agent
49
+ nothing it does not already have. What it finds there decides nothing
50
+ about another group.
51
+ 5. **Inside a group OATS protects the agents' work, not the group's
52
+ secrets.** Locks, claims, recovery copies and the Git hardening at
53
+ retirement exist so that a kill, a race or a hostile repository
54
+ configuration does not lose or corrupt work. They are robustness, not
55
+ access control.
56
+
57
+ ## What OATS does not promise
58
+
59
+ Inside one trust group, none of these hold:
60
+
61
+ - That an agent cannot read another agent's seat key, the team's Claude
62
+ token, the launch configurations, the schedule registry or sshd's host
63
+ keys.
64
+ - That an agent cannot stop sshd, `oats host run`, the wake broker or its
65
+ supervisor.
66
+ - That a capability is confined to the outputs it declares.
67
+ - That a command which reads is one which runs nothing.
68
+ `oats readiness --home <home>` executes the home's module commands, and
69
+ today it gives them the environment of whoever runs the read, without that
70
+ caller's `OATS_`, `OAS_` and `PI_` identity variables. Run it for a home of
71
+ another trust group only from an environment that holds nothing the home's
72
+ agent should not have.
73
+ - That a capability the kernel reports as trusted has been judged.
74
+ [Trust is the workspace's declaration](capabilities.md#mental-model) of a
75
+ member repo or a package. The kernel then checks that what it is about to
76
+ run is the copy made at spawn. That copy is in the agent's home, so the
77
+ check is no defence against the agent.
78
+ - That a harness's sandbox is a boundary. OATS counts none as one and relies
79
+ on none. Where a harness restricts what its agent can write, that is the
80
+ harness's property and not a promise of OATS.
81
+
82
+ ## Code from outside the group
83
+
84
+ What an agent's home runs comes from the workspace: packages, pinned by the
85
+ deployment's lock, and member repositories, which are not pinned. A member's
86
+ souls and capabilities are used at the member's latest commit, trusted by
87
+ membership ([capabilities.md](capabilities.md#mental-model)).
88
+
89
+ So the default branch of the workspace host and of every member is outside
90
+ every agent group, and it is the operator's to keep there. A commit on it
91
+ becomes the hooks and commands of the next spawn of every soul that composes
92
+ that member, in every deployment of the workspace, and of the next capability
93
+ command an operator runs on their own machine.
94
+
95
+ OATS does not enforce this. An agent holds whatever Git credential its
96
+ deployment gives it. If that credential can push to a member's default
97
+ branch, one subverted agent reaches every other team and the operator, and
98
+ rule 1 no longer bounds the loss. Give agents a credential that cannot:
99
+ branch protection that requires another identity's approval, or a repository
100
+ that is not a member of the workspace.
101
+
102
+ ## Keys outside the group
103
+
104
+ One part of the line is enforced by something other than OATS: where a
105
+ team's keys are kept. A hosted aweb team's controller key is kept by the
106
+ service, outside every agent group, and no agent can read it. That holds
107
+ today.
108
+
109
+ The aweb human-assurance design goes further. In it, the keys of a human, of
110
+ a namespace and of a team's controller will be held by a protected signer
111
+ outside every agent group. The deployment root's agent key will stay inside
112
+ the group by design, and what it can do will be bounded by its admission
113
+ policy, so that its loss is the loss of that group and of nothing above it.
114
+ The signer is not shipped.
115
+
116
+ No deployment that brings its own team has this yet. Each still holds its
117
+ team keys under the agents' user, in `~/.awid/team-keys` and `.aweb-roots`.
118
+ Under rule 1 those keys are compromised along with any agent in that group,
119
+ until they are moved to the signer.