@awebai/oats 0.69.17 → 0.69.19

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. package/README.md +1 -1
  2. package/bin/oats.mjs +14 -13
  3. package/docs/capabilities.md +8 -1
  4. package/docs/container.md +345 -18
  5. package/docs/design/2026-09-23-workspace-module-contracts.md +8 -2
  6. package/docs/design/2026-09-27-team-model-v2.md +2 -2
  7. package/docs/design/2026-09-28-automations-trust.md +1 -1
  8. package/docs/desktop-cli-api.md +100 -53
  9. package/docs/desktop.md +53 -24
  10. package/docs/execution-targets.md +66 -48
  11. package/docs/implementation.md +8 -7
  12. package/docs/integrations.md +2 -2
  13. package/docs/knowledge.md +5 -5
  14. package/docs/official-catalog.md +7 -7
  15. package/docs/packages.md +13 -13
  16. package/docs/release-lane.md +30 -23
  17. package/docs/release-notes/v0.69.18.md +358 -0
  18. package/docs/release-notes/v0.69.19.md +172 -0
  19. package/docs/servers.md +5 -3
  20. package/docs/souls-and-instances.md +51 -27
  21. package/docs/trust-model.md +119 -0
  22. package/docs/tui.md +8 -8
  23. package/docs/upgrading.md +45 -19
  24. package/docs/workspaces.md +3 -3
  25. package/injects/work-directory.md +27 -2
  26. package/injects/work-workspace.md +32 -6
  27. package/lib/command-flags.mjs +1 -1
  28. package/lib/core.mjs +26 -11
  29. package/lib/errors.mjs +1 -1
  30. package/lib/home-owner.mjs +25 -0
  31. package/lib/host-run-admission.mjs +21 -0
  32. package/lib/host-run-child.mjs +31 -0
  33. package/lib/host-run-work.mjs +150 -0
  34. package/lib/host-run.mjs +43 -29
  35. package/lib/instance-naming.mjs +26 -44
  36. package/lib/packages.mjs +0 -43
  37. package/lib/pi-bridge.mjs +18 -6
  38. package/lib/schedule.mjs +5 -3
  39. package/lib/servers.mjs +4 -3
  40. package/lib/session-end.mjs +9 -0
  41. package/lib/session-resume-contract.mjs +1 -1
  42. package/lib/session-resume.mjs +144 -51
  43. package/lib/session-seen.mjs +16 -11
  44. package/lib/triggers.mjs +3 -1
  45. package/lib/worktree.mjs +5 -2
  46. package/package-catalog.json +3 -3
  47. package/package.json +4 -2
  48. package/packages/client/above-tested-notice.mjs +30 -0
  49. package/packages/client/above-tested.mjs +225 -0
  50. package/packages/client/cli-locator.mjs +67 -52
  51. package/packages/client/deployment-label.mjs +4 -4
  52. package/packages/client/instance-name.mjs +5 -29
  53. package/packages/client/instance-presentation.mjs +2 -2
  54. package/packages/client/instance-tree.mjs +18 -7
  55. package/packages/client/session-start.mjs +31 -3
  56. package/packages/client/workspace-choices.mjs +1 -1
  57. package/packages/client/workspace-views.mjs +1 -1
  58. package/packages/record/README.md +10 -8
  59. package/packages/record/lib/process-identity.mjs +14 -36
  60. package/packages/tui/lib/read.mjs +19 -3
  61. package/skills/oats-getting-started/SKILL.md +33 -4
package/README.md CHANGED
@@ -271,7 +271,7 @@ It is optional: agents run, message each other and follow their schedules whethe
271
271
 
272
272
  3. **Answer its questions.** It asks everything in one round and lists the changes it will make to your computer; say yes to them. After that you only approve the GitHub login and type a password or token if one is asked for.
273
273
 
274
- Your agent then installs OATS, OATS Desktop and what they need. It creates a private GitHub repository for your agents' shared setup (the workspace), creates the group your agents message each other in (on [aweb](https://aweb.ai), with no sign-up), and starts the **setup expert**, an agent that adapts the defaults with you. OATS Desktop opens on it. Allow 5 to 10 minutes.
274
+ Your agent then installs OATS and what it needs, and OATS Desktop unless you decline it: the Desktop is optional, and the terminal UI (`oats tui`) or the command line work without it. It creates a private GitHub repository for your agents' shared setup (the workspace), creates the group your agents message each other in (on [aweb](https://aweb.ai), with no sign-up), and starts the **setup expert**, an agent that adapts the defaults with you. OATS Desktop, if you kept it, opens on it. Allow 5 to 10 minutes.
275
275
 
