@awebai/oats 0.69.19 → 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 (38) hide show
  1. package/bin/oats.mjs +2 -2
  2. package/docs/capabilities.md +26 -13
  3. package/docs/container.md +218 -18
  4. package/docs/desktop-cli-api.md +25 -11
  5. package/docs/desktop.md +16 -0
  6. package/docs/implementation.md +2 -1
  7. package/docs/integrations.md +1 -1
  8. package/docs/knowledge.md +5 -5
  9. package/docs/official-catalog.md +4 -4
  10. package/docs/packages.md +11 -11
  11. package/docs/release-notes/v0.69.20.md +325 -0
  12. package/docs/servers.md +4 -2
  13. package/docs/souls-and-instances.md +4 -2
  14. package/docs/upgrading.md +11 -5
  15. package/docs/workspaces.md +13 -7
  16. package/lib/core.mjs +31 -195
  17. package/lib/hook-outcome.mjs +6 -0
  18. package/lib/instance-lifecycle.mjs +3 -1
  19. package/lib/instance-listing.mjs +3 -2
  20. package/lib/launch-prompt-fixtures/README.md +6 -0
  21. package/lib/retire-admission.mjs +215 -0
  22. package/lib/servers.mjs +3 -0
  23. package/package-catalog.json +2 -2
  24. package/package.json +1 -1
  25. package/packages/client/attributed-human.mjs +13 -0
  26. package/packages/client/deployment-data.mjs +4 -0
  27. package/packages/client/deployment-panel.mjs +2 -0
  28. package/packages/client/instance-lifecycle.mjs +6 -4
  29. package/packages/client/lifecycle-confirmation.mjs +4 -2
  30. package/packages/client/lifecycle-contract.mjs +11 -6
  31. package/packages/client/remote-roster.mjs +4 -0
  32. package/packages/record/README.md +15 -2
  33. package/packages/record/docs/capture-service.md +14 -0
  34. package/packages/record/lib/canonical.mjs +2 -70
  35. package/packages/record/lib/capture-aw-unit.mjs +14 -3
  36. package/packages/record/lib/capture-aw.mjs +11 -5
  37. package/packages/record/lib/capture-health.mjs +16 -5
  38. package/skills/oats-getting-started/SKILL.md +2 -2
package/bin/oats.mjs CHANGED
@@ -3012,7 +3012,7 @@ function retireCmd() {
3012
3012
  dropAmbientRoot();
3013
3013
  let root; try { root = ensureRoot(dirFlag()); } catch (e) { return lifecycleFail(e, "E_NO_ROOT"); }
3014
3014
  try {
3015
- const plan = planRetire(dirFlag(), root, name, { home: homeFlag });
3015
+ const plan = planRetire(dirFlag(), root, name, { home: homeFlag, force: args.includes("--force") });
3016
3016
  if (args.includes("--json")) { jsonOk(plan); return; }
3017
3017
  console.log(`retire ${name} — plan ${plan.planRevision}`);
3018
3018
  console.log(` session ${plan.facts.session.state}; work ${plan.facts.work.observed ? `${plan.facts.work.changed} changed / ${plan.facts.work.untracked} untracked on ${plan.facts.work.branch ?? (plan.facts.work.detached ? "detached" : "a ref OATS carries no branch name for")}` : `not observed (${plan.facts.work.reason})`}; children ${plan.facts.children.length}; pull request ${plan.facts.pullRequest}`);
@@ -3061,7 +3061,7 @@ function retireCmd() {
3061
3061
  // its extra trees as it names them (the retire refuses as stale rather than move or remove one
3062
3062
  // that no longer reads that way when it gets to them).
3063
3063
  revalidate = () => {
3064
- try { fresh = planRetire(dirFlag(), root, name, { home: homeFlag }); } catch (e) { planFailure = e; throw e; }
3064
+ try { fresh = planRetire(dirFlag(), root, name, { home: homeFlag, force: args.includes("--force") }); } catch (e) { planFailure = e; throw e; }
3065
3065
  if (fresh.planRevision !== planRev) throw (stalePlan = Object.assign(new Error(`the retire plan changed since it was shown (${planRev} → ${fresh.planRevision}); review the fresh plan`), { code: "E_PLAN_STALE", details: { plan: fresh } }));
3066
3066
  return { plannedExtraWorktrees: fresh.facts.extraWorktrees, children: fresh.facts.children, ambiguous: fresh.facts.ambiguous };
3067
3067
  };
@@ -157,6 +157,7 @@ A self-contained package has an `oats.json`:
157
157
  reads what there is to undo from the home and from the service it
158
158
  registered with, and answers `meta: { retired: false, reason:
159
159
  "nothing-to-delete" }` when there is nothing: that is a complete cleanup.
160
+ Every other explicit `retired: false` outcome is an incomplete cleanup.
160
161
  - A capability declaring a **required** spawn hook should declare a `retire` hook
161
162
  too. Without one, OATS has no way to undo what the spawn hook did and no way to
162
163
  know whether it did anything, so a failure quarantines the home rather than
@@ -183,18 +184,30 @@ A self-contained package has an `oats.json`:
183
184
  the branch gone (a damaged ref, a failed read), the retry stays incomplete
184
185
  with `git branch <b>: could not verify whether it still exists (…)`. A retry that still cannot
185
186
  finish keeps the home again, names what is outstanding, and exits nonzero.
186
- - The **escape hatch is `oats retire <instance> --force`**, for a home OATS cannot
187
- identify at all: no `instance.json` and no **usable** cleanup descriptor, or an
188
- `instance.json` that does not say which retire hooks to run and no usable
189
- descriptor beside it. Such a record names no repository (`repo`), which the
190
- retire hooks are run for, and does not show (`capabilityRuntime`) that no
191
- capability has a retire hook: the stub a spawn leaves when it is killed
192
- before its record, where no marker was written before its hooks (a spawn by
193
- a kernel before this rule, or a marker since removed). Retire refuses it
194
- with `E_UNIDENTIFIED_INSTANCE_HOME` before anything is stopped, run or
195
- removed: the spawn hooks may have registered an identity that only the
196
- retire hooks would release. Clean up by hand what the capabilities
197
- registered, then `--force` removes the home, running no hook. Usable
187
+ - **A home whose retire hooks cannot run is refused before anything is stopped,
188
+ run or removed, children included.** The same admission rule applies to
189
+ `oats retire --plan`, the Desktop's Remove plan and every apply path.
190
+ `E_UNIDENTIFIED_INSTANCE_HOME` names the cause, the recorded capabilities
191
+ that may have left state, and the manual-cleanup remedy. No current
192
+ deployment configuration can prove what an old home registered.
193
+ A normal home needs its recorded `capabilityRuntime` and a context repository
194
+ to run its hooks. The context is its recorded `repo`, or the repository Git
195
+ identifies for its own worktree when the record names none. An explicit
196
+ capability set with no retire hooks proves that none is owed. A captured home from before 0.26 cannot run its hooks:
197
+ only an explicit empty captured `hookOrder`, with no capability metadata,
198
+ hook intents, hook failures or lifecycle marked `*-cleanup-required`,
199
+ proves that no capability's spawn hook ran. Missing
200
+ information proves nothing.
201
+ - The **escape hatch is `oats retire <instance> --force`**. This includes
202
+ homes spawned before `capabilityRuntime`, captured homes without proof of
203
+ no spawn hooks, a home without a usable record or cleanup descriptor, and
204
+ a home whose recorded retire hooks have no context repository. Inspect the
205
+ home and clean up external identities and memberships with the provider's
206
+ tooling first. Force can remove the home while leaving that state active;
207
+ its output keeps the warnings about hooks that did not run and state that
208
+ was not revoked. An unreadable `instance.json` still refuses even with
209
+ force. A forced self-retirement carries the force choice into its deferred
210
+ completion. A usable cleanup descriptor can drive the normal retry. Usable
198
211
  means it satisfies the versioned cleanup contract the rollback writes, checked
199
212
  to the depth the retry consumes it: `version`, a context `repo`, a recognised
200
213
  `work` mode (plus a `branch` for `worktree` — an unknown mode would skip the
@@ -245,7 +258,7 @@ A self-contained package has an `oats.json`:
245
258
  verifiably alive (its pid runs with the recorded start time):
246
259
  - `oats status` gives the home's row `spawnInProgress: true` and no
247
260
  `rollbackIncomplete`;
248
- - `oats retire` refuses with `E_LIFECYCLE_BUSY`, `--force` included;
261
+ - `oats retire` refuses with `E_LIFECYCLE_BUSY`, `--plan` and `--force` included;
249
262
  - `oats session start` refuses it as any quarantined home
250
263
  (`E_INSTANCE_RETIRING`).
251
264
 
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
174
235
  ```
175
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));'
260
+ ```
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
@@ -305,6 +398,11 @@ launch-configs:
305
398
  CLAUDE_CONFIG_DIR: /state/home/.claude
306
399
  CLAUDE_CODE_OAUTH_TOKEN:
307
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"
308
406
  ```
309
407
 
310
408
  Select it with `--launch-config team-claude`. The operator provisions only a
@@ -312,6 +410,47 @@ Select it with `--launch-config team-claude`. The operator provisions only a
312
410
  by every agent in the same trust group; read-only mounting does not hide it
313
411
  or narrow its authority. Never share the mount across trust groups.
314
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
+
315
454
  ### After changing a credential
316
455
 
317
456
  A resume starts an agent under the values its last start recorded. When the
@@ -384,17 +523,21 @@ What the image's files fix for that:
384
523
 
385
524
  - **PID-only tini signals the Node supervisor.** It forwards TERM to host
386
525
  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
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
388
529
  host-run exit is reported and drains the other children before a nonzero
389
530
  container exit, so
390
531
  the restart policy can restart it. The broker runs as the agent uid; its
391
532
  default state directory is `/state/home/.config/aw/wake`, so registrations
392
533
  survive container replacement and it starts again even with no spawn.
393
- - **`stop_grace_period: 45s`** in the Compose service. Docker's default is
394
- 10 seconds, shorter than the 20 seconds each harness is given; a container
395
- killed at the timeout leaves agents that were not stopped in order. A
396
- platform that does not read the Compose file needs the same stop timeout
397
- 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.
398
541
  - **A healthcheck on sshd.** The supervisor reports an sshd exit; if
399
542
  sshd ends, the agents and the tick go on and the operator's route is gone.
400
543
  The service's healthcheck opens `127.0.0.1:2222` every 30 seconds (5
@@ -464,7 +607,7 @@ variables. It resolves `AGENT_IMAGE` independently and requires that image's
464
607
  ID, reference and start command, and its complete environment (printing only
465
608
  names of differing variables). Other comparisons include supplementary
466
609
  groups, namespace overrides, sysctls, published ports, resolver overrides
467
- 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
468
611
  healthcheck the service file's, so a container made before either was set
469
612
  is refused until it is recreated. The OCI runtime must match the daemon's
470
613
  independently read default; shared memory stays at Docker's 64 MiB default,
@@ -665,3 +808,60 @@ credentials. The publish step stores
665
808
  registry authentication in a private temporary file and removes it on exit.
666
809
  It receives no npm publish credential. To roll back a deployed image, select
667
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).
@@ -463,8 +463,10 @@ with the soul's merged payload. `oats <namespace> --help --json` answers
463
463
  captured home (`details: {home, captured: true}`), the selectors
464
464
  `--deployment`, `--resolution` and `--artifact-set` (`details.selector`), and
465
465
  an inherited `OATS_DEPLOYMENT` or `OATS_RESOLUTION` (`details.inherited`).
466
- `oats version` and `oats retire` still work. `oats status --json` names such
467
- homes in `problems[]`: `legacy-captured-home {code, instances, homes,
466
+ `oats version` still answers. For captured homes, inspect and clean up external
467
+ state first; without positive proof that no spawn hook ran, retirement needs
468
+ `oats retire <instance> --force`. `oats status --json` names such homes in
469
+ `problems[]`: `legacy-captured-home {code, instances, homes,
468
470
  message}` and `legacy-local-agents {code, dirs, instances, message}`.
469
471
 
470
472
  <a id="observation-reuse-feature-observe-max-age-oats-0311"></a>
@@ -5675,6 +5677,9 @@ had begun.
5675
5677
  | `E_AMBIGUOUS` | yes | yes |
5676
5678
  | `E_SNAPSHOT_UNKNOWN` | yes | yes |
5677
5679
 
5680
+ `E_UNIDENTIFIED_INSTANCE_HOME` includes cleanup-hook admission in both retire
5681
+ plan and apply; the refusal returns no work facts when the home cannot be identified.
5682
+
5678
5683
  `E_HOME_NOT_OWNED` is the answer of every command that takes a home's
5679
5684
  lifecycle claim (a start, a resume, a stop, a retire, an upgrade) when the
5680
5685
  user it runs as does not own the home. It is answered before the claim is
@@ -6578,13 +6583,10 @@ message names the entry or the state that could not be read, or the directory
6578
6583
  Git reads as the top level of a `work/` whose `core.worktree` names another
6579
6584
  one),
6580
6585
  `E_SESSION_UNKNOWN`, `E_AMBIGUOUS_INSTANCE`,
6581
- `E_UNIDENTIFIED_INSTANCE_HOME` (a home with no `instance.json` and no cleanup
6582
- descriptor, or a rollback marker that cannot drive a retry, or an
6583
- `instance.json` that names no repository and does not show that no capability
6584
- has a retire hook, what a spawn killed before its record leaves
6585
- ([capabilities.md](capabilities.md#manifest)), until `--force`;
6586
- a home whose `instance.json` [cannot be read](#unreadable-record), `--plan`
6587
- and `--force` included),
6586
+ `E_UNIDENTIFIED_INSTANCE_HOME` (a missing or unusable cleanup record, or
6587
+ recorded hooks that cannot run without proof that no cleanup is owed, until
6588
+ `--force`; a home whose `instance.json` [cannot be read](#unreadable-record)
6589
+ refuses even with `--plan` or `--force`),
6588
6590
  `E_NO_ROOT`, `E_LIFECYCLE_FAILED`, `E_LIFECYCLE_BUSY` (another retire of the
6589
6591
  home is running or scheduled, or a stop of it is running, `--force`
6590
6592
  included: one retire or stop of a home at a time, above; or, feature
@@ -6592,8 +6594,20 @@ included: one retire or stop of a home at a time, above; or, feature
6592
6594
  hooks, a row with `spawnInProgress: true`, `--force` included; or one whose start time
6593
6595
  cannot be read, a `rollbackIncomplete` row, until `--force`; or a hook or git
6594
6596
  group whose leader's start cannot be read, until `--force`; every one is
6595
- answered before any effect and carries [`details.holder`](#busy-holder)). The
6596
- codes a retire answers only before any effect are
6597
+ answered before any effect and carries [`details.holder`](#busy-holder)).
6598
+
6599
+ Hook admission refuses both `--plan` (including Desktop Remove) and apply
6600
+ before anything is stopped, run or removed, children included. Causes include
6601
+ homes spawned before `capabilityRuntime`, recorded retire hooks without a
6602
+ context repository (recorded or identified by Git for its own worktree),
6603
+ and captured homes from before 0.26 without positive proof that no spawn hook ran. An ordinary home's explicit capability set with
6604
+ no retire hooks proves no hook is owed. Captured proof also excludes any
6605
+ recorded hook intents, failures or lifecycle cleanup debt. The refusal names
6606
+ known capabilities, external identities/memberships at risk, and the remedy:
6607
+ clean up with the provider's tooling, then `oats retire <instance> --force`.
6608
+ See [the cleanup rule](capabilities.md#manifest).
6609
+
6610
+ The codes a retire answers only before any effect are
6597
6611
  [one list](#before-effect-codes). A recovery whose Git status disagrees with
6598
6612
  the source's carries `details: {home, statusDisagreement: {repo, rows: [{path,
6599
6613
  source, recovery}], total}}` (the first 10 paths). A worktree recovery whose
package/docs/desktop.md CHANGED
@@ -1101,6 +1101,22 @@ computer, and for an instance on a server, on that server too; until then the
1101
1101
  buttons are disabled and the dialog says which is missing. An instance whose
1102
1102
  home is being spawned or retired can't be given a colour meanwhile.
1103
1103
 
1104
+ ## An instance's owning human
1105
+
1106
+ Where the messaging capability attributes an instance's messaging identity to
1107
+ a human, the instance panel's Lineage section shows that human first, as
1108
+ **Owning human**, above the instance's parent and sibling. It is the
1109
+ `attributedHuman` of the instance's row in `oats status --json`, and of a
1110
+ server's row for an instance on a server
1111
+ ([Attributed human](desktop-cli-api.md#attributed-human)), shown as OATS
1112
+ reports it. The instance is still named by its own name everywhere: the
1113
+ sidebar, its terminal tab, the command palette and the panel's header.
1114
+
1115
+ An instance with no human attributed shows no such field, and nothing says
1116
+ one is missing: that is the usual case, on a deployment whose messaging
1117
+ capability supplies no human identities and for an older OATS that doesn't
1118
+ report it. A label OATS would not show as one line of text reads the same way.
1119
+
1104
1120
  ## Identity marks and harness badges
1105
1121
 
1106
1122
  Souls, capabilities and workspaces carry a coloured two-letter mark beside
@@ -84,7 +84,7 @@ and the rules its tests pin.
84
84
  | `lib/` | the kernel (below) |
85
85
  | `injects/` | the kernel and work-mode instruction blocks composed into every instance |
86
86
  | `skills/` | bootstrap skills shipped with the kernel |
87
- | `capabilities/` | this repository's own member capabilities, discovered at the member's latest state: `oats-desktop-ui`, `oats-workspace-experts`, and the copy of the engineering template (`oats-dispatcher`, `oats-engineering-expert`, `oats-developer`, `oats-build`, `oats-code-review`, `oats-maintainer`, `oats-landing-rules`; the release it came from in `TEMPLATE-RELEASE`, its MIT notice in `TEMPLATE-LICENSE`, the notices of the sources its build skills adapt in `THIRD-PARTY-NOTICES.md`) that the framework's own souls compose |
87
+ | `capabilities/` | this repository's own member capabilities, discovered at the member's latest state: `oats-desktop-ui`, `oats-workspace-experts`, and the copy of the engineering template (`oats-dispatcher`, `oats-engineering-expert`, `oats-developer`, `oats-build`, `oats-code-review`, `oats-maintainer`, `oats-landing-rules`; the release it came from in `TEMPLATE-RELEASE`, its MIT notice in `TEMPLATE-LICENSE`, the notices of the sources its build skill and its quality floor adapt in `THIRD-PARTY-NOTICES.md`) that the framework's own souls compose |
88
88
  | `mirrors/` | copies of the official packages' capabilities at their pinned tags: release-lane and test material, kept out of `capabilities/` so member discovery does not list them a second time; not shipped in the npm package. The three OKF mirrors (`oats-okf*`) are generated by `scripts/check-okf-mirror.mjs` and checked byte for byte against `scripts/okf-source-inventory.json`; the other seven (`oats-aweb`, `oats-aweb-tasks`, `oats-folio`, `oats-library`, `oats-jira`, `oats-linear`, `oats-authoring`) are copied from their tags by hand and checked for their version only, until every mirror has that check (oats-project/oats#1848) |
89
89
  | `oats-package/` | the `oats.framework` package |
90
90
  | `souls/` | this repository's own souls (a workspace member) |
@@ -153,6 +153,7 @@ and the rules its tests pin.
153
153
  | `retire-output.mjs` | the lines `oats retire` prints for preserved work, one function for the local and the remote path |
154
154
  | `status-words.mjs` | the word `oats status`, `oats status --server` and `oats server roster` print for an instance row (RUNNING, LOST, idle, unknown, RETIRING; the roster keeps its own suffixes) and the line under a LOST row that names the way back; rows in, strings out, the JSON untouched |
155
155
  | `retire-git-forms.mjs` | which of a retire's Git commands read no work-tree file, by their exact form: the ones `core.mjs` runs without the overrides of the repository's filter drivers |
156
+ | `retire-admission.mjs` | the shared internal preflight for Remove plans and retire apply: the record reader, cleanup descriptor validator, positive hook-cleanup proof and spawn liveness read. Both callers import it directly. `core.mjs` re-exports only its existing record readers and constants from this leaf, by reference; admission itself is not public API |
156
157
  | `retire-state.mjs` | a status row's `retire` (feature `status-retire-state`): `readRetireState`, the one read of the value, which the local row (`core.mjs` `retireStateOf`, from the marker, its result and the home's claim) and the remote roster's relay (`servers.mjs` `rowRetire`) both go through. Pure; status only reads, so nothing here takes a claim, removes a file or signals a process |
157
158
  | `retained-after-retire.mjs` | what retires left behind (recovery copies, retained worktrees) as `oats doctor` information lines: read-only, Git through `instance-git.mjs`'s helper-free reads |
158
159
  | `retire-incomplete.mjs` | retirements left open (a quarantine, a failed or interrupted self-retire) as `oats doctor`'s `retire-incomplete` problems (oats-project/oats#1747), read with `instance-listing.mjs`'s `openRetirements`, the readers of the status rows: read-only, no claim, no tmux |
@@ -40,7 +40,7 @@ arrives from.
40
40
  ```yaml
41
41
  # oats-workspace.yaml: one default per slot, for every soul
42
42
  packages:
43
- oats.okf: v6.0.3
43
+ oats.okf: v6.2.0
44
44
  oats.aweb: v1.42.1
45
45
  oats.linear: v1.0.1
46
46
  oats.jira: v1.0.1
package/docs/knowledge.md CHANGED
@@ -6,7 +6,7 @@ kernel owns slot selection, composition and command dispatch; the capability
6
6
  owns its knowledge format, instructions and promotion procedure. The model is
7
7
  in [Knowledge, instances and evolving expertise](knowledge-theory.md).
8
8
 
9
- This is the operator guide for **oats.okf 6.0.3** (OATS **>=0.69.2**). Provider implementation and
9
+ This is the operator guide for **oats.okf 6.2.0** (OATS **>=0.69.2**). Provider implementation and
10
10
  recovery details belong to the [oats-okf README](https://github.com/awebai/oats-okf).
11
11
  In 6.0 there is no knowledge harvester: a working instance proposes its own
12
12
  knowledge as a pull request at its checkpoints (`oats okf propose`), and the
@@ -28,7 +28,7 @@ knowledge maintainer gates every merge.
28
28
  ```yaml
29
29
  # oats-workspace.yaml (excerpt)
30
30
  packages:
31
- oats.okf: v6.0.3
31
+ oats.okf: v6.2.0
32
32
  defaults:
33
33
  knowledge: { oats.okf: { from: package } }
34
34
  stores:
@@ -56,9 +56,9 @@ Upgrading from 4.x requires the ordered
56
56
  just editing a version line. The package requires OATS >=0.69.2: its
57
57
  `knowledge-maintainer` soul says `background: true`, which an older kernel
58
58
  refuses. Upgrade OATS first, then the package. Each 5.x step is in
59
- [oats.okf's CHANGELOG](https://github.com/oats-project/oats-okf/blob/v6.0.3/CHANGELOG.md).
59
+ [oats.okf's CHANGELOG](https://github.com/oats-project/oats-okf/blob/v6.2.0/CHANGELOG.md).
60
60
 
61
- **Upgrade to 6.0:** pin `oats.okf: v6.0.3` and run `oats sync`. Only new
61
+ **Upgrade to 6.0:** pin `oats.okf: v6.2.0` and run `oats sync`. Only new
62
62
  spawns get `oats okf propose`, the 6.0 `okf-propose` skill and the
63
63
  spawn-recorded duty. Existing homes keep their copied provider even after a
64
64
  session restart; a stopped 5.x home can move with `oats instance upgrade`
@@ -67,7 +67,7 @@ remedy to retire and respawn it. Harvester spawns stop: the stub soul
67
67
  `oats.okf/knowledge-harvester`, kept until 7.0, refuses every spawn with
68
68
  `E_REMOVED` and the fix. Harvesters already running keep their 5.x modules
69
69
  and finish, or a person retires them. Then, by hand, from the deployment
70
- (oats.okf's [Upgrading to 6.0](https://github.com/oats-project/oats-okf/blob/v6.0.3/README.md#upgrading-to-60)
70
+ (oats.okf's [Upgrading to 6.0](https://github.com/oats-project/oats-okf/blob/v6.2.0/README.md#upgrading-to-60)
71
71
  has each step's commands):
72
72
 
73
73
  1. Delete the harvester's launch preference, if any:
@@ -9,8 +9,8 @@ or workspace membership alone does not make a package official.
9
9
 
10
10
  | package | release | capabilities | package souls |
11
11
  |---|---|---|---|
12
- | `oats.framework` | `oats-framework/v1.25.2` (this repository) | `oats.core`, `oats.setup`, `oats.onboarding`, `oats.support`, `oats.knowledge-theory`, `oats.coordination-setup` | `knowledge-theory-expert`, `oats-setup-expert` |
13
- | `oats.okf` | `v6.0.3` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
12
+ | `oats.framework` | `oats-framework/v1.26.0` (this repository) | `oats.core`, `oats.setup`, `oats.onboarding`, `oats.support`, `oats.knowledge-theory`, `oats.coordination-setup` | `knowledge-theory-expert`, `oats-setup-expert` |
13
+ | `oats.okf` | `v6.2.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
14
  | `oats.aweb` | `v1.42.1` | `oats.aweb` (messaging), `oats.aweb-tasks` (tasks) | |
15
15
  | `oats.engineering` | `v1.18.0` (frozen: see Coordination templates) | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
16
16
  | `oats.authoring` | `v1.0.3` | `oats.authoring` | |
@@ -49,7 +49,7 @@ release it came from in its description, and the copy records it as a whole in
49
49
 
50
50
  | Template | Latest release | Way of working |
51
51
  | --- | --- | --- |
52
- | `oats-project/oats-engineering-coordination` | `template-v3.1.3` | Work that lands as pull requests: a dispatcher, a lead for each effort that builds a change itself or sends developers, whoever builds it iterating with a fresh reviewer each round, and a maintainer where a lane needs one. |
52
+ | `oats-project/oats-engineering-coordination` | `template-v4.0.2` | Work that lands as pull requests: a dispatcher, a lead for each effort with a tree sized to the work (alone, with short-lived probes and helpers, or with one specialist per area), whoever builds a change iterating with a fresh reviewer each round, a maintainer's green light where a lane asks for one, and every finished instance retiring itself. |
53
53
  | `oats-project/oats-research-coordination` | `template-v2.1.2` | Work that ends in a finding or a report: a dispatcher, a research lead for each question that researches a single small angle itself or sends a researcher for each, and a verifier briefed to disprove, which checks the lead's own claims too. A report lands when the person who asked accepts it. |
54
54
  | `oats-project/oats-scientific-research-coordination` | `template-v2.1.2` | Studies that end in claims a person is accountable for: a dispatcher, a study lead for each study, an analyst for each arm of a locked protocol, fresh study reviewers for the methods, an independent check, leakage and citations, and a record steward that locks protocols and keeps the study records. A claim lands when the scientist accepts it; one that leaves the group needs a check that isn't LLM judgement. |
55
55
 
@@ -64,7 +64,7 @@ aliases, a later decision once no workspace we know of pins it.
64
64
  ## Find and use packages
65
65
 
66
66
  - A workspace pins an official package by **bare version** in its
67
- `packages:` map (`oats.okf: v6.0.3`); `oats sync` resolves it through the
67
+ `packages:` map (`oats.okf: v6.2.0`); `oats sync` resolves it through the
68
68
  catalog to an exact commit, fetches it, verifies its integrity and locks it.
69
69
  A package outside the catalog is written `git:<repo>@<ref>`. Pinning does
70
70
  not join a team or adopt the publisher's workspace. See