@awebai/oats 0.69.18 → 0.69.20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/bin/oats.mjs +2 -2
  2. package/docs/capabilities.md +27 -14
  3. package/docs/container.md +416 -43
  4. package/docs/design/2026-09-27-team-model-v2.md +2 -2
  5. package/docs/design/2026-09-28-automations-trust.md +1 -1
  6. package/docs/desktop-cli-api.md +52 -31
  7. package/docs/desktop.md +29 -6
  8. package/docs/execution-targets.md +32 -17
  9. package/docs/implementation.md +4 -3
  10. package/docs/integrations.md +2 -2
  11. package/docs/knowledge.md +5 -5
  12. package/docs/official-catalog.md +5 -5
  13. package/docs/packages.md +13 -13
  14. package/docs/release-lane.md +6 -4
  15. package/docs/release-notes/v0.69.19.md +172 -0
  16. package/docs/release-notes/v0.69.20.md +325 -0
  17. package/docs/servers.md +6 -4
  18. package/docs/souls-and-instances.md +37 -13
  19. package/docs/tui.md +8 -8
  20. package/docs/upgrading.md +17 -5
  21. package/docs/workspaces.md +13 -7
  22. package/injects/work-directory.md +27 -2
  23. package/injects/work-workspace.md +32 -6
  24. package/lib/core.mjs +33 -197
  25. package/lib/hook-outcome.mjs +6 -0
  26. package/lib/host-run.mjs +24 -19
  27. package/lib/instance-lifecycle.mjs +3 -1
  28. package/lib/instance-listing.mjs +3 -2
  29. package/lib/launch-prompt-fixtures/README.md +6 -0
  30. package/lib/retire-admission.mjs +215 -0
  31. package/lib/servers.mjs +3 -0
  32. package/lib/session-resume-contract.mjs +1 -1
  33. package/lib/session-resume.mjs +130 -47
  34. package/lib/session-seen.mjs +3 -3
  35. package/package-catalog.json +3 -3
  36. package/package.json +3 -1
  37. package/packages/client/attributed-human.mjs +13 -0
  38. package/packages/client/deployment-data.mjs +4 -0
  39. package/packages/client/deployment-panel.mjs +2 -0
  40. package/packages/client/instance-lifecycle.mjs +6 -4
  41. package/packages/client/instance-presentation.mjs +2 -2
  42. package/packages/client/instance-tree.mjs +18 -7
  43. package/packages/client/lifecycle-confirmation.mjs +4 -2
  44. package/packages/client/lifecycle-contract.mjs +11 -6
  45. package/packages/client/remote-roster.mjs +4 -0
  46. package/packages/record/README.md +15 -2
  47. package/packages/record/docs/capture-service.md +14 -0
  48. package/packages/record/lib/canonical.mjs +2 -70
  49. package/packages/record/lib/capture-aw-unit.mjs +14 -3
  50. package/packages/record/lib/capture-aw.mjs +11 -5
  51. package/packages/record/lib/capture-health.mjs +16 -5
  52. package/skills/oats-getting-started/SKILL.md +3 -3
package/docs/container.md CHANGED
@@ -83,7 +83,7 @@ version and regenerate this directory's lock with
83
83
  `npm install --package-lock-only --ignore-scripts`; review both files. Do not
84
84
  use `--install-oats` or `--install-aw` against a running container.
85
85
 
86
- The committed OATS 0.69.15 pin has `oats host run`, which the entrypoint
86
+ The committed OATS 0.69.19 pin has `oats host run`, which the entrypoint
87
87
  runs, and `oats schedule host install --register-only`. It supports
88
88
  `env: { fromFile: ... }` and the operator's `oats harness token set` route.
89
89
  Provision the token through the
@@ -110,7 +110,9 @@ the UID-only form proves startup and SSH support, not token access.
110
110
  | `/etc/agent-login` | root:runtime-GID, 0750; `claude-token` root:runtime-GID, 0440 | Read-only |
111
111
  | `/etc/agent-ssh/authorized_keys` | root-owned regular file, 0644 | Read-only |
112
112
  | `/etc/resolv.conf` | Operator-provided resolver file | Read-only |
113
- | `/tmp` | tmpfs, rw,nosuid,nodev,mode=1777 | Ephemeral |
113
+ | `/tmp` | tmpfs, rw,nosuid,nodev,size=AGENT_TMP_SIZE,mode=1777 | Ephemeral; bounded by the configured byte limit |
114
+ | `/etc/agent-trust/ca.pem` | Optional public CA file, read-only | Operator-provisioned extra trust; no private keys |
115
+ | `/mirrors` | Optional bare Git mirror directory, read-only | Operator-refreshed source snapshots, outside writable state |
114
116
 
115
117
  All binds use `create_host_path: false`: a missing path fails startup.
116
118
  `/state/home`, `/state/ssh` and `/state/deploy` are created 0700 by the agent.