276
276
  **To join a workspace a teammate already runs,** say instead *"Join our OATS workspace at \<its GitHub repository\>, following https://github.com/oats-project/oats"*. Your teammate's agent makes you an invite, which your teammate passes to you privately; your agent tells you when to paste it.
277
277
 
package/bin/oats.mjs CHANGED
@@ -1423,11 +1423,12 @@ async function instanceUpgradeCmd(name, bail) {
1423
1423
  } catch (e) { return lifecycleFail(e, "E_UPGRADE_FAILED", { ...e.details, ...(e.plan ? { plan: e.plan } : {}), ...(e.candidates ? { candidates: e.candidates } : {}) }); }
1424
1424
  }
1425
1425
 
1426
- /** `oats instance suggest-name` (feature instance-suggest-name, awebai/oats#1490 §2): the name a spawn
1427
- * of a soul would get by --suggest-name, chosen here for a spawn that may land on another machine
1428
- * (lib/core.mjs suggestSpawnName). Never routed: --server is refused before the route dispatch. */
1426
+ /** `oats instance suggest-name` (feature instance-suggest-name, awebai/oats#1490 §2): the name a
1427
+ * --suggest-name spawn would get, chosen here for a spawn that may land on another machine
1428
+ * (lib/core.mjs suggestSpawnName). --soul is optional, shape-checked when given and unused for the
1429
+ * name. Never routed: --server is refused before the route dispatch. */
1429
1430
  async function instanceSuggestNameCmd(bail) {
1430
- const usage = "usage: oats instance suggest-name --soul <soul> (--task <t> | --task-file <f>) [--harness claude|pi] [--model <m>] [--launch-config <n>] [--dir <d>] [--json]";
1431
+ const usage = "usage: oats instance suggest-name [--soul <soul>] (--task <t> | --task-file <f>) [--harness claude|pi] [--model <m>] [--launch-config <n>] [--dir <d>] [--json]";
1431
1432
  // A flag's value as given, the empty text included (`--task ""` is an empty task, not a missing one).
1432
1433
  const value = (name) => {
1433
1434
  const i = args.indexOf(`--${name}`);
@@ -1437,7 +1438,6 @@ async function instanceSuggestNameCmd(bail) {
1437
1438
  return v;
1438
1439
  };
1439
1440
  const soul = value("soul"), task = value("task"), taskFile = value("task-file");
1440
- if (soul === undefined) return bail("E_BAD_ARGS", `--soul is required; ${usage}`);
1441
1441
  if ((task === undefined) === (taskFile === undefined)) return bail("E_BAD_ARGS", `give the task with one of --task or --task-file; ${usage}`);
1442
1442
  let text = task;
1443
1443
  if (taskFile !== undefined) { try { text = readFileSync(taskFile, "utf8"); } catch (e) { return bail("E_BAD_ARGS", `--task-file ${taskFile} cannot be read (${e.code || "error"})`); } }
@@ -5086,8 +5086,8 @@ Usage:
5086
5086
  includes the decision revision for confirmation
5087
5087
  [--suggest-name] no --name, --purpose or --expect-decision: the
5088
5088
  soul's harness, on the machine that spawns, names
5089
- the instance for its task (<descriptive>-<role>,
5090
- made unique); else it is numbered, and
5089
+ the instance for its task (the model's whole
5090
+ <work>-<role>, made unique); else it is numbered, and
5091
5091
  naming.reason says why (claude and pi); on a
5092
5092
  preview or an apply
5093
5093
  [--expect-decision <rev>] bind apply to the previewed decision; drift refuses
@@ -5249,13 +5249,14 @@ Usage:
5249
5249
  record that this instance does the same work as
5250
5250
  its parent (on needs a recorded parent); clients
5251
5251
  draw the parent line for it; off removes it
5252
- oats instance suggest-name --soul <soul> (--task <t> | --task-file <f>) [--harness claude|pi]
5252
+ oats instance suggest-name [--soul <soul>] (--task <t> | --task-file <f>) [--harness claude|pi]
5253
5253
  [--model <m>] [--launch-config <n>] [--dir <d>] [--json]
5254
- a name for a spawn of <soul> (only a name: it gives
5255
- the role) by this machine's harness, as a preview's
5256
- --suggest-name chooses it, not made unique (where it
5257
- lands decides that); else numbered, and naming.reason
5258
- says why. Reads only this machine's launch
5254
+ a name for a spawn by this machine's harness, as a
5255
+ preview's --suggest-name chooses it (the model's whole
5256
+ <work>-<role>), not made unique (where it lands decides
5257
+ that); else numbered, and naming.reason says why.
5258
+ --soul is optional, checked as a soul name's shape and
5259
+ not used for the name. Reads only this machine's launch
5259
5260
  configurations; writes and reserves nothing; no --server
5260
5261
  oats worktree add --purpose <p> --branch <b> --base <remote-branch> from an instance home: make the
5261
5262
  [--repo <member key|clone path>] extra tree <home>/.work-<p> on a new branch at origin's
@@ -32,6 +32,13 @@ its skills flat into `<home>/.agents/skills/<skill>/`), and the instance's `AGEN
32
32
  generated without changing the canonical soul. Nothing is installed or
