@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.
- package/README.md +1 -1
- package/bin/oats.mjs +14 -13
- package/docs/capabilities.md +8 -1
- package/docs/container.md +345 -18
- package/docs/design/2026-09-23-workspace-module-contracts.md +8 -2
- package/docs/design/2026-09-27-team-model-v2.md +2 -2
- package/docs/design/2026-09-28-automations-trust.md +1 -1
- package/docs/desktop-cli-api.md +100 -53
- package/docs/desktop.md +53 -24
- package/docs/execution-targets.md +66 -48
- package/docs/implementation.md +8 -7
- 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 +30 -23
- package/docs/release-notes/v0.69.18.md +358 -0
- package/docs/release-notes/v0.69.19.md +172 -0
- package/docs/servers.md +5 -3
- package/docs/souls-and-instances.md +51 -27
- package/docs/trust-model.md +119 -0
- package/docs/tui.md +8 -8
- package/docs/upgrading.md +45 -19
- package/docs/workspaces.md +3 -3
- package/injects/work-directory.md +27 -2
- package/injects/work-workspace.md +32 -6
- package/lib/command-flags.mjs +1 -1
- package/lib/core.mjs +26 -11
- 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 +43 -29
- 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-contract.mjs +1 -1
- package/lib/session-resume.mjs +144 -51
- package/lib/session-seen.mjs +16 -11
- package/lib/triggers.mjs +3 -1
- package/lib/worktree.mjs +5 -2
- package/package-catalog.json +3 -3
- package/package.json +4 -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/instance-presentation.mjs +2 -2
- package/packages/client/instance-tree.mjs +18 -7
- 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.
|
|
@@ -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
|
|
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
|
|
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
|
|
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>`;
|