@awebai/oats 0.69.16 → 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.
- package/README.md +1 -1
- package/bin/oats.mjs +14 -13
- package/docs/capabilities.md +7 -0
- package/docs/container.md +172 -18
- package/docs/design/2026-09-23-workspace-module-contracts.md +8 -2
- package/docs/desktop-cli-api.md +73 -33
- package/docs/desktop.md +40 -18
- package/docs/execution-targets.md +36 -33
- package/docs/implementation.md +7 -6
- package/docs/integrations.md +2 -2
- package/docs/knowledge.md +5 -5
- package/docs/official-catalog.md +7 -7
- package/docs/packages.md +13 -13
- package/docs/release-lane.md +24 -19
- package/docs/release-notes/v0.69.17.md +49 -0
- package/docs/release-notes/v0.69.18.md +358 -0
- package/docs/servers.md +3 -1
- package/docs/souls-and-instances.md +18 -16
- package/docs/trust-model.md +119 -0
- package/docs/upgrading.md +46 -21
- package/docs/workspaces.md +3 -3
- package/lib/command-flags.mjs +1 -1
- package/lib/core.mjs +24 -9
- package/lib/errors.mjs +1 -1
- package/lib/home-owner.mjs +25 -0
- package/lib/host-run-admission.mjs +21 -0
- package/lib/host-run-child.mjs +31 -0
- package/lib/host-run-work.mjs +150 -0
- package/lib/host-run.mjs +20 -11
- package/lib/instance-naming.mjs +26 -44
- package/lib/packages.mjs +0 -43
- package/lib/pi-bridge.mjs +18 -6
- package/lib/schedule.mjs +5 -3
- package/lib/servers.mjs +4 -3
- package/lib/session-end.mjs +9 -0
- package/lib/session-resume.mjs +19 -9
- package/lib/session-seen.mjs +13 -8
- package/lib/triggers.mjs +3 -1
- package/lib/worktree.mjs +5 -2
- package/package-catalog.json +3 -3
- package/package.json +2 -2
- package/packages/client/above-tested-notice.mjs +30 -0
- package/packages/client/above-tested.mjs +225 -0
- package/packages/client/cli-locator.mjs +67 -52
- package/packages/client/deployment-label.mjs +4 -4
- package/packages/client/instance-name.mjs +5 -29
- package/packages/client/session-start.mjs +31 -3
- package/packages/client/workspace-choices.mjs +1 -1
- package/packages/client/workspace-views.mjs +1 -1
- package/packages/record/README.md +10 -8
- package/packages/record/lib/process-identity.mjs +14 -36
- package/packages/tui/lib/read.mjs +19 -3
- 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
|
|
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.
|
|
332
|
-
person or an agent chooses is
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
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
|
|
340
|
-
|
|
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
|
|
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 <
|
|
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
|
-
|
|
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 --
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
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.
|