33
33
  activated at a deployment.
34
34
 
35
+ Trust is decided once, where the workspace declares the member or the
36
+ package. When the kernel later reports a capability as trusted, it has
37
+ checked only that what it is about to run is the copy made at spawn and where
38
+ that copy came from. It judges nothing about the code, and the copy is in the
39
+ home its agent can write, so the check is no defence against that agent
40
+ ([trust-model.md](trust-model.md)).
41
+
35
42
  ## Manifest
36
43
 
37
44
  A self-contained package has an `oats.json`:
@@ -1181,7 +1188,7 @@ own configuration.
1181
1188
  naming the release, not with a schema error.
1182
1189
  3. The blast radius is every soul that composes the capability, on every host
1183
1190
  below the release: one capability can stop every developer soul of a
1184
- workspace from spawning, as in lfx-oats-workspace#22, where one capability
1191
+ workspace from spawning, as in lab-oats-workspace#22, where one capability
1185
1192
  took down every developer soul.
1186
1193
  4. To limit it, put the hook in a small capability composed only by the souls
1187
1194
  that need the setup.
package/docs/container.md CHANGED
@@ -8,6 +8,26 @@ then runs `oats host run`
8
8
  ([The kernel's periodic work](#the-kernels-periodic-work)). Deployment setup
9
9
  and seat admission belong to the operator.
10
10
 
11
+ ## One team, one trust group
12
+
13
+ The service runs every agent, sshd and `oats host run` as one user, so the
14
+ container is one trust group ([trust-model.md](trust-model.md)):
15
+
16
+ - **It is the unit of compromise.** If one agent in it is subverted, treat
17
+ every agent, seat and credential in it as subverted. Each agent can read
18
+ every seat under `/state/seats`, the Claude token and sshd's host keys,
19
+ rewrite the launch configurations in `/state/deploy` and the schedule
20
+ registry in `/state/home`, rewrite the wake registrations under
21
+ `/state/home/.config/aw/wake`, and stop sshd, `oats host run`, the wake
22
+ broker or its supervisor.
23
+ - **It holds one team, never several.** Agents that must not be able to read
24
+ each other's identities or affect each other's work get separate
25
+ containers. Nothing in OATS makes sharing one safe.
26
+ - **Its Git credentials must not reach the workspace's own code.** A
27
+ workspace member is used at its latest commit, so an agent that can push to
28
+ a member's default branch changes what every deployment of that workspace
29
+ runs ([trust-model.md](trust-model.md#code-from-outside-the-group)).
30
+
11
31
  ## Configuration contract
12
32
 
13
33
  The same inputs apply to a Compose service or a platform's container spec:
@@ -48,7 +68,7 @@ must succeed during the build.
48
68
 
49
69
  `libnss-wrapper` is the extra OS package needed for arbitrary UID support.
50
70
  No credentials or SSH host keys are baked in. The build context allowlist
51
- excludes everything except the image's five inputs.
71
+ excludes everything except the explicitly listed image inputs.
52
72
 
53
73
  A derived image may add reviewed OS tools with `USER root` and `RUN`, then
54
74
  restore `USER agent`. Those build steps use the system passwd/group database.
@@ -184,6 +204,97 @@ Preview runs no provider hook and does not validate a missing seat. Apply
184
204
  only after reviewing it and provisioning its seat; use the same arguments
185
205
  without `--preview`. Keep the team and controller keys outside the container.
186
206
 
207
+ ### Making a seat
208
+
209
+ `identity.source` is the legacy route of `oats.aweb`: the spawn copies an
210
+ existing aweb identity into the new home and connects it. It is the route
211
+ that works in a container today, and it stays labelled legacy until the
212
+ package has a route that admits a seat itself.
213
+
214
+ A seat is the `.aw` directory of one admitted team member. On both routes
215
+ below the seat's signing key is created in the container, over the SSH
216
+ route, so it is on `/state` and never leaves it; the team's controller key
217
+ stays outside. Which route applies depends on who holds that controller key.
218
+
219
+ **A team whose controller key the operator holds** (a self-hosted server, or
220
+ a team the operator brought). The seat asks, the controller admits it, the
221
+ seat fetches its certificate:
222
+
223
+ ```sh
224
+ # 1. In the container, once per seat. Prints the add-member command.
225
+ mkdir -p /state/seats/<alias> && cd /state/seats/<alias>
226
+ aw id team request --create-local-key --team <team>:<domain> --name <alias>
227
+
228
+ # 2. Outside the container, where the team's controller key is: run the
229
+ # printed `aw id team add-member` command. It answers a certificate id.
230
+
231
+ # 3. In the container, in the same directory:
232
+ aw id team fetch-cert --team <team> --namespace <domain> --cert-id <certificate-id>
233
+ aw workspace connect --service <the team's aweb server>
234
+ ```
235
+
236
+ An invite cannot be used here: a token made with the operator's own
237
+ controller key is redeemed only on the machine that holds that key
238
+ (`aw id team accept-invite --help`).
239
+
240
+ **A team hosted by the aweb service.** The service holds the controller key
241
+ and issues an invite token (`aw_inv_…`); the seat redeems it:
242
+
243
+ ```sh
244
+ # In the container, once per seat:
245
+ mkdir -p /state/seats/<alias> && cd /state/seats/<alias>
246
+ aw id team accept-invite <token> --name <alias>
247
+ aw workspace connect --service <the team's aweb server>
248
+ ```
249
+
250
+ The commands are as `aw` 1.36.57 documents them in its own `--help`. The
251
+ sequences have not yet been run in a container.
252
+
253
+ Before it copies or locks anything, the spawn checks five things, and
254
+ refuses the seat with its fix when one is missing:
255
+
256
+ - `signing.key`, the member's key;
257
+ - the server: `aweb_url` in `workspace.yaml` (`aw workspace connect` writes
258
+ it). The seat's service comes only from there: `OATS_AWEB_URL` is not read;
259
+ - the team: the deployment's default team, or else the active team in
260
+ `teams.yaml`;
261
+ - `teams.yaml` itself;
262
+ - a membership of that team in `teams.yaml`, matched as aw matches it. When
263
+ there is none, accept the team's invite (`aw id team accept-invite`) or
264
+ fetch its certificate (`aw id team fetch-cert`) in the seat's directory, or
265
+ make the seat's team the deployment's default.
266
+
267
+ The member's certificate file under `team-certs/` is not checked at that
268
+ point, and the seat does not work without it: the spawn copies the seat,
269
+ fails when it connects or reads the identity back, and removes the copy.
270
+
271
+ One seat serves one instance at a time. The spawn writes
272
+ `.aw-retained-seat.json` beside the seat's `.aw` and refuses a second spawn
273
+ while the first instance's home exists; retiring that instance releases the
274
+ seat. Every change of that lock is one guarded step, using two private files
275
+ beside it, `.aw-retained-seat.json.guard` and `.aw-retained-seat.json.held`.
276
+ A change that was killed can leave one of them behind. The next spawn or
277
+ take-over then refuses, naming the file and its fix, and the next retire
278
+ reports it. Nothing removes such a file automatically. Two cases need the
279
+ operator:
280
+
281
+ - **The holder's home exists and its runtime is known to be dead.** Spawn
282
+ with `identity.takeOver=true`. If that runtime is in fact alive, there are
283
+ then two seats with one key; stop the old one.
284
+ - **The holder's home is not on this host** (a home removed by hand, a volume
285
+ restored, or a home on another host that shares the seat). The spawn
286
+ refuses, naming the holder as the lock records it (instance, host, since
287
+ and home) and the release. A lock is never released by age. Once that seat
288
+ is confirmed gone, spawn with `identity.takeOver=true`, which clears the lock
289
+ with a warning, or remove the lock file the refusal names.
290
+
291
+ Retiring never revokes the member's certificate: on a server that is not the
292
+ hosted service, whoever holds the controller key removes a member
293
+ (`aw id team remove-member`). A seat's spawn that fails or is killed never
294
+ deletes the standing identity's workspace at the server: its retire releases
295
+ the lock and prints the `aw workspace connect` that binds the identity back to
296
+ its seat.
297
+
187
298
  The pinned OATS release supports this file-backed launch configuration:
188
299
 
189
300
  ```yaml
@@ -201,11 +312,50 @@ Select it with `--launch-config team-claude`. The operator provisions only a
201
312
  by every agent in the same trust group; read-only mounting does not hide it
202
313
  or narrow its authority. Never share the mount across trust groups.
203
314
 
315
+ ### After changing a credential
316
+
317
+ A resume starts an agent under the values its last start recorded. When the
318
+ value behind a reference has changed, such as a new token in
319
+ `/etc/agent-login/claude-token`, every resume of that home is refused with
320
+ `E_LAUNCH_ENV_CHANGED`, by the sweep and by hand
321
+ ([execution-targets.md](execution-targets.md#resume-after-a-shutdown)). The
322
+ agents do not come back when the container restarts, and host run's log
323
+ shows them as `refused`.
324
+
325
+ So after replacing a referenced credential, start each agent once yourself.
326
+ An ordinary start does not compare; it uses the new value and records it:
327
+
328
+ ```sh
329
+ # In the container:
330
+ oats session restart --home <abs> # an agent that runs
331
+ oats session start --home <abs> # one that is stopped
332
+ ```
333
+
334
+ An ordinary start begins a new conversation; it does not resume the earlier
335
+ one.
336
+
337
+ ### Where conversations are stored
338
+
339
+ With `CLAUDE_CONFIG_DIR: /state/home/.claude`, Claude Code writes each
340
+ session's transcript under that directory. It holds what the agents read and
341
+ wrote, tool output included: mail they opened, and the results of calls made
342
+ on their behalf.
343
+
344
+ - It is one directory for every agent of the container, and every agent can
345
+ read it ([One team, one trust group](#one-team-one-trust-group)).
346
+ - It is on `/state`, so it outlives the container and is in any copy of the
347
+ volume.
348
+ - OATS neither trims nor deletes it. Retiring an instance removes its home,
349
+ not its transcripts. The operator decides how long they are kept and
350
+ removes them.
351
+
204
352
  ## The kernel's periodic work
205
353
 
206
354
  A container has no launchd and no systemd user manager, so no timer runs
207
- the kernel's periodic work in it. The image's entrypoint does: it starts
208
- sshd in the background and then runs `oats host run`
355
+ the kernel's periodic work in it. After the entrypoint prepares NSS and
356
+ SSH host keys, an image-local Node supervisor starts `aw wake run`. It waits
357
+ for `aw wake status --json` to report `daemon_running: true` and name that
358
+ live child's PID as `daemon_pid`, then starts sshd and `oats host run`
209
359
  ([desktop-cli-api.md](desktop-cli-api.md#the-host-run-oats-host-run)), one
210
360
  foreground process that lasts as long as the container.
211
361
 
@@ -216,31 +366,36 @@ foreground process that lasts as long as the container.
216
366
  deployments the container's host schedule registry lists and lists the
217
367
  instances. With no deployment registered it ticks nothing and says so.
218
368
  - **On the runtime's SIGTERM** (`docker stop`, `docker restart`, a Compose
219
- `down` or a recreate) it starts no further minute, waits for a tick that
220
- is running, and stops every running agent side by side: SIGTERM to the
369
+ `down` or a recreate) it starts no further minute. Active launch work gets
370
+ 10 seconds to finish naturally; then a private admission fence prevents
371
+ further schedule, trigger, wake or resume launches and owned children get
372
+ a 5-second cancellation phase. An interrupted launch stays `unknown` and
373
+ needs reconciliation; a timeout does not prove that nothing ran. Host run
374
+ then lists and stops every running agent side by side: SIGTERM to the
221
375
  harness and a wait of 20 seconds, never escalated. Each home's stop record
222
376
  says it was stopped with the host, so the home reads `lost` and the next
223
- start's sweep resumes it. Then it exits 0 and the container ends.
377
+ start's sweep resumes it. Then it exits 0 and the supervisor stops the
378
+ broker. Work that cannot be killed retains the host-run claim; the runtime's
379
+ final kill is a failed stop, never proof of an ordered shutdown.
224
380
  - **Its progress** is one line per event on standard error, beside sshd's
225
381
  log, in `docker logs`.
226
382
 
227
383
  What the image's files fix for that:
228
384
 
229
- - **`oats host run` is tini's direct child**, the process the runtime's
230
- signal reaches and the container waits for: the entrypoint's last line is
231
- `exec oats host run`, after sshd is started in the background. `tini -g`
232
- signals its child's process group; the OATS tmux server and the harnesses
233
- under it are in sessions of their own, outside that group, so they run
234
- until `oats host run` stops them. Measured in `oats-agent:o1-local` with
235
- tini 0.19.0 and tmux 3.3a: on `docker stop` both members of the group
236
- received the TERM, and two seconds later the tmux server and its pane were
237
- alive and the pane had received nothing.
385
+ - **PID-only tini signals the Node supervisor.** It forwards TERM to host
386
+ run alone and keeps the wake broker alive until host run finishes stopping
387
+ the agents. Then it stops sshd and the broker in parallel. A broker or
388
+ host-run exit is reported and drains the other children before a nonzero
389
+ container exit, so
390
+ the restart policy can restart it. The broker runs as the agent uid; its
391
+ default state directory is `/state/home/.config/aw/wake`, so registrations
392
+ survive container replacement and it starts again even with no spawn.
238
393
  - **`stop_grace_period: 45s`** in the Compose service. Docker's default is
239
394
  10 seconds, shorter than the 20 seconds each harness is given; a container
240
395
  killed at the timeout leaves agents that were not stopped in order. A
241
396
  platform that does not read the Compose file needs the same stop timeout
242
397
  in its container spec.
243
- - **A healthcheck on sshd.** `oats host run` does not supervise sshd: if
398
+ - **A healthcheck on sshd.** The supervisor reports an sshd exit; if
244
399
  sshd ends, the agents and the tick go on and the operator's route is gone.
245
400
  The service's healthcheck opens `127.0.0.1:2222` every 30 seconds (5
246
401
  second timeout, 3 retries, 10 second start period), so the container then
@@ -258,8 +413,10 @@ What the image's files fix for that:
258
413
 
259
414
  `oats host run` refuses to start while another one holds the container's
260
415
  lock (`E_HOST_RUN_BUSY`); the container then exits 1 and the restart policy
261
- starts it again. A lock left by an earlier run of the container is taken
262
- over.
416
+ starts it again. A lock left by an earlier run is taken over when its pid
417
+ is gone or has another process start time. A visible live holder, or a
418
+ holder whose start cannot be read, stays held; see
419
+ [Session recovery](execution-targets.md#which-losses-come-back).
263
420
 
264
421
  The schedule tick covers only registered deployments. Register the
265
422
  deployment once, after `server connect`
@@ -338,3 +495,173 @@ fixtures. The SSH guard requires flat
338
495
  `Keyword value` lines and refuses duplicate keywords, `Match`/`Include`,
339
496
  equals-delimited keywords and quoted keywords. Follow the repository's
340
497
  local check limits; full suites run in CI.
498
+
499
+ ## Image CI and publication
500
+
501
+ [Team image](../.github/workflows/team-image.yml) builds `container/agent`
502
+ from the pull request's exact head commit, on an Ubuntu 24.04 amd64 runner.
503
+ It also supports a manual verification run at the selected ref. Actions are
504
+ pinned by commit, and the verification token has only `contents: read`.
505
+ After acceptance, verification also runs the real Docker export, Skopeo
506
+ compression and configuration-digest checks used before publication, without
507
+ a registry credential or any registry/release write.
508
+
509
+ Manual verification offers two additional proofs:
510
+
511
+ - `default_payload_proof` builds the registry context a second time without
512
+ the additive BuildKit mount and compares the full installed `/opt/agent`
513
+ payload: file paths, sizes, content hashes, modes, directories and link
514
+ targets. Image history and IDs may differ; payload differences fail.
515
+ - `packed_kernel` prepares a private context from the selected commit and
516
+ runs the image with that commit's own `npm pack` kernel. This job is
517
+ manual-only until the image owner's compatible final baseline lands.
518
+ Ordinary PR verification keeps the committed context in the meantime.
519
+ An incompatible baseline fails explicitly, with no registry-kernel fallback
520
+ and no wider lock allowance. The committed baseline needs final OATS
521
+ 0.69.18+ and aw 1.36.59+ with the compatible exact runtime closure.
522
+ With the committed baseline, the packed job refuses; its positive real
523
+ packed-image acceptance is **NOT RUN** until that compatible baseline lands.
524
+
525
+ Packing disables lifecycle scripts and uses a private npm home/cache, empty
526
+ user/global configs and an explicit public registry. Every packed file must
527
+ be in the kernel's literal `package.json.files` list, including the explicitly
528
+ declared manifest and license. The tarball is checked against its SHA512
529
+ integrity and the exact checkout's regular Git files, sizes, bytes and modes;
530
+ links, unsafe paths and untracked/generated payloads refuse. The source
531
+ checkout stays unchanged.
532
+
533
+ Only the private image manifest changes to the fixed
534
+ `file:../oats-build-inputs/oats-pr-kernel.tgz` dependency. The same tarball is
535
+ provided in the closed context and a private host-side sibling directory,
536
+ so npm lock generation and the build resolve the same bytes. The existing
537
+ `npm ci --ignore-scripts` RUN gets a read-only context mount at
538
+ `/opt/oats-build-inputs`; no tarball COPY, build argument, new lifecycle
539
+ execution or runtime mount is added. The registry release context and its
540
+ strict metadata checks keep their own path. Both adapters protect every
541
+ unrelated CLI and lock entry, addition, removal and root/metadata field.
542
+
543
+ After the unmodified acceptance, the packed job checks the installed kernel's
544
+ exact own-file set, sizes, modes and hashes against the HEAD inventory in
545
+ the same accepted container. Version equality alone is insufficient: two
546
+ commits may share a version. Separately resolved nested dependencies remain
547
+ governed by the image lock. A changed inventory artifact or installed file
548
+ fails before digest preparation. The closed context, tarball, generated
549
+ manifest/lock, source inventory and build metadata are retained as artifacts;
550
+ npm config/cache are outside the uploaded context. Source SHA and
551
+ integrity/inventory/lock hashes are retained in those artifacts. Acceptance
552
+ reports the image ID in its log and passes it between workflow steps to bind
553
+ the export to the accepted image. These checks do not broaden the receipt's
554
+ supervisor, agent or containment claims.
555
+
556
+ The shared fixture, `.github/scripts/team-image-accept.sh`, starts the
557
+ committed Compose service on a disposable internal bridge with IPv6 off and
558
+ an isolated gateway (Docker Engine 28+). It provisions private state, a
559
+ throwaway SSH public key, a resolver file and an empty root:20001 0750 login
560
+ directory, waits for the service's SSH healthcheck, then runs the image's
561
+ unmodified `accept.sh --evidence target-amd64`. Cleanup removes the service,
562
+ network and fixture paths on success or failure. This is image acceptance;
563
+ it provisions no seat or inference token. The script's `NOT RUN` items
564
+ remain outside this check.
565
+
566
+ The `publish-team-image` job in
567
+ [Release](../.github/workflows/release.yml) waits for the existing `publish`
568
+ job, so npm publication and the GitHub Release precede the image. Its
569
+ single job-level `if: ${{ false }}` keeps publication disabled pending the
570
+ registry decision for the proposed `ghcr.io/oats-project/team-agent` target.
571
+ GHCR creates a new package as private by default. Verification remains
572
+ enabled. Enabling publication requires the registry decision and a reviewed
573
+ change to the switch.
574
+
575
+ Before enabling, the registry owner must complete these separately authorized
576
+ setup steps and include their evidence as a checklist in the enabling PR:
577
+
578
+ 1. Push the approved digest from a verified run.
579
+ 2. Set the package visibility to public.
580
+ 3. Grant this repository's Actions write access.
581
+ 4. Record the pinned-client observation that an unused exact version tag
582
+ returns `manifest unknown`.
583
+
584
+ Package creation is this manual setup step, never an automatic release-job
585
+ bootstrap. The job treats only `manifest unknown` as an absent tag. It refuses
586
+ `name unknown`, `denied`, authentication and transport errors. The registry
587
+ owner resolves bootstrap and access problems without broadening the matcher.
588
+
589
+ Publication requires a stable `vX.Y.Z` release tag (at least 0.69.18).
590
+ The release job copies only the tagged image's literal `.dockerignore`
591
+ allowlist into a private build context, sets its OATS dependency to exactly
592
+ `X.Y.Z`, and regenerates that copy's lock with npm scripts disabled and the
593
+ public registry selected explicitly. The source checkout and Dockerfile
594
+ stay unchanged. The committed aw pin must be a final version of at least
595
+ 1.36.59 and match its lock; prereleases cannot pass the guard.
596
+
597
+ The generated lock may change only the OATS entry, its root dependency
598
+ specification and its own exact runtime dependencies. Other entries,
599
+ including aw, Claude and unrelated transitive packages, must remain equal
600
+ to the committed lock, including additions and removals. Registry version,
601
+ tarball URL and SHA512 integrity must match the new kernel and its exact
602
+ dependencies. A missing compatible committed baseline fails the build;
603
+ it does not widen the allowance. The image owner maintains that baseline.
604
+ The effective manifest, generated lock and source/version/integrity metadata
605
+ are retained as a run artifact. Lock regeneration is audited rather than
606
+ claimed to reproduce the entire image across retries.
607
+
608
+ After building the private context, the release job runs the existing real
609
+ acceptance and separately executes `oats version --json` in that same
610
+ container. The installed kernel must equal `X.Y.Z` before registry login.
611
+ The fixture records the accepted container's image ID. Export must inspect
612
+ that same ID, then use `docker save` on the immutable ID. Skopeo reads the
613
+ archive and compresses layers into a private directory, preserving its
614
+ Docker v2s2 manifest type. Docker's CLI negotiates the Engine API; Skopeo
615
+ uses no daemon connection. The release lane installs and verifies the
616
+ reviewed Ubuntu Skopeo package version `1.13.3+ds1-2ubuntu0.24.04.3`, whose
617
+ error text it parses; changing that input requires another review and real
618
+ preparation run. PR verification installs the available archive package
619
+ without an exact apt pin and records its version in the step summary.
620
+
621
+ Keeping the manifest type avoids rewriting configuration bytes. The
622
+ prepared configuration digest must equal the hash of the archive's raw
623
+ configuration, binding the manifest and root filesystem to the accepted
624
+ image. This binding uses archive bytes rather than assuming Docker's image
625
+ ID is a configuration digest. The classic store has real runner evidence;
626
+ the containerd store branch has fixture coverage and still needs a real run.
627
+ Skopeo [copies with preserved digests](https://github.com/containers/skopeo/blob/main/docs/skopeo-copy.1.md)
628
+ to `repository@sha256:...`.
629
+
630
+ The same manifest also gets the exact release retention tag `X.Y.Z`, with
631
+ no leading `v`, `latest`, major or minor aliases. Before any registry write,
632
+ a different digest at that tag is refused; a same-digest retry is idempotent.
633
+ Only an explicit manifest-not-found result permits creation. Authentication,
634
+ transport and other lookup errors fail closed. After copying the digest,
635
+ the job copies the same manifest to the absent version tag and verifies its
636
+ resolved digest. The release workflow serializes its own writes; this
637
+ preflight is not a registry compare-and-swap against independent writers.
638
+ Deployments, chart values, deploy/team and release receipts continue to use
639
+ the digest reference. The version tag is for retention and human inspection.
640
+
641
+ After the version tag is written, a failed final verification or receipt edit
642
+ requires manual recovery of that published digest: verify the existing tag
643
+ against the original run's retained build inputs and acceptance evidence, then
644
+ restore its owned receipt block. Use the original digest output/summary when
645
+ available; a failed final inspect may precede that output. A workflow rerun
646
+ rebuilds and can yield a different digest that correctly refuses. Never retag
647
+ to make the rerun pass.
648
+
649
+ The digest is a job output and appears in the run summary. An owned block
650
+ in the existing GitHub Release notes records the immutable image reference,
651
+ source tag and commit, installed kernel, generated lock hash and npm kernel
652
+ integrity. A retry replaces only that image's block, preserving other prose.
653
+ The receipt's PASS list covers image build, non-root user, read-only root,
654
+ sshd startup and image/configuration digest binding. Supervisor startup,
655
+ admitted-seat spawn, wake delivery, package sync, inference, mail/chat,
656
+ viewer, governance, platform containment and network/egress-bypass checks
657
+ remain **NOT RUN**. Version and lock checks do not prove supervisor startup
658
+ or agent readiness; those claims need direct acceptance coverage.
659
+
660
+ Only that job has `packages: write`; `contents: write` lets it replace its
661
+ owned receipt block. Among run-step environments, only the publish step
662
+ receives `GITHUB_TOKEN`. The SHA-pinned first-party checkout and setup-node
663
+ actions use their default action token inputs; checkout does not persist
664
+ credentials. The publish step stores
665
+ registry authentication in a private temporary file and removes it on exit.
666
+ It receives no npm publish credential. To roll back a deployed image, select
667
+ the previous reviewed digest in the deployment configuration.
@@ -305,8 +305,14 @@ Each entry's manifests, souls and integrity are read at the observed commit →
305
305
  ### 4.3 Trust and removed APIs
306
306
 
307
307
  There is no approval step or record: declaring a package in `packages:` is the trust decision, and the
308
- lock pins commit and integrity. `oats sync --approve` is `E_BAD_ARGS`. Pre-workspace exports remain as
309
- shims that throw `E_REMOVED { name, contract }`, pointing at this record.
308
+ lock pins commit and integrity. `oats sync --approve` is `E_BAD_ARGS`.
309
+
310
+ Pre-workspace package-install, requirement, OAS-migration and config-merge APIs are not
311
+ exported from `lib/packages.mjs`. Named imports fail at module loading; namespace imports do not
312
+ contain those names. Use workspace `packages:`
313
+ plus `oats sync`; capability requirements and configuration belong to their provider, not the
314
+ removed package-install/config-merge APIs. The live `lockedPackageCapabilities` in `lib/resolve.mjs`
315
+ and `packageSpecIdentity` in `lib/core.mjs` are separate APIs and remain available.
310
316
 
311
317
  ---
312
318
 
@@ -25,8 +25,8 @@ Local `oats-local.yaml` (the deployment's per-machine file, never committed):
25
25
 
26
26
  ```yaml
27
27
  teams:
28
- antares-oats: { team: antares-oats:ana.aweb.ai } # a local (personal) team: label → provider id
29
- defaultTeam: antares-oats
28
+ builder-oats: { team: builder-oats:ana.aweb.ai } # a local (personal) team: label → provider id
29
+ defaultTeam: builder-oats
30
30
  souls:
31
31
  disabled: [...]
32
32
  teams: # the extra teams each soul's instances MAY join here
@@ -35,4 +35,4 @@ Hosts that ran workspace automations before 0.30 must add their `trust` lines. T
35
35
  notes say so. No host of ours runs one today, so there's nothing to migrate.
36
36
 
37
37
  ## Unblocks
38
- The okf review trigger on Juan's host: it runs once his host trusts it.
38
+ The okf review trigger on an operator's host: it runs once that host trusts it.