@awebai/oats 0.69.12 → 0.69.14

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 (70) hide show
  1. package/README.md +216 -178
  2. package/bin/oats.mjs +176 -184
  3. package/docs/capabilities.md +4 -1
  4. package/docs/configuration.md +63 -5
  5. package/docs/container.md +246 -0
  6. package/docs/design/2026-09-23-workspace-module-contracts.md +2 -0
  7. package/docs/desktop-cli-api.md +376 -37
  8. package/docs/desktop-instance-start.md +4 -1
  9. package/docs/desktop.md +58 -12
  10. package/docs/execution-targets.md +69 -6
  11. package/docs/implementation.md +86 -29
  12. package/docs/integrations.md +3 -2
  13. package/docs/knowledge-and-learning.md +72 -0
  14. package/docs/oats-local.schema.json +11 -2
  15. package/docs/official-catalog.md +39 -5
  16. package/docs/packages.md +93 -14
  17. package/docs/release-lane.md +2 -1
  18. package/docs/release-notes/v0.69.13.md +767 -0
  19. package/docs/release-notes/v0.69.14.md +83 -0
  20. package/docs/schedules.md +26 -3
  21. package/docs/servers.md +181 -5
  22. package/docs/souls-and-instances.md +140 -11
  23. package/docs/tui.md +1 -1
  24. package/docs/upgrading.md +24 -5
  25. package/docs/workspaces.md +31 -5
  26. package/lib/claim.mjs +21 -5
  27. package/lib/command-flags.mjs +238 -0
  28. package/lib/core.mjs +791 -563
  29. package/lib/deployments.mjs +4 -3
  30. package/lib/dir-lock.mjs +126 -31
  31. package/lib/errors.mjs +1 -1
  32. package/lib/harness-token.mjs +110 -0
  33. package/lib/hot-reads.mjs +4 -3
  34. package/lib/instance-events.mjs +28 -6
  35. package/lib/instance-git.mjs +138 -13
  36. package/lib/instance-inspect.mjs +6 -1
  37. package/lib/instance-listing.mjs +80 -38
  38. package/lib/instance-resolution.mjs +56 -3
  39. package/lib/instance-upgrade.mjs +16 -20
  40. package/lib/launch-env-exec.sh +7 -0
  41. package/lib/launch-env.mjs +74 -0
  42. package/lib/launch-preference.mjs +19 -12
  43. package/lib/member-clone.mjs +7 -1
  44. package/lib/packages.mjs +74 -2
  45. package/lib/read-call.mjs +3 -0
  46. package/lib/reader.mjs +3 -2
  47. package/lib/refused-text.mjs +3 -2
  48. package/lib/remote.mjs +119 -27
  49. package/lib/retained-after-retire.mjs +2 -7
  50. package/lib/retire-git-forms.mjs +41 -0
  51. package/lib/retire-incomplete.mjs +96 -0
  52. package/lib/schedule.mjs +2 -1
  53. package/lib/servers.mjs +78 -23
  54. package/lib/session-resume.mjs +68 -53
  55. package/lib/session-seen.mjs +54 -5
  56. package/lib/start-env.mjs +13 -7
  57. package/lib/system-tools.mjs +1 -1
  58. package/lib/teams.mjs +11 -4
  59. package/lib/upgrade-state.mjs +13 -2
  60. package/lib/worktree.mjs +56 -7
  61. package/package-catalog.json +1 -1
  62. package/package.json +2 -1
  63. package/packages/client/instance-lifecycle.mjs +1 -1
  64. package/packages/client/lifecycle-contract.mjs +3 -1
  65. package/packages/client/session-resume-cli.mjs +2 -1
  66. package/packages/client/session-start.mjs +10 -7
  67. package/packages/client/workspace-cli.mjs +5 -1
  68. package/share/oats-login-receive +204 -0
  69. package/skills/oats-getting-started/SKILL.md +92 -25
  70. package/lib/tmux-config.mjs +0 -35
@@ -693,7 +693,10 @@ instance session they are the session's.
693
693
  soul-set value from a host-set one there, and never reads `soul.yaml` for it;
694
694
  a home with none recorded gives `{}`. A final JSON line may return `meta`,
695
695
  `brief`, `warning`, or harness-specific `launch` arguments; a preview-aware
696
- launch hook's preview answer may add `volatileEnv` (below). A **spawn or
696
+ launch hook's preview answer may add `volatileEnv` (below). A retire hook's
697
+ `warning` is in the retire's `warnings` and, as a `retire-warning` event, in
698
+ the instance's workspace log, readable with `oats instance events` after the
699
+ home is gone ([Events](desktop-cli-api.md#events)). A **spawn or
697
700
  launch hook** may also return an `env` object for the launched process;
698
701
  returning `env` from a retire or [worktree](#the-worktree-event) hook is an
699
702
  explicit contract error.
@@ -64,7 +64,7 @@ refused (`E_WORKSPACE_SCHEMA`).
64
64
  | `settings.<cap>.<key>` | Host-owned values a capability's manifest asks for: absolute paths, state roots, delivery modes. The workspace file refuses absolute paths; they go here. Merged into the capability's provider payload after the soul's own and before any `--provider` flag ([three homes](workspaces.md#provider-payloads-have-three-homes)). |
65
65
  | `teams.<label>` | A **local** team: `{ team: <provider team id>, description? }`, a team only this deployment uses; every soul may join it. Allowed only where `oats-workspace.yaml` says `localTeams: true` (or in the standalone view); otherwise refused (`E_WORKSPACE_SCHEMA`, reason `local-teams-closed`). Shared teams are committed in `oats-workspace.yaml`; a label in both is `team-label-collision` (the shared one wins). Written by `oats teams add <label> --team <id>` and `oats teams remove <label>`. |
66
66
  | `defaultTeam` | This deployment's default team: a label of a local or shared team, under the same condition as `teams`. A soul's own default in the workspace's `souls:` wins over it; it wins over the workspace's `defaultTeam`. The first `oats teams add` sets it (unless `--no-default`); `oats teams default <label>` changes it, and `--if-absent` / `--expect <label>` change it only where there is no effective default / it is that label. |
67
- | `souls.disabled` | Souls not run on this machine; a spawn is refused with `E_SOUL_DISABLED`. A bare name disables every soul of that name; `<package>/<soul>` or `<member>/<soul>` disables one. It is for a soul that must not run here (broken, or not for this machine), with the reason in a comment; it is not a gate for souls without a `launch:`, which take the host default like any launch nobody named (see [Launch preferences](#launch-preferences)). |
67
+ | `souls.disabled` | Souls not run on this machine; a spawn is refused with `E_SOUL_DISABLED`. A bare name disables every soul of that name; `<package>/<soul>` or `<member>/<soul>` disables one. It is for a soul that must not run here (broken, or not for this machine), with the reason in a comment; it is not a gate for souls without a `launch:`, which take the host default like any launch nobody named (see [Launch preferences](#launch-preferences)). An entry is matched by exact name only, so one whose soul was renamed or moved (a removed package pin, for example) names no soul and keeps nothing off: it fails open, and the soul becomes spawnable again under its new name, unlike a stale `souls.launch` key, which fails closed. Run `oats doctor` after any rename or removal: it reports such an entry as `disabled-soul-unmatched`, with the nearest souls ([what doctor reports](desktop-cli-api.md#launch-preferences)). |
68
68
  | `session.tmuxSession` | The tmux session new tmux instances open their windows in (0.31). Absent: `OATS_TMUX_SESSION`, else `PI_AGENTS_TMUX_SESSION` (the pre-0.31 variable), else `oats-agents`. `session: { tmuxSession: pi-agents }` keeps the pre-0.31 layout. `oats inspect --json` reports it as `session`. |
69
69
  | `host.name` | This machine's name. A workspace trigger or schedule runs only on the host named by its `runsOn` ([schedules.md](schedules.md)). |
70
70
  | `automations.trust` | The workspace triggers and schedules (`<member>/<id>`) this host agrees to run, or `"*"` for every one the workspace places here (0.30). Absent or empty: none runs. See [Who runs workspace automations](#who-runs-workspace-automations). |
@@ -289,7 +289,7 @@ instance's terminal and press Enter yourself.
289
289
  An entry has `harness` (`pi` \| `claude` \| `codex`, required), `executable`
290
290
  (a bare name looked up on `PATH`, or a path relative to the directory of the
291
291
  file that declares it), `args` (literal, no shell), `env` (a literal string, or
292
- `{ fromEnv: NAME }` resolved on the host at start), `model`, `yolo` and
292
+ `{ fromEnv: NAME }` or `{ fromFile: /absolute/path }` resolved on the host at start), `model`, `yolo` and
293
293
  `default` (0.32; see [the harness default](#the-harness-default)). A launch
294
294
  configuration is a host choice: a soul never names one.
295
295
 
@@ -450,7 +450,7 @@ launch: { harness: claude, model: claude-opus-5-5 }
450
450
  souls:
451
451
  launch:
452
452
  "*": personal # a launch configuration, for every soul here
453
- oats-expert: { harness: claude, model: claude-opus-5-5 }
453
+ oats-engineering-expert: { harness: claude, model: claude-opus-5-5 }
454
454
  oats.engineering/code-reviewer: { harness: codex } # a package soul
455
455
  ```
456
456
 
@@ -552,6 +552,64 @@ source variable must be set on the host (`E_LAUNCH_ENV_MISSING`, before
552
552
  anything is created or stopped), and only the harness's pane receives it.
553
553
  `list` and `preview` redact every environment value, literals included.
554
554
 
555
+ `{ fromFile: /absolute/path }` reads a regular UTF-8 file on the host that
556
+ starts the harness, at every start. The source is limited to 64 KiB, including
557
+ any final newline; larger files are refused before reading their contents.
558
+ It removes exactly one trailing LF or
559
+ CRLF; an empty file is allowed. Invalid UTF-8 and NUL are refused. A leading
560
+ UTF-8 BOM is preserved as part of the value. `fromFile` is for credential
561
+ values; directory selectors (`HOME`, `PATH`, `CLAUDE_CONFIG_DIR`, `CODEX_HOME`,
562
+ `PI_CODING_AGENT_DIR`, `PI_CODING_AGENT_SESSION_DIR`) require a literal or
563
+ `{ fromEnv: NAME }`. A missing, unreadable or
564
+ non-regular file refuses with `E_LAUNCH_ENV_MISSING`. The message names the
565
+ file and the reason (including encoding, NUL or size failures), then names
566
+ `oats harness token set <harness> --server <id>` or operator provisioning on
567
+ that host. The token command is a separate provisioning feature.
568
+
569
+ ```yaml
570
+ launch-configs:
571
+ subscription:
572
+ harness: claude
573
+ env:
574
+ CLAUDE_CODE_OAUTH_TOKEN: { fromFile: /etc/agent-login/claude-token }
575
+ ```
576
+
577
+ For server credentials, [harness token commands](servers.md#harness-credentials)
578
+ deliver an existing setup-token or API key through the separate operator
579
+ route, with `--stdin`. Bind the receiver's server-side file in the launch
580
+ configuration, for example
581
+ `CLAUDE_CODE_OAUTH_TOKEN: { fromFile: /srv/oats-team/team/login/claude-token }`.
582
+ For Codex use `OPENAI_API_KEY`; for pi use the selected provider's env
583
+ variable. The token command does not choose a provider or edit this binding.
584
+ A replacement is read at the next start; existing sessions are not restarted.
585
+
586
+ **Claude login credentials.** At a Claude start, OATS checks for
587
+ `$CLAUDE_CONFIG_DIR/.credentials.json`, or `$HOME/.claude/.credentials.json`
588
+ when no config directory is selected, using the launch's effective environment.
589
+ If OATS sets `CLAUDE_CODE_OAUTH_TOKEN` through a literal, either reference kind,
590
+ or a capability's launch contribution, it refuses with
591
+ `E_CLAUDE_LOGIN_CREDENTIAL`, naming the exact credential file it found. An
592
+ empty value counts. Remove the `/login`
593
+ credential from that Claude configuration and use `oats harness token set
594
+ claude` to provision an inference-only token. Without an OATS-set token, a
595
+ personal `/login` credential is allowed silently. An inherited token does not
596
+ select the token route.
597
+ Other harnesses are unaffected. Spawn preview and apply check the predictable
598
+ configuration before creating a home, worktree or identity. A selector supplied
599
+ by a capability hook is checked after its launch environment is known, and
600
+ every actual launch checks its final pane again. On macOS, Claude's `/login`
601
+ credential lives in the Keychain; this file check does not inspect it.
602
+
603
+ Both reference kinds use `OATS_LAUNCH_REF_<NAME>` aliases. Their values are
604
+ absent from process arguments, tmux command lines, recipes, events and logs.
605
+ The kernel hands them to the pane through a per-start file in the instance
606
+ home, created exclusively with mode 0600; the launcher reads and deletes it
607
+ before executing the pane command. A failed dispatch removes it. Retirement
608
+ recovery excludes leftover handoff files. Each subsequent start removes
609
+ abandoned handoffs before dispatch, even when the new launch has no references. The start environment records only
610
+ keyed digests of reference values, including file references, so a resume
611
+ refuses a changed value; an ordinary start adopts a rotated file.
612
+
555
613
  **The instance's `oats`.** Every launch (`oats spawn`, `session start`,
556
614
  `session restart`, locally or through `--server`) writes `<home>/.oats/bin/oats`,
557
615
  a link to the launching kernel's `bin/oats.mjs`, and runs the harness with
@@ -693,8 +751,8 @@ oats doctor # this deployment's files and the lock
693
751
  ```
694
752
 
695
753
  Environment: `OATS_REMOTE_CACHE` relocates the fetch cache (which also holds
696
- the bounded parsed-read cache and the observations `--max-age` reuses; all of
697
- it is safe to delete); `OATS_PACKAGE_CATALOG` names an alternative package
754
+ the bounded parsed-read cache, the observations `--max-age` reuses and the
755
+ records of verified package trees; all of it is safe to delete); `OATS_PACKAGE_CATALOG` names an alternative package
698
756
  catalog file. The read verbs (`status`, `workspace status`, `souls`,
699
757
  `capabilities`, `inspect`, the read forms of `teams` and `soul teams`, and
700
758
  `spawn --preview`), and a spawn apply bound by `--expect-decision`, take
@@ -0,0 +1,246 @@
1
+ # Agent team container
2
+
3
+ `container/agent/` supplies an agent image and a Compose service for one
4
+ team's trust group. It runs non-root sshd on port 2222; the operator uses the
5
+ existing [server route](servers.md) to connect, preview and spawn. The
6
+ entrypoint creates private state directories and host keys, then starts
7
+ sshd. Deployment setup and seat admission belong to the operator.
8
+
9
+ ## Configuration contract
10
+
11
+ The same inputs apply to a Compose service or a platform's container spec:
12
+
13
+ | Input | Purpose |
14
+ | --- | --- |
15
+ | Deployment repository and commit | Operator provisions `/state/deploy`; its `oats-lock.json` pins packages and souls. Record the source and lock commits in the receipt. |
16
+ | aweb/AWID endpoints and team identifier | Deployment configuration; the platform's egress allowlist admits the endpoints. |
17
+ | Operator SSH public key | Read-only `authorized_keys` mount. |
18
+ | Resource limits | Runtime pids, memory and CPU limits. |
19
+ | Approved mounts | Explicit list, checked against the running container. |
20
+ | Egress destination list | Platform's resolver/forwarder configuration, outside the agent container. |
21
+ | Harness launch environment | Non-secret literals or file references, resolved at process start. |
22
+
23
+ Credentials never go in the image, build arguments, Compose environment, env
24
+ files or OATS configuration literals. The operator provisions ordinary
25
+ member seats and an inference-only Claude setup-token. Team/controller keys,
26
+ owner authority and service credentials stay outside the container. A
27
+ `/login` credential or a copy of `~/.claude` must never enter it.
28
+
29
+ ## Build and upgrade
30
+
31
+ From a checkout at the reviewed commit:
32
+
33
+ ```sh
34
+ env -i PATH="$PATH" docker build --platform linux/arm64 \
35
+ -t oats-agent:reviewed container/agent
36
+ ```
37
+
38
+ Use `linux/amd64` on the target builder. The Dockerfile pins Node 22 Debian
39
+ Bookworm slim by its multi-architecture index digest; the committed
40
+ `package.json` and `package-lock.json` pin the CLI versions and npm integrity
41
+ hashes. `npm ci --ignore-scripts` installs the dependency closure. Only
42
+ `@awebai/aw` is rebuilt with lifecycle scripts, in a build step without a
43
+ network. Claude's matching native binary is linked directly from its locked
44
+ platform package, without running its installer. Each CLI's version command
45
+ must succeed during the build.
46
+
47
+ `libnss-wrapper` is the extra OS package needed for arbitrary UID support.
48
+ No credentials or SSH host keys are baked in. The build context allowlist
49
+ excludes everything except the image's five inputs.
50
+
51
+ A derived image may add reviewed OS tools with `USER root` and `RUN`, then
52
+ restore `USER agent`. Those build steps use the system passwd/group database.
53
+ The entrypoint enables nss_wrapper only after generating the runtime
54
+ database; SSH command environments also enable it. An overridden entrypoint
55
+ or `docker exec` uses system NSS, so an arbitrary numeric UID may have no
56
+ name there. Use the SSH route for commands that require the `agent` mapping.
57
+
58
+ CLIs upgrade only by building and selecting a new image. Global npm installs
59
+ fail on the read-only root. To update the OATS pin, change its one dependency
60
+ version and regenerate this directory's lock with
61
+ `npm install --package-lock-only --ignore-scripts`; review both files. Do not
62
+ use `--install-oats` or `--install-aw` against a running container.
63
+
64
+ The committed OATS 0.69.12 pin supports container/SSH checks and spawn
65
+ preview. Live token delivery requires a new pin to a release that includes
66
+ `env: { fromFile: ... }` and the operator's `oats harness token set` route.
67
+ Until that image is built, the two-seat inference milestone remains unproven.
68
+
69
+ ## Mounts and UID
70
+
71
+ The provisioner creates host directories with the runtime UID and GID.
72
+ The Compose defaults are `20001:20001`; use an explicit non-root UID:GID in
73
+ the target service so the group-readable token is readable.
74
+
75
+ The image also starts with a numeric UID alone, such as
76
+ `docker run --user 20001`. When that UID has no image passwd entry, Docker
77
+ assigns GID 0. The wrapper names that runtime group `agent`, and new files
78
+ in `/state` have GID 0. Such a run cannot read a root:20001 0750 login
79
+ directory or its 0440 token. Use `--user 20001:20001` for the team login;
80
+ the UID-only form proves startup and SSH support, not token access.
81
+
82
+ | Container path | Host ownership and mode | Access |
83
+ | --- | --- | --- |
84
+ | `/state` | Runtime UID:GID, 0700 | Read/write; persistent |
85
+ | `/work` (optional) | Runtime UID:GID, 0700 | Read/write |
86
+ | `/etc/agent-login` | root:runtime-GID, 0750; `claude-token` root:runtime-GID, 0440 | Read-only |
87
+ | `/etc/agent-ssh/authorized_keys` | root-owned regular file, 0644 | Read-only |
88
+ | `/etc/resolv.conf` | Operator-provided resolver file | Read-only |
89
+ | `/tmp` | tmpfs, rw,nosuid,nodev,mode=1777 | Ephemeral |
90
+
91
+ All binds use `create_host_path: false`: a missing path fails startup.
92
+ `/state/home`, `/state/ssh` and `/state/deploy` are created 0700 by the agent.
93
+ `HOME=/state/home`. nss_wrapper reads passwd/group files generated in
94
+ `/state/ssh`, mapping the name `agent` to the actual UID/GID. The root
95
+ filesystem and `/etc/passwd` remain read-only. SSH sessions receive the same
96
+ mapping and HOME. The `agent` user has no sudo.
97
+
98
+ Host keys persist in `/state/ssh`; agents in the trust group can read them.
99
+ sshd accepts only `agent` public-key authentication, with PAM, password and
100
+ keyboard-interactive authentication off. Forwarding is disabled: OATS's
101
+ ControlMaster multiplexing uses SSH command/session channels and needs no
102
+ TCP, agent or X11 forwarding. The operator's jump host must separately permit
103
+ the ProxyJump connection to the container.
104
+
105
+ ## Compose integration
106
+
107
+ Supply these plain variables to the bundle's env file:
108
+
109
+ | Variable | Meaning |
110
+ | --- | --- |
111
+ | `TEAM` | Container name suffix: `oats-agent-${TEAM}`; service key is `agent`. |
112
+ | `AGENT_IMAGE` | Reviewed image tag or digest. |
113
+ | `AGENT_UID`, `AGENT_GID` | Runtime IDs; both default to 20001. |
114
+ | `TEAM_STATE_DIR` | Absolute host directory for `/state`. |
115
+ | `TEAM_WORK_DIR` | Optional absolute host directory for `/work`. |
116
+ | `TEAM_LOGIN_DIR` | Absolute host directory containing `claude-token`. |
117
+ | `AUTHORIZED_KEYS_FILE` | Absolute host public-key file. |
118
+ | `RESOLV_CONF_FILE` | Absolute host resolver file; always required. |
119
+ | `AGENT_PIDS`, `AGENT_MEMORY`, `AGENT_CPUS` | Positive limits; memory uses bytes, k, m or g. |
120
+ | `AGENTS_NETWORK`, `AGENT_IP` | Installer-created external network and container address. |
121
+
122
+ The bundle owns the network, resolver, forwarder, firewall and their bypass
123
+ checks. The agent service publishes no ports and sets no DNS or extra-hosts
124
+ override. It joins only the named external `agents` network. Its restart
125
+ policy is `unless-stopped`; security flags are fixed in the service file.
126
+
127
+ ```sh
128
+ docker compose -p "oats-team-${TEAM}" --env-file <plain-env-file> \
129
+ -f compose.yaml -f container/agent/compose.agent.yaml config
130
+ docker compose -p "oats-team-${TEAM}" --env-file <plain-env-file> \
131
+ -f compose.yaml -f container/agent/compose.agent.yaml up -d
132
+ ```
133
+
134
+ When `TEAM_WORK_DIR` is set, append
135
+ `-f container/agent/compose.agent.work.yaml` to both commands. Otherwise omit
136
+ the override: the base has no `/work` mount. With multiple Compose files,
137
+ paths resolve relative to the first file; use absolute host paths. Container
138
+ down/upgrade preserves `/state`; the operator owns provisioning and rollback.
139
+
140
+ ## OATS over SSH
141
+
142
+ The operator's SSH alias selects the key, host-key verification, port 2222
143
+ and jump route. The equivalent connection is:
144
+
145
+ ```sh
146
+ ssh -J <provisioner>@<host> -p 2222 agent@<container-ip>
147
+ ```
148
+
149
+ Register an already provisioned deployment, or connect it from the operator's
150
+ deployment using its source reference:
151
+
152
+ ```sh
153
+ oats server add team-agent --ssh <ssh-alias> --workspace /state/deploy \
154
+ --oats /usr/local/bin/oats --path /usr/local/bin:/usr/bin:/bin
155
+ oats server connect team-agent --ssh <ssh-alias> --dir /state/deploy \
156
+ --oats /usr/local/bin/oats --path /usr/local/bin:/usr/bin:/bin
157
+ ```
158
+
159
+ Use public HTTPS package pins unless a separate reviewed credential route
160
+ is provisioned. Verify `server connect` reports ready. The operator places
161
+ two independently admitted ordinary-member identities at
162
+ `/state/seats/<alias>/.aw`; each spawn selects one:
163
+
164
+ ```sh
165
+ oats spawn <soul> --server team-agent --harness claude --preview --provider oats.aweb identity.source=/state/seats/<alias>/.aw
166
+ ```
167
+
168
+ Preview runs no provider hook and does not validate a missing seat. Apply
169
+ only after reviewing it and provisioning its seat; use the same arguments
170
+ without `--preview`. Keep the team and controller keys outside the container.
171
+
172
+ On an OATS release supporting file-backed launch environment, the launch
173
+ configuration uses:
174
+
175
+ ```yaml
176
+ launch-configs:
177
+ team-claude:
178
+ harness: claude
179
+ env:
180
+ CLAUDE_CONFIG_DIR: /state/home/.claude
181
+ CLAUDE_CODE_OAUTH_TOKEN:
182
+ fromFile: /etc/agent-login/claude-token
183
+ ```
184
+
185
+ Select it with `--launch-config team-claude`. The operator provisions only a
186
+ `claude setup-token` result through the supported token route. It is readable
187
+ by every agent in the same trust group; read-only mounting does not hide it
188
+ or narrow its authority. Never share the mount across trust groups.
189
+
190
+ ## Acceptance and evidence
191
+
192
+ The host needs Docker and Node 22+. Export the same plain variables used for
193
+ Compose, then run:
194
+
195
+ ```sh
196
+ container/agent/accept.sh "oats-agent-${TEAM}" --evidence local
197
+ container/agent/accept.sh "oats-agent-${TEAM}" --evidence target-amd64
198
+ container/agent/accept.sh "oats-agent-${TEAM}" --evidence live-lab \
199
+ --claude /state/deploy/agents/<soul>/instances/<instance>
200
+ ```
201
+
202
+ Choose the label matching the actual run. `local` accepts the builder's
203
+ architecture; the other labels require amd64 and root:GID 0440 token / 0750
204
+ login-directory metadata. Local fixtures use a dummy file, never a real
205
+ login. Run the live Claude mode separately for each admitted instance home;
206
+ the home is an evidence label and an `instance.json` existence check. The
207
+ probe runs from a private temporary directory under `/tmp`, removed on
208
+ success or failure, with `--setting-sources user`. It uses the container's
209
+ user settings, excluding the instance's project settings, hooks and
210
+ `CLAUDE.md`, so the probe does not clear that live instance's waiting claim.
211
+ It reads the token only inside the container and requires the exact inference
212
+ response. It records no raw Claude output.
213
+
214
+ The script compares inspect settings and the exact bind list to the exported
215
+ variables. It resolves `AGENT_IMAGE` independently and requires that image's
216
+ ID, reference and start command, and its complete environment (printing only
217
+ names of differing variables). Other comparisons include supplementary
218
+ groups, namespace overrides, sysctls, published ports, resolver overrides
219
+ and the single network/address. The OCI runtime must match the daemon's
220
+ independently read default; shared memory stays at Docker's 64 MiB default,
221
+ the OOM killer stays enabled, and device cgroup rules stay empty. The total
222
+ memory-plus-swap setting is absent or Docker's default of twice the memory
223
+ limit; unlimited swap is refused.
224
+ It checks the process's UID/GID/supplementary groups/capabilities/no-new-privileges
225
+ and non-root sshd's banner, scans `/` as container root (pruning `/proc`,
226
+ `/sys`, `/dev` and the agent-scanned `/state`, `/tmp`, `/run`, `/work`),
227
+ and scans those trees plus writable `/dev/shm` and `/dev/mqueue` as the agent
228
+ for `.credentials.json`. It checks
229
+ the token is readable and not writable, and proves a global npm install fails using an
230
+ offline local package. Scan errors fail acceptance. The root inspection
231
+ process receives no added capabilities. Token provenance still needs the
232
+ operator's receipt: permissions and successful inference cannot distinguish
233
+ all credential classes.
234
+
235
+ A successful script run covers those checks only. The complete platform
236
+ receipt also needs `server connect`, both admitted-seat spawn previews and
237
+ applies, the source/lock commit, viewer, package sync, the bundle's network
238
+ and bypass evidence, mail/chat exchange, governance refusals and any broker
239
+ checks. Record target evidence separately from local evidence. Container
240
+ startup and a local preview do not establish two running agents.
241
+
242
+ `test/agent-container.test.mjs` pins the image, Compose and SSH security
243
+ settings and rejects weakened inspect fixtures. The SSH guard requires flat
244
+ `Keyword value` lines and refuses duplicate keywords, `Match`/`Include`,
245
+ equals-delimited keywords and quoted keywords. Follow the repository's
246
+ local check limits; full suites run in CI.
@@ -294,6 +294,8 @@ Each entry's manifests, souls and integrity are read at the observed commit →
294
294
  `{ lock, changes: [{ id, from, to, commit }] }` (`to: null`: no longer declared).
295
295
 
296
296
  - A branch is `E_PACKAGE_INTEGRITY { why: "branch" }`.
297
+ - A manifest whose `package` is not the entry's key is `E_PACKAGE_INTEGRITY { why: "package-id" }`,
298
+ fresh or already locked.
297
299
  - An unchanged version, source and path is re-verified: a moved commit or different integrity,
298
300
  capabilities or souls is `E_PACKAGE_INTEGRITY`.
299
301
  - A malformed package is `E_PACKAGE_MANIFEST`.