@@ -141,16 +143,63 @@ Supply these plain variables to the bundle's env file:
141
143
  | `AUTHORIZED_KEYS_FILE` | Absolute host public-key file. |
142
144
  | `RESOLV_CONF_FILE` | Absolute host resolver file; always required. |
143
145
  | `AGENT_PIDS`, `AGENT_MEMORY`, `AGENT_CPUS` | Positive limits; memory uses bytes, k, m or g. |
146
+ | `AGENT_TMP_SIZE` | Positive integer bytes from the shared configuration's `agents.tmpSize`; bounds the `/tmp` tmpfs. |
147
+ | `AGENT_CA_FILE` | Optional absolute public PEM path from `agents.caFile`; selects `compose.agent.trust.yaml`. |
148
+ | `AGENT_MIRRORS_DIR` | Optional absolute mirror directory from `agents.mirrorsDir`; selects `compose.agent.mirrors.yaml`. |
144
149
  | `AGENTS_NETWORK`, `AGENT_IP` | Installer-created external network and container address. |
145
150
 
146
151
  The bundle owns the network, resolver, forwarder, firewall and their bypass
147
152
  checks. The agent service publishes no ports and sets no DNS or extra-hosts
148
153
  override. It joins only the named external `agents` network. Its restart
149
- policy is `unless-stopped`, its stop grace period is 45 seconds and its
154
+ policy is `unless-stopped`, its stop grace period is 50 seconds and its
150
155
  healthcheck reads sshd's port
151
156
  ([The kernel's periodic work](#the-kernels-periodic-work)); security flags
152
157
  are fixed in the service file.
153
158
 
159
+ Include `compose.agent.trust.yaml` only when `agents.caFile` is configured. It
160
+ adds one read-only mount at `/etc/agent-trust/ca.pem` and exactly two fixed
161
+ environment settings: `SSL_CERT_FILE` and `NODE_EXTRA_CA_CERTS`, both pointing
162
+ there before the supervisor starts. The file must contain only valid public CA
163
+ certificates, at most 64 KiB, with no private key. Go keeps its normal certificate
164
+ directories and Node extends its normal roots. The acceptance check validates
165
+ the file and the exact mount/environment pair; it permits no general environment
166
+ override. The broker and its Node verification child receive the same trust
167
+ settings. The immutable `/etc/profile.d/agent-trust.sh` also supplies the two
168
+ settings to the agent's captured login environment and tmux children when the
169
+ fixed CA file is readable. The image sources that same profile at the start of
170
+ the system bashrc, before its noninteractive return, for bash's SSH startup
171
+ path. sshd also fixes `BASH_ENV` to that profile for other noninteractive bash
172
+ commands; user environment and SSH rc overrides remain disabled. Without the
173
+ CA mount, the profile exports neither setting. Recreate the container after
174
+ changing a trust bundle so the broker, Node children and captured sessions all
175
+ start with the same approved anchors.
176
+ A successful probe using an explicit CA does not establish that the
177
+ real broker trusts it; prove that through the deployment's HTTPS registry.
178
+
179
+ Include `compose.agent.mirrors.yaml` only when `agents.mirrorsDir` is configured.
180
+ The operator provisions and refreshes the bare mirrors outside the container,
181
+ with no repository credentials, and the fragment mounts them read-only at
182
+ `/mirrors`. Keep both optional input sources outside every agent-writable bind
183
+ source, including symlink aliases: run acceptance on the Docker engine host so
184
+ it can resolve the actual sources. A CA file with multiple hardlinks is refused,
185
+ since a read-only bind cannot protect another writable link to the same file.
186
+ The wrapper renders the existing Git rewrite in
187
+ `/state/home/.gitconfig`:
188
+
189
+ ```gitconfig
190
+ [url "file:///mirrors/github.com/"]
191
+ insteadOf = https://github.com/
192
+ ```
193
+
194
+ Retain the operator's exact source/ref/commit manifest and refresh time beside
195
+ the mirrors. A snapshot observes the last operator refresh; its presence does
196
+ not prove current membership or withdrawal freshness. The first deployment check
197
+ is `oats workspace status` with all members confirmed, followed by the actual
198
+ spawn preview. Do not enable all Git file transports or add a general Git-host
199
+ egress route to make that check pass. Kubernetes uses an explicit existing
200
+ `agents.kubernetes.mirrorsClaim` for the same read-only mount, separate from
201
+ state; it never turns the Compose directory into a hostPath.
202
+
154
203
  ```sh
155
204
  docker compose -p "oats-team-${TEAM}" --env-file <plain-env-file> \
156
205
  -f compose.yaml -f container/agent/compose.agent.yaml config
@@ -164,15 +213,57 @@ the override: the base has no `/work` mount. With multiple Compose files,
164
213
  paths resolve relative to the first file; use absolute host paths. Container
165
214
  down/upgrade preserves `/state`; the operator owns provisioning and rollback.
166
215
 
167
- ## OATS over SSH
216
+ The image account and the runtime NSS entry use `/bin/bash` as the login shell.
217
+ This lets OATS capture a fresh login environment rather than inheriting the tmux
218
+ creator's environment after a failed shell capture.
168
219
 
169
- The operator's SSH alias selects the key, host-key verification, port 2222
170
- and jump route. The equivalent connection is:
220
+ Compose fixes the container hostname to `oats-agent`, so replacement keeps the
221
+ hostname used by cache locks. Container names and network addresses still belong
222
+ to the deployment wrapper. A lock written under a former ephemeral hostname may
223
+ need one manual cleanup after checking that its holder is no longer running.
171
224
 
172
- ```sh
173
- ssh -J <provisioner>@<host> -p 2222 agent@<container-ip>
225
+ ## Broker delivery before launch
226
+
227
+ Container deployments use the in-container broker with session delivery. Before
228
+ any spawn or resume, the bootstrap wrapper writes the existing setting in the
229
+ deployment's `oats-local.yaml`:
230
+
231
+ ```yaml
232
+ settings:
233
+ oats.aweb:
234
+ delivery: session
235
+ ```
236
+
237
+ A contradictory existing value must stop bootstrap with a fix naming
238
+ `settings.oats.aweb.delivery`; correct the deployment setting before restarting
239
+ it. Verify the effective value with `oats inspect` or the spawn preview's
240
+ `settings.oats.aweb`. The image and Compose also declare `AWEB_DELIVERY=session`
241
+ to silence ambient channel extensions; that variable alone does not select the
242
+ provider setting. The image has no Claude channel plugin.
243
+
244
+ ## OATS over SSH
245
+
246
+ The operator's SSH alias selects the key and verifies the provisioned SSH host
247
+ key. The isolated agents bridge has no host gateway, so use the operator's
248
+ existing Docker context as a stdio relay to port 2222 inside the container:
249
+
250
+ ```sshconfig
251
+ Host team-agent
252
+ HostName oats-agent
253
+ User agent
254
+ Port 2222
255
+ IdentityFile <operator-key-path>
256
+ IdentitiesOnly yes
257
+ UserKnownHostsFile <provisioned-known-hosts-file>
258
+ StrictHostKeyChecking yes
259
+ ProxyCommand docker --context <operator-context> exec -i <container> node -e 'const s=require("node:net").connect(2222,"127.0.0.1");process.stdin.pipe(s);s.pipe(process.stdout);s.on("error",()=>process.exit(1));'
174
260
  ```
175
261
 
262
+ Provision the public host key in that known-hosts file before connecting. The
263
+ Docker context belongs only to the operator; the agent receives no engine socket,
264
+ additional network or published port. `ssh team-agent` then uses the same SSH
265
+ authentication and host-key checks as an ordinary SSH transport.
266
+
176
267
  Register an already provisioned deployment, or connect it from the operator's
177
268
  deployment using its source reference:
178
269
 
@@ -192,9 +283,11 @@ deployment for the schedule tick `oats host run` runs in the container
192
283
  oats schedule host install --register-only --server team-agent
193
284
  ```
194
285
 
195
- The operator places
196
- two independently admitted ordinary-member identities at
197
- `/state/seats/<alias>/.aw`; each spawn selects one:
286
+ The legacy VM migration route copies an already admitted ordinary-member
287
+ identity's private state into `/state/seats/<alias>/.aw`; each spawn selects one
288
+ through the existing `identity.source` input. Treat that copy as credential
289
+ provisioning, keep it private, and do not use a team or namespace controller
290
+ identity:
198
291
 
199
292
  ```sh
200
293
  oats spawn <soul> --server team-agent --harness claude --preview --provider oats.aweb identity.source=/state/seats/<alias>/.aw
@@ -250,47 +343,50 @@ aw workspace connect --service <the team's aweb server>
250
343
  The commands are as `aw` 1.36.57 documents them in its own `--help`. The
251
344
  sequences have not yet been run in a container.
252
345
 
253
- Before it copies anything, the spawn checks three things and refuses the
254
- seat when one is missing:
346
+ Before it copies or locks anything, the spawn checks five things, and
347
+ refuses the seat with its fix when one is missing:
255
348
 
256
349
  - `signing.key`, the member's key;
257
350
  - the server: `aweb_url` in `workspace.yaml` (`aw workspace connect` writes
258
- it);
351
+ it). The seat's service comes only from there: `OATS_AWEB_URL` is not read;
259
352
  - the team: the deployment's default team, or else the active team in
260
- `teams.yaml`.
353
+ `teams.yaml`;
354
+ - `teams.yaml` itself;
355
+ - a membership of that team in `teams.yaml`, matched as aw matches it. When
356
+ there is none, accept the team's invite (`aw id team accept-invite`) or
357
+ fetch its certificate (`aw id team fetch-cert`) in the seat's directory, or
358
+ make the seat's team the deployment's default.
261
359
 
262
- The member's certificate under `team-certs/` is not checked at that point,
263
- and the seat does not work without it: the spawn copies the seat, fails when
264
- it connects or reads the identity back, and removes the copy.
360
+ The member's certificate file under `team-certs/` is not checked at that
361
+ point, and the seat does not work without it: the spawn copies the seat,
362
+ fails when it connects or reads the identity back, and removes the copy.
265
363
 
266
364
  One seat serves one instance at a time. The spawn writes
267
365
  `.aw-retained-seat.json` beside the seat's `.aw` and refuses a second spawn
268
366
  while the first instance's home exists; retiring that instance releases the
269
- seat. Two cases need the operator:
367
+ seat. Every change of that lock is one guarded step, using two private files
368
+ beside it, `.aw-retained-seat.json.guard` and `.aw-retained-seat.json.held`.
369
+ A change that was killed can leave one of them behind. The next spawn or
370
+ take-over then refuses, naming the file and its fix, and the next retire
371
+ reports it. Nothing removes such a file automatically. Two cases need the
372
+ operator:
270
373
 
271
374
  - **The holder's home exists and its runtime is known to be dead.** Spawn
272
375
  with `identity.takeOver=true`. If that runtime is in fact alive, there are
273
376
  then two seats with one key; stop the old one.
274
- - **The holder's home is gone without a retire** (a home removed by hand, a
275
- volume restored). Every later spawn is still refused, as "taken by another
276
- spawn a moment ago", and `identity.takeOver` does not apply. Remove
277
- `.aw-retained-seat.json` by hand once the home is confirmed gone
278
- ([awebai/oats-aweb#227](https://github.com/awebai/oats-aweb/issues/227)).
377
+ - **The holder's home is not on this host** (a home removed by hand, a volume
378
+ restored, or a home on another host that shares the seat). The spawn
379
+ refuses, naming the holder as the lock records it (instance, host, since
380
+ and home) and the release. A lock is never released by age. Once that seat
381
+ is confirmed gone, spawn with `identity.takeOver=true`, which clears the lock
382
+ with a warning, or remove the lock file the refusal names.
279
383
 
280
384
  Retiring never revokes the member's certificate: on a server that is not the
281
385
  hosted service, whoever holds the controller key removes a member
282
- (`aw id team remove-member`).
283
-
284
- Known limits of this route, until their fixes are released:
285
-
286
- - **A restart can lose the seat's identity.** A seat made this way may not
287
- get `AWEB_IDENTITY_HOME` at a restart
288
- ([awebai/oats-aweb#226](https://github.com/awebai/oats-aweb/issues/226)).
289
- Check `aw whoami` in the home after a restart; if it is not the seat, retire
290
- the instance and spawn it again.
291
- - **Do not interrupt a seat's spawn.** A spawn killed after it connected can
292
- delete the standing identity's workspace at the server
293
- ([awebai/oats-aweb#228](https://github.com/awebai/oats-aweb/issues/228)).
386
+ (`aw id team remove-member`). A seat's spawn that fails or is killed never
387
+ deletes the standing identity's workspace at the server: its retire releases
388
+ the lock and prints the `aw workspace connect` that binds the identity back to
389
+ its seat.
294
390
 
295
391
  The pinned OATS release supports this file-backed launch configuration:
296
392
 
@@ -302,6 +398,11 @@ launch-configs:
302
398
  CLAUDE_CONFIG_DIR: /state/home/.claude
303
399
  CLAUDE_CODE_OAUTH_TOKEN:
304
400
  fromFile: /etc/agent-login/claude-token
401
+ CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1"
402
+ DISABLE_UPDATES: "1"
403
+ DISABLE_FEEDBACK_COMMAND: "1"
404
+ ENABLE_CLAUDEAI_MCP_SERVERS: "false"
405
+ CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL: "1"
305
406
  ```
306
407
 
307
408
  Select it with `--launch-config team-claude`. The operator provisions only a
@@ -309,6 +410,47 @@ Select it with `--launch-config team-claude`. The operator provisions only a
309
410
  by every agent in the same trust group; read-only mounting does not hide it
310
411
  or narrow its authority. Never share the mount across trust groups.
311
412
 
413
+ For the optional external model role, the wrapper also writes
414
+ `{"skipWebFetchPreflight": true}` into `/state/home/.claude/settings.json`,
415
+ merging with any other supported settings. The literals above disable ancillary
416
+ Claude traffic; they do not prove that the pinned harness needs only
417
+ `api.anthropic.com`. Qualify a real authorized start and turn, retaining every
418
+ refused DNS/SNI name. Report an additional necessary host rather than adding it
419
+ automatically. Do not put `ANTHROPIC_API_KEY` or `ANTHROPIC_AUTH_TOKEN` alongside
420
+ this login: those credentials take precedence over the setup-token input.
421
+
422
+ The [egress component](../container/agent/egress/README.md#optional-external-source-and-model-roles)
423
+ defines the two optional source/model routes and their operator-selected DNS
424
+ resolvers. Their boundary is exact SNI and a validated public destination;
425
+ it does not filter repository paths, HTTP authorities or data sent to a provider.
426
+ It limits which services are reachable, not which accounts on them. A credential
427
+ from any source, including an untrusted message, can allow an agent to push data
428
+ to a GitHub repository or send data to a model account controlled by that
429
+ credential's owner. Publishing needs a separate operator decision and a push
430
+ credential scoped to one repository; the network boundary does not enforce
431
+ that scope.
432
+
433
+ Direct source access is off by default. Operator-refreshed read-only mirrors
434
+ provide source reads without that outbound route. They avoid access to any
435
+ public GitHub repository, request-path disclosure in GitHub logs, and writes
436
+ limited only by credential scope. Mirrors reflect the last operator refresh;
437
+ direct access uses the configured remote source. Both routes remain supported.
438
+ The resolver input requires public IPv4 DNS and proxy UDP/TCP 53 access to it;
439
+ a cluster that mandates a private DNS resolver is not supported by this input.
440
+ The existing five-service ingress audit remains a separate admission gate.
441
+
442
+ ### A knowledge credential
443
+
444
+ Agents that propose knowledge with `oats.okf` need a GitHub credential of
445
+ their own, never the maintainer's: whatever it may do, every agent in the
446
+ container may do. Give them an identity with the write role only on the
447
+ knowledge repository, its token in a file named by
448
+ `settings.oats.okf.github-token-file`, and keep the identity that merges to
449
+ the accepted branch outside the container. oats.okf's
450
+ [Bringing up a deployment's knowledge store](https://github.com/oats-project/oats-okf/blob/v6.2.0/README.md#bringing-up-a-deployments-knowledge-store)
451
+ (oats.okf 6.2 and later) has each step; run its
452
+ `oats okf setup --check` in the container to check them.
453
+
312
454
  ### After changing a credential
313
455
 
314
456
  A resume starts an agent under the values its last start recorded. When the
@@ -381,17 +523,21 @@ What the image's files fix for that:
381
523
 
382
524
  - **PID-only tini signals the Node supervisor.** It forwards TERM to host
383
525
  run alone and keeps the wake broker alive until host run finishes stopping
384
- the agents. Then it stops sshd and the broker in parallel. A broker or
526
+ the agents. Then it stops sshd and the broker in parallel, allowing sshd three seconds
527
+ and the broker six seconds before escalation. The broker budget preserves
528
+ its channel children's five-second delivery drain. A broker or
385
529
  host-run exit is reported and drains the other children before a nonzero
386
530
  container exit, so
387
531
  the restart policy can restart it. The broker runs as the agent uid; its
388
532
  default state directory is `/state/home/.config/aw/wake`, so registrations
389
533
  survive container replacement and it starts again even with no spawn.
390
- - **`stop_grace_period: 45s`** in the Compose service. Docker's default is
391
- 10 seconds, shorter than the 20 seconds each harness is given; a container
392
- killed at the timeout leaves agents that were not stopped in order. A
393
- platform that does not read the Compose file needs the same stop timeout
394
- in its container spec.
534
+ - **`stop_grace_period: 50s`** in the Compose service. Docker's default
535
+ 10 seconds is shorter than the kernel and broker drains; each harness
536
+ alone gets 20 seconds. A container killed at the timeout leaves agents
537
+ that were not stopped in order. A platform that does not read the Compose
538
+ file needs the same stop timeout in its container spec. The 50-second
539
+ limit is the runtime's final failure boundary for stuck OS work; wake
540
+ delivery and model activity require separate evidence.
395
541
  - **A healthcheck on sshd.** The supervisor reports an sshd exit; if
396
542
  sshd ends, the agents and the tick go on and the operator's route is gone.
397
543
  The service's healthcheck opens `127.0.0.1:2222` every 30 seconds (5
@@ -461,7 +607,7 @@ variables. It resolves `AGENT_IMAGE` independently and requires that image's
461
607
  ID, reference and start command, and its complete environment (printing only
462
608
  names of differing variables). Other comparisons include supplementary
463
609
  groups, namespace overrides, sysctls, published ports, resolver overrides
464
- and the single network/address. The stop timeout must be 45 seconds and the
610
+ and the single network/address. The stop timeout must be 50 seconds and the
465
611
  healthcheck the service file's, so a container made before either was set
466
612
  is refused until it is recreated. The OCI runtime must match the daemon's
467
613
  independently read default; shared memory stays at Docker's 64 MiB default,
@@ -492,3 +638,230 @@ fixtures. The SSH guard requires flat
492
638
  `Keyword value` lines and refuses duplicate keywords, `Match`/`Include`,
493
639
  equals-delimited keywords and quoted keywords. Follow the repository's
494
640
  local check limits; full suites run in CI.
641
+
642
+ ## Image CI and publication
643
+
644
+ [Team image](../.github/workflows/team-image.yml) builds `container/agent`
645
+ from the pull request's exact head commit, on an Ubuntu 24.04 amd64 runner.
646
+ It also supports a manual verification run at the selected ref. Actions are
647
+ pinned by commit, and the verification token has only `contents: read`.
648
+ After acceptance, verification also runs the real Docker export, Skopeo
649
+ compression and configuration-digest checks used before publication, without
650
+ a registry credential or any registry/release write.
651
+
652
+ Manual verification offers two additional proofs:
653
+
654
+ - `default_payload_proof` builds the registry context a second time without
655
+ the additive BuildKit mount and compares the full installed `/opt/agent`
656
+ payload: file paths, sizes, content hashes, modes, directories and link
657
+ targets. Image history and IDs may differ; payload differences fail.
658
+ - `packed_kernel` prepares a private context from the selected commit and
659
+ runs the image with that commit's own `npm pack` kernel. This job is
660
+ manual-only until the image owner's compatible final baseline lands.
661
+ Ordinary PR verification keeps the committed context in the meantime.
662
+ An incompatible baseline fails explicitly, with no registry-kernel fallback
663
+ and no wider lock allowance. The committed baseline needs final OATS
664
+ 0.69.18+ and aw 1.36.59+ with the compatible exact runtime closure.
665
+ With the committed baseline, the packed job refuses; its positive real
666
+ packed-image acceptance is **NOT RUN** until that compatible baseline lands.
667
+
668
+ Packing disables lifecycle scripts and uses a private npm home/cache, empty
669
+ user/global configs and an explicit public registry. Every packed file must
670
+ be in the kernel's literal `package.json.files` list, including the explicitly
671
+ declared manifest and license. The tarball is checked against its SHA512
672
+ integrity and the exact checkout's regular Git files, sizes, bytes and modes;
673
+ links, unsafe paths and untracked/generated payloads refuse. The source
674
+ checkout stays unchanged.
675
+
676
+ Only the private image manifest changes to the fixed
677
+ `file:../oats-build-inputs/oats-pr-kernel.tgz` dependency. The same tarball is
678
+ provided in the closed context and a private host-side sibling directory,
679
+ so npm lock generation and the build resolve the same bytes. The existing
680
+ `npm ci --ignore-scripts` RUN gets a read-only context mount at
681
+ `/opt/oats-build-inputs`; no tarball COPY, build argument, new lifecycle
682
+ execution or runtime mount is added. The registry release context and its
683
+ strict metadata checks keep their own path. Both adapters protect every
684
+ unrelated CLI and lock entry, addition, removal and root/metadata field.
685
+
686
+ After the unmodified acceptance, the packed job checks the installed kernel's
687
+ exact own-file set, sizes, modes and hashes against the HEAD inventory in
688
+ the same accepted container. Version equality alone is insufficient: two
689
+ commits may share a version. Separately resolved nested dependencies remain
690
+ governed by the image lock. A changed inventory artifact or installed file
691
+ fails before digest preparation. The closed context, tarball, generated
692
+ manifest/lock, source inventory and build metadata are retained as artifacts;
693
+ npm config/cache are outside the uploaded context. Source SHA and
694
+ integrity/inventory/lock hashes are retained in those artifacts. Acceptance
695
+ reports the image ID in its log and passes it between workflow steps to bind
696
+ the export to the accepted image. These checks do not broaden the receipt's
697
+ supervisor, agent or containment claims.
698
+
699
+ The shared fixture, `.github/scripts/team-image-accept.sh`, starts the
700
+ committed Compose service on a disposable internal bridge with IPv6 off and
701
+ an isolated gateway (Docker Engine 28+). It provisions private state, a
702
+ throwaway SSH public key, a resolver file and an empty root:20001 0750 login
703
+ directory, waits for the service's SSH healthcheck, then runs the image's
704
+ unmodified `accept.sh --evidence target-amd64`. Cleanup removes the service,
705
+ network and fixture paths on success or failure. This is image acceptance;
706
+ it provisions no seat or inference token. The script's `NOT RUN` items
707
+ remain outside this check.
708
+
709
+ The `publish-team-image` job in
710
+ [Release](../.github/workflows/release.yml) waits for the existing `publish`
711
+ job, so npm publication and the GitHub Release precede the image. Its
712
+ single job-level `if: ${{ false }}` keeps publication disabled pending the
713
+ registry decision for the proposed `ghcr.io/oats-project/team-agent` target.
714
+ GHCR creates a new package as private by default. Verification remains
715
+ enabled. Enabling publication requires the registry decision and a reviewed
716
+ change to the switch.
717
+
718
+ Before enabling, the registry owner must complete these separately authorized
719
+ setup steps and include their evidence as a checklist in the enabling PR:
720
+
721
+ 1. Push the approved digest from a verified run.
722
+ 2. Set the package visibility to public.
723
+ 3. Grant this repository's Actions write access.
724
+ 4. Record the pinned-client observation that an unused exact version tag
725
+ returns `manifest unknown`.
726
+
727
+ Package creation is this manual setup step, never an automatic release-job
728
+ bootstrap. The job treats only `manifest unknown` as an absent tag. It refuses
729
+ `name unknown`, `denied`, authentication and transport errors. The registry
730
+ owner resolves bootstrap and access problems without broadening the matcher.
731
+
732
+ Publication requires a stable `vX.Y.Z` release tag (at least 0.69.18).
733
+ The release job copies only the tagged image's literal `.dockerignore`
734
+ allowlist into a private build context, sets its OATS dependency to exactly
735
+ `X.Y.Z`, and regenerates that copy's lock with npm scripts disabled and the
736
+ public registry selected explicitly. The source checkout and Dockerfile
737
+ stay unchanged. The committed aw pin must be a final version of at least
738
+ 1.36.59 and match its lock; prereleases cannot pass the guard.
739
+
740
+ The generated lock may change only the OATS entry, its root dependency
741
+ specification and its own exact runtime dependencies. Other entries,
742
+ including aw, Claude and unrelated transitive packages, must remain equal
743
+ to the committed lock, including additions and removals. Registry version,
744
+ tarball URL and SHA512 integrity must match the new kernel and its exact
745
+ dependencies. A missing compatible committed baseline fails the build;
746
+ it does not widen the allowance. The image owner maintains that baseline.
747
+ The effective manifest, generated lock and source/version/integrity metadata
748
+ are retained as a run artifact. Lock regeneration is audited rather than
749
+ claimed to reproduce the entire image across retries.
750
+
751
+ After building the private context, the release job runs the existing real
752
+ acceptance and separately executes `oats version --json` in that same
753
+ container. The installed kernel must equal `X.Y.Z` before registry login.
754
+ The fixture records the accepted container's image ID. Export must inspect
755
+ that same ID, then use `docker save` on the immutable ID. Skopeo reads the
756
+ archive and compresses layers into a private directory, preserving its
757
+ Docker v2s2 manifest type. Docker's CLI negotiates the Engine API; Skopeo
758
+ uses no daemon connection. The release lane installs and verifies the
759
+ reviewed Ubuntu Skopeo package version `1.13.3+ds1-2ubuntu0.24.04.3`, whose
760
+ error text it parses; changing that input requires another review and real
761
+ preparation run. PR verification installs the available archive package
762
+ without an exact apt pin and records its version in the step summary.
763
+
764
+ Keeping the manifest type avoids rewriting configuration bytes. The
765
+ prepared configuration digest must equal the hash of the archive's raw
766
+ configuration, binding the manifest and root filesystem to the accepted
767
+ image. This binding uses archive bytes rather than assuming Docker's image
768
+ ID is a configuration digest. The classic store has real runner evidence;
769
+ the containerd store branch has fixture coverage and still needs a real run.
770
+ Skopeo [copies with preserved digests](https://github.com/containers/skopeo/blob/main/docs/skopeo-copy.1.md)
771
+ to `repository@sha256:...`.
772
+
773
+ The same manifest also gets the exact release retention tag `X.Y.Z`, with
774
+ no leading `v`, `latest`, major or minor aliases. Before any registry write,
775
+ a different digest at that tag is refused; a same-digest retry is idempotent.
776
+ Only an explicit manifest-not-found result permits creation. Authentication,
777
+ transport and other lookup errors fail closed. After copying the digest,
778
+ the job copies the same manifest to the absent version tag and verifies its
779
+ resolved digest. The release workflow serializes its own writes; this
780
+ preflight is not a registry compare-and-swap against independent writers.
781
+ Deployments, chart values, deploy/team and release receipts continue to use
782
+ the digest reference. The version tag is for retention and human inspection.
783
+
784
+ After the version tag is written, a failed final verification or receipt edit
785
+ requires manual recovery of that published digest: verify the existing tag
786
+ against the original run's retained build inputs and acceptance evidence, then
787
+ restore its owned receipt block. Use the original digest output/summary when
788
+ available; a failed final inspect may precede that output. A workflow rerun
789
+ rebuilds and can yield a different digest that correctly refuses. Never retag
790
+ to make the rerun pass.
791
+
792
+ The digest is a job output and appears in the run summary. An owned block
793
+ in the existing GitHub Release notes records the immutable image reference,
794
+ source tag and commit, installed kernel, generated lock hash and npm kernel
795
+ integrity. A retry replaces only that image's block, preserving other prose.
796
+ The receipt's PASS list covers image build, non-root user, read-only root,
797
+ sshd startup and image/configuration digest binding. Supervisor startup,
798
+ admitted-seat spawn, wake delivery, package sync, inference, mail/chat,
799
+ viewer, governance, platform containment and network/egress-bypass checks
800
+ remain **NOT RUN**. Version and lock checks do not prove supervisor startup
801
+ or agent readiness; those claims need direct acceptance coverage.
802
+
803
+ Only that job has `packages: write`; `contents: write` lets it replace its
804
+ owned receipt block. Among run-step environments, only the publish step
805
+ receives `GITHUB_TOKEN`. The SHA-pinned first-party checkout and setup-node
806
+ actions use their default action token inputs; checkout does not persist
807
+ credentials. The publish step stores
808
+ registry authentication in a private temporary file and removes it on exit.
809
+ It receives no npm publish credential. To roll back a deployed image, select
810
+ the previous reviewed digest in the deployment configuration.
811
+
812
+ ## Egress component
813
+
814
+ The generic [egress image and service](../container/agent/egress/README.md) live
815
+ with the agent image. The deployment wrapper owns its allowlist and derives the
816
+ non-secret runtime policy from the shared deployment configuration and signer
817
+ profile when signer is declared. An optional derived `roles` array selects a
818
+ nonempty subset of aweb, logs, registry, secrets and signer, with exactly matching
819
+ targets and probe paths. Omission retains the five-role policy and output.
820
+ Signer `humanOrigin` is required with signer and refused without it. Registry
821
+ `authorityRecords` are required with registry and refused without it, independently
822
+ of signer: messaging-only namespaces still need exact `_awid` TXT evidence for
823
+ discovery and sender verification. The root-authoritative resolver has no
824
+ forwarding fallback. The proxy permits only the named API and registry routes and serves
825
+ only the declared public namespace authority records. Service custody keys,
826
+ PostgreSQL, Redis and the Docker socket stay outside the agent container.
827
+
828
+ Network membership, CNI enforcement and ingress Host/SNI agreement require runtime
829
+ proof before launching agents. An internal bridge, a NetworkPolicy object or a
830
+ healthy proxy alone does not prove the boundary. The [service descriptor](../container/agent/egress/descriptor.md)
831
+ supplies the wrapper mapping without a separate operator schema.
832
+
833
+ The [minimal Compose wrapper and refusing network preflight](../container/agent/egress/README.md#minimal-compose-wrapper-and-network-preflight)
834
+ own explicit agents/services IPAM, gateways, `AGENT_IP` and `EGRESS_ADDRESS`.
835
+ Preflight is read-only on the Linux engine host and refuses failed observations
836
+ or CIDR overlaps across every Docker IPAM entry, route table and link address.
837
+ Every role set keeps unlisted DNS/TLS refusal, alternate-network refusal, a live
838
+ host-gateway canary, direct upstream/backend denial and an explicit IPv4 IPAM
839
+ gateway. The report separates universal and declared controls. The Compose probe
840
+ accepts an optional derived `namePrefix` for its temporary containers and reports
841
+ `{name,image,network,created,absentVerified}` receipts on success and refusal.
842
+ Cleanup removes only an exact name whose per-attempt ownership label matches;
843
+ timeouts require inspection and never count as absence. A failed observation
844
+ refuses and reports the unverified name. The new `--json` mode returns
845
+ `{passed,receipts,error?}` on stdout, with exit 1 on refusal; the default PASS token
846
+ and stderr receipt lines remain available. See the
847
+ [Compose probe contract](../container/agent/egress/README.md#boundary-probe-on-an-existing-compose-deployment).
848
+ Stage public
849
+ sources before credentials; there is no codeload exception. Pin wrapper,
850
+ compiler/proxy image and probes to one reviewed commit and retain image digests.
851
+
852
+ The ingress probe keeps backend non-delivery witnesses for owned routes. A
853
+ wrapper may explicitly mark only the registry as external for verified-TLS 200
854
+ controls, without third-party refusal or backend-log claims. When signer is
855
+ declared, signer and human-surface ingress controls remain required.
856
+ `probeIngress` explicitly refuses a policy without signer before sending controls;
857
+ runtime role controls follow the compiler's canonical order for every declaration.
858
+ Deployment bundles default `team.registryRoute` to `external`; existing bundles serving a local registry
859
+ must select `local` and refuse a URL their service does not serve. See the
860
+ [route-mode contract](../container/agent/egress/README.md#ingress-admission-probe)
861
+ for the exact probe inputs and ownership checks.
862
+
863
+ For Kubernetes, liveness runs `node /usr/local/lib/agent-liveness.mjs` to check
864
+ the supervisor process. SSH on port 2222 is readiness: losing SSH must not
865
+ restart the whole team while its agents and broker are still running. The
866
+ container's 50-second termination window covers the kernel and supervisor
867
+ phases under the same [shutdown failure boundary](#the-kernels-periodic-work).
@@ -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.