@awebai/oats 0.69.19 → 0.69.21

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 (46) hide show
  1. package/bin/oats.mjs +28 -5
  2. package/docs/capabilities.md +27 -14
  3. package/docs/capability-manifest.schema.json +1 -1
  4. package/docs/container.md +218 -18
  5. package/docs/desktop-cli-api.md +105 -11
  6. package/docs/desktop.md +122 -65
  7. package/docs/implementation.md +3 -2
  8. package/docs/integrations.md +2 -2
  9. package/docs/knowledge.md +5 -5
  10. package/docs/official-catalog.md +5 -5
  11. package/docs/packages.md +13 -13
  12. package/docs/release-notes/v0.69.20.md +325 -0
  13. package/docs/release-notes/v0.69.21.md +155 -0
  14. package/docs/servers.md +9 -3
  15. package/docs/souls-and-instances.md +15 -2
  16. package/docs/upgrading.md +17 -5
  17. package/docs/workspaces.md +13 -7
  18. package/lib/capability-contract.mjs +2 -2
  19. package/lib/command-flags.mjs +1 -0
  20. package/lib/core.mjs +36 -198
  21. package/lib/hook-outcome.mjs +6 -0
  22. package/lib/instance-inspect.mjs +3 -0
  23. package/lib/instance-lifecycle.mjs +19 -1
  24. package/lib/instance-listing.mjs +11 -6
  25. package/lib/instance-pin.mjs +59 -0
  26. package/lib/kernel-features.mjs +1 -1
  27. package/lib/launch-prompt-fixtures/README.md +6 -0
  28. package/lib/retire-admission.mjs +215 -0
  29. package/lib/servers.mjs +11 -3
  30. package/package-catalog.json +3 -3
  31. package/package.json +1 -1
  32. package/packages/client/attributed-human.mjs +13 -0
  33. package/packages/client/deployment-data.mjs +4 -0
  34. package/packages/client/deployment-panel.mjs +2 -0
  35. package/packages/client/instance-lifecycle.mjs +6 -4
  36. package/packages/client/lifecycle-confirmation.mjs +4 -2
  37. package/packages/client/lifecycle-contract.mjs +11 -6
  38. package/packages/client/remote-roster.mjs +4 -0
  39. package/packages/client/roster-row-facts.mjs +50 -0
  40. package/packages/record/README.md +15 -2
  41. package/packages/record/docs/capture-service.md +14 -0
  42. package/packages/record/lib/canonical.mjs +2 -70
  43. package/packages/record/lib/capture-aw-unit.mjs +14 -3
  44. package/packages/record/lib/capture-aw.mjs +11 -5
  45. package/packages/record/lib/capture-health.mjs +16 -5
  46. package/skills/oats-getting-started/SKILL.md +211 -28
package/bin/oats.mjs CHANGED
@@ -83,7 +83,7 @@ const { hostUnitFiles, hostUnitStatus, installHostUnit, uninstallHostUnit } = aw
83
83
  const { kernelNode, stableNode } = await kernelImport("stable-node", () => import("../lib/stable-node.mjs"));
84
84
  const { receiveAttachment, uploadAttachment, readStreamBounded, MAX_ATTACHMENT_BYTES } = await kernelImport("attachments", () => import("../lib/attachments.mjs"));
85
85
  const { observeInstanceGit, diffInstanceFile, NO_FILE_MONITOR } = await kernelImport("instance-git", () => import("../lib/instance-git.mjs"));
86
- const { planStop, applyStop, planRetire, retireDefaultsLine, stopClosingLine, descendantsOf, resolveInstance: resolveInstanceForCli, setInstanceColor, setInstanceBackground, setInstanceSameWork, STOP_WARNINGS } = await kernelImport("instance-lifecycle", () => import("../lib/instance-lifecycle.mjs"));
86
+ const { planStop, applyStop, planRetire, retireDefaultsLine, stopClosingLine, descendantsOf, resolveInstance: resolveInstanceForCli, setInstanceColor, setInstanceBackground, setInstancePin, setInstanceSameWork, STOP_WARNINGS } = await kernelImport("instance-lifecycle", () => import("../lib/instance-lifecycle.mjs"));
87
87
  const { extraWorktreeLines, formatBytes, warningLines, workRecoveryLines } = await kernelImport("retire-output", () => import("../lib/retire-output.mjs"));
88
88
  const { livenessWord, lostLine, statusWord, waitingLine } = await kernelImport("status-words", () => import("../lib/status-words.mjs"));
89
89
  const { retainedRecoveryLines, retainedWorktreeLines, retainedWorktrees } = await kernelImport("retained-after-retire", () => import("../lib/retained-after-retire.mjs"));
@@ -1453,8 +1453,8 @@ async function instanceCmd() {
1453
1453
  if (sub === "upgrade") return instanceUpgradeCmd(name, bail);
1454
1454
  if (sub === "waiting" || sub === "attention") return instanceWaitingCmd(sub, bail);
1455
1455
  if (sub === "suggest-name") return instanceSuggestNameCmd(bail);
1456
- const usage = "usage: oats instance waiting <set|clear> --producer <id> [--reason permission|question|attention] [--message=<text>] [--home <abs>] [--dir <d>] [--json] | oats instance attention [--message=<text>] [--clear] [--json] | oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--dir <d>] [--json] | oats instance git <instance> [--home <abs>] [--dir <d>] [--json] | oats instance diff <instance> --file <id> --revision <rev> [--index-revision <rev>] [--home <abs>] [--dir <d>] [--json] | oats instance stop <instance> (--plan | --apply --plan-revision <rev> --idempotency-key <key>) [--no-recursive] [--grace-ms <n>] [--home <abs>] [--dir <d>] [--json] | oats instance color <instance> (<color> | --clear) [--home <abs>] [--dir <d>] [--json] | oats instance background <instance> on|off [--home <abs>] [--dir <d>] [--json] | oats instance same-work <instance> on|off [--home <abs>] [--dir <d>] [--json]";
1457
- if (!["git", "diff", "stop", "events", "color", "background", "same-work"].includes(sub) || !name || name.startsWith("--")) return bail("E_BAD_ARGS", usage);
1456
+ const usage = "usage: oats instance waiting <set|clear> --producer <id> [--reason permission|question|attention] [--message=<text>] [--home <abs>] [--dir <d>] [--json] | oats instance attention [--message=<text>] [--clear] [--json] | oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--dir <d>] [--json] | oats instance git <instance> [--home <abs>] [--dir <d>] [--json] | oats instance diff <instance> --file <id> --revision <rev> [--index-revision <rev>] [--home <abs>] [--dir <d>] [--json] | oats instance stop <instance> (--plan | --apply --plan-revision <rev> --idempotency-key <key>) [--no-recursive] [--grace-ms <n>] [--home <abs>] [--dir <d>] [--json] | oats instance color <instance> (<color> | --clear) [--home <abs>] [--dir <d>] [--json] | oats instance background <instance> on|off [--home <abs>] [--dir <d>] [--json] | oats instance pin <instance> on|off [--home <abs>] [--dir <d>] [--json] | oats instance same-work <instance> on|off [--home <abs>] [--dir <d>] [--json]";
1457
+ if (!["git", "diff", "stop", "events", "color", "background", "pin", "same-work"].includes(sub) || !name || name.startsWith("--")) return bail("E_BAD_ARGS", usage);
1458
1458
  dropAmbientRoot();
1459
1459
  if (sub === "events") {
1460
1460
  // K7: typed producer events, bounded window; nothing inferred.
@@ -1528,6 +1528,25 @@ async function instanceCmd() {
1528
1528
  return lifecycleFail(e, "E_LIFECYCLE_FAILED", e.candidates ? { candidates: e.candidates } : e.details);
1529
1529
  }
1530
1530
  }
1531
+ if (sub === "pin") {
1532
+ // Feature instance-pin: presentation only, so no plan; addressed as `instance background` addresses an instance.
1533
+ const homeOpt = flag("home");
1534
+ if (homeOpt === true || (homeOpt !== undefined && !isAbsolute(homeOpt))) return bail("E_BAD_ARGS", "--home needs an absolute instance home");
1535
+ const pinUsage = "usage: oats instance pin <instance> on|off [--home <abs>] [--dir <d>] [--json]";
1536
+ // The words after the instance that are not a flag or the value of --home or --dir: exactly one, on or off.
1537
+ const words = [];
1538
+ for (let i = 3; i < args.length; i++) { if (args[i] === "--home" || args[i] === "--dir") i++; else if (!args[i].startsWith("--")) words.push(args[i]); }
1539
+ if (words.length !== 1 || !["on", "off"].includes(words[0])) return bail("E_BAD_ARGS", `give on or off; ${pinUsage}`);
1540
+ let root; try { root = ensureRoot(dirFlag()); } catch (e) { return lifecycleFail(e, "E_NO_ROOT"); }
1541
+ try {
1542
+ const r = setInstancePin(dirFlag(), root, name, { home: homeOpt, pinned: words[0] === "on" });
1543
+ if (JSON_MODE) { jsonOk(r); return; }
1544
+ console.log(`${r.instance}: ${r.pinned ? "pinned" : "not pinned"}${r.changed ? "" : " (unchanged)"}`);
1545
+ return;
1546
+ } catch (e) {
1547
+ return lifecycleFail(e, "E_LIFECYCLE_FAILED", e.candidates ? { candidates: e.candidates } : e.details);
1548
+ }
1549
+ }
1531
1550
  if (sub === "same-work") {
1532
1551
  // Feature instance-same-work: presentation only, so no plan; addressed as color addresses an instance.
1533
1552
  const homeOpt = flag("home");
@@ -3012,7 +3031,7 @@ function retireCmd() {
3012
3031
  dropAmbientRoot();
3013
3032
  let root; try { root = ensureRoot(dirFlag()); } catch (e) { return lifecycleFail(e, "E_NO_ROOT"); }
3014
3033
  try {
3015
- const plan = planRetire(dirFlag(), root, name, { home: homeFlag });
3034
+ const plan = planRetire(dirFlag(), root, name, { home: homeFlag, force: args.includes("--force") });
3016
3035
  if (args.includes("--json")) { jsonOk(plan); return; }
3017
3036
  console.log(`retire ${name} — plan ${plan.planRevision}`);
3018
3037
  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 +3080,7 @@ function retireCmd() {
3061
3080
  // its extra trees as it names them (the retire refuses as stale rather than move or remove one
3062
3081
  // that no longer reads that way when it gets to them).
3063
3082
  revalidate = () => {
3064
- try { fresh = planRetire(dirFlag(), root, name, { home: homeFlag }); } catch (e) { planFailure = e; throw e; }
3083
+ try { fresh = planRetire(dirFlag(), root, name, { home: homeFlag, force: args.includes("--force") }); } catch (e) { planFailure = e; throw e; }
3065
3084
  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
3085
  return { plannedExtraWorktrees: fresh.facts.extraWorktrees, children: fresh.facts.children, ambiguous: fresh.facts.ambiguous };
3067
3086
  };
@@ -5245,6 +5264,10 @@ Usage:
5245
5264
  oats instance background <instance> on|off [--home <abs>] [--json]
5246
5265
  whether clients list the instance under
5247
5266
  Background, presentation only
5267
+ oats instance pin <instance> on|off [--home <abs>] [--json]
5268
+ pin the instance at the top of its machine's
5269
+ list; shared, as every viewer of the machine
5270
+ reads it from the home
5248
5271
  oats instance same-work <instance> on|off [--home <abs>] [--json]
5249
5272
  record that this instance does the same work as
5250
5273
  its parent (on needs a recorded parent); clients
@@ -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
 
@@ -320,7 +333,7 @@ A self-contained package has an `oats.json`:
320
333
  - an exact name that is `.oats`, `.agents` or `.claude`, or that starts
321
334
  with `.oats-events`, `.oats-stop`, `.oats-restart`, `.oats-rollback`,
322
335
  `.oats-agents-md`, `.oats-start`, `.oats-attachments`, `.oats-color`,
323
- `.oats-background` or `.oats-same-work`: the top-level entries the kernel
336
+ `.oats-background`, `.oats-pinned` or `.oats-same-work`: the top-level entries the kernel
324
337
  itself writes in an instance home;
325
338
  - a prefix that starts with `.oats-`.
326
339
 
@@ -374,7 +374,7 @@
374
374
  "description": "Home entries the kernel owns cannot be declared.",
375
375
  "anyOf": [
376
376
  {"pattern": "^\\.(?:oats|agents|claude)$"},
377
- {"pattern": "^\\.oats-(?:events|stop|restart|rollback|agents-md|start|attachments|color|background|same-work)"},
377
+ {"pattern": "^\\.oats-(?:events|stop|restart|rollback|agents-md|start|attachments|color|background|pinned|same-work)"},
378
378
  {"pattern": "^\\.oats-.*\\*$"}
379
379
  ]
380
380
  }
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).