@awebai/oats 0.69.22 → 0.69.23

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 (54) hide show
  1. package/bin/oats.mjs +131 -23
  2. package/docs/capabilities.md +12 -2
  3. package/docs/capability-manifest.schema.json +1 -1
  4. package/docs/container.md +206 -228
  5. package/docs/design/2026-11-19-sandboxes.md +878 -0
  6. package/docs/design/README.md +3 -0
  7. package/docs/desktop-cli-api.md +416 -72
  8. package/docs/desktop.md +60 -17
  9. package/docs/implementation.md +1 -1
  10. package/docs/integrations.md +3 -3
  11. package/docs/knowledge-capability-authoring.md +10 -7
  12. package/docs/knowledge-reference/acceptance.md +21 -19
  13. package/docs/knowledge-reference/adoption.md +18 -4
  14. package/docs/knowledge-reference/model.md +11 -9
  15. package/docs/knowledge-reference/package-craft.md +2 -2
  16. package/docs/knowledge-reference/proposal.md +117 -0
  17. package/docs/knowledge-reference/provider-mapping.md +10 -10
  18. package/docs/knowledge-reference/reader-capture.md +26 -22
  19. package/docs/knowledge-theory.md +1 -1
  20. package/docs/knowledge.md +5 -5
  21. package/docs/official-catalog.md +4 -4
  22. package/docs/packages.md +13 -13
  23. package/docs/release-notes/v0.69.23.md +231 -0
  24. package/docs/servers.md +10 -6
  25. package/docs/souls-and-instances.md +51 -22
  26. package/docs/tui.md +4 -3
  27. package/docs/upgrading.md +12 -5
  28. package/docs/workspaces.md +2 -2
  29. package/lib/argv.mjs +6 -2
  30. package/lib/capability-contract.mjs +2 -2
  31. package/lib/command-flags.mjs +39 -2
  32. package/lib/core.mjs +25 -14
  33. package/lib/instance-board.mjs +337 -0
  34. package/lib/instance-events.mjs +48 -10
  35. package/lib/instance-lifecycle.mjs +19 -15
  36. package/lib/instance-listing.mjs +18 -10
  37. package/lib/instance-related-work.mjs +143 -0
  38. package/lib/kernel-features.mjs +4 -1
  39. package/lib/servers.mjs +123 -13
  40. package/package-catalog.json +3 -3
  41. package/package.json +1 -1
  42. package/packages/client/deployment-data.mjs +4 -2
  43. package/packages/client/deployment-panel.mjs +2 -1
  44. package/packages/client/instance-tree.mjs +34 -4
  45. package/packages/client/keymap.mjs +5 -0
  46. package/packages/client/mail-contract.mjs +130 -0
  47. package/packages/client/panel-views.mjs +7 -7
  48. package/packages/client/related-work.mjs +84 -0
  49. package/packages/client/remote-roster.mjs +4 -3
  50. package/packages/client/workspace-cli.mjs +13 -2
  51. package/skills/oats-getting-started/SKILL.md +11 -8
  52. package/docs/knowledge-reference/harvester.md +0 -109
  53. package/lib/instance-same-work.mjs +0 -67
  54. package/packages/client/same-work.mjs +0 -49
@@ -0,0 +1,878 @@
1
+ # Sandboxes: boundaries declared in the workspace, started by `oats sync`
2
+
3
+ **Status:** contracts decided, 2026-11-19. The product owner's side and aweb's maintainers agreed
4
+ C1–C10 and C3b as written at 0849ef12, with aweb's maintainers' four changes, which
5
+ the product owner's side accepted: the registry setting (C3, C6), a keyed `seat` (C4), the receipt of the host's
6
+ `remove-member` (C6) and the credential-mount probe (C8). The connector half of C9
7
+ stays designed only. Nothing is built yet. **Revised after review round 1** (marked
8
+ "(r1)" below): existing host homes, lifecycle calls made inside a sandbox, C4's
9
+ per-act wire shapes and provider selection, shared team aliases, mount overlap, the
10
+ first use's GitHub API route, managed server registrations, and the missing refusal
11
+ codes. Both sides decided those, with two precisions from aweb's maintainers, and decided the
12
+ `forge` egress role for the GitHub API. **Revised again after review round 2** (marked
13
+ "(r2)"): every real agent bind is checked, `status` mutates nothing, the routed
14
+ spawn's exact sequence and seat binding, the seat's service descriptor, provider state
15
+ scoped per deployment, a team not yet created, and the seat option's key. Both sides
16
+ decided the r2 additions, with `sandbox-state-orphaned`. **Revised after review round
17
+ 3** (marked "(r3)"): the apply is bound to the preview's `decision.revision`; the seat
18
+ plan needs only the spawn key; the spawn hook learns the apply's key; the kernel keeps
19
+ the full routed request for replay; mint recovery; hardlinked credentials; the
20
+ resolvers are host infrastructure; the protected-sources input shape; and the `forge`
21
+ role's Host guarantee corrected to what a TLS pass-through can enforce. Both sides
22
+ decided the r3 contracts, with the domain-fronting risk statement and the pending
23
+ request's custody. **Revised after review round 4** (marked "(r4)"): the apply
24
+ evidence `bind` acts on, and the fence that keeps a replay away from an interrupted
25
+ delivery. **Revised after the round-4 delta read** (marked "(r4d)"): a seat is
26
+ released only on proof that no home can hold it, and the readiness and ordering text
27
+ that follows from that. A later change to a contract goes back to
28
+ both sides (the lane map's "Contract changes" line). When this record and a reference
29
+ page disagree after it is built, the reference page wins.
30
+
31
+ ## The goal
32
+
33
+ One machine runs `oats sync` on a deployment, and the sandboxes that deployment lists
34
+ are built and started, with their boundaries declared once in the workspace. The first
35
+ use is scheduled knowledge-base ingestor agents on a cloud machine: they read untrusted
36
+ content, so they must not reach the engineers' agents, credentials or network.
37
+
38
+ **Done means:** on a Linux machine with Docker, a workspace that declares one sandbox,
39
+ and a deployment whose local file lists it, `oats sync` builds and starts the sandbox.
40
+ A workspace schedule whose `runsOn` names that machine spawns its soul inside the
41
+ sandbox, with an identity minted on the host. The agent can message only its own team,
42
+ reach only the declared destinations and read only the declared credentials. Retiring
43
+ it removes its identity from the team. Delisting the sandbox stops it and destroys
44
+ nothing. All of this is shown by a live rehearsal and by the tests pinned in each spec.
45
+
46
+ ## Decided with the product owner
47
+
48
+ - **A team is membership and messaging. A sandbox is the boundary** (its local state,
49
+ credentials and egress). In v1 a team has at most one sandbox, so the two coincide by
50
+ default. They stay separate primitives: a later layout can split one team across
51
+ sandboxes by relaxing validation, with no change to the file format and no identity
52
+ remint (decided 2026-11-19, agreeing to aweb's maintainers' requirement of 2026-11-18).
53
+ - **Credentials in v1 are read-only files** mounted into the sandbox. Every agent in it
54
+ can read them, which is acceptable with one team per sandbox (decided 2026-11-19).
55
+ - **OATS does not create or delete machines in v1.** Sync builds and starts listed
56
+ sandboxes on a machine that already exists. Creating machines comes later, as a
57
+ provider capability (decided 2026-11-19).
58
+ - **Both broker contracts are designed in this effort**: one for secrets, one for
59
+ connectors (decided 2026-11-18). Credential files remain the way to start.
60
+ - **Messaging isolation is by server:** each isolated team gets its own aweb server
61
+ with federation outbound off. This needs no aw contract change (decided 2026-11-17).
62
+ - **Kept as they are:** the word "team"; the schedule file, with `runsOn` naming the
63
+ machine and no lease; a sandbox does not list its own souls; there is no workspace
64
+ list of shared deployments.
65
+
66
+ ## What exists today, and what this builds on
67
+
68
+ - `container/agent` is one team's container. It runs every agent, sshd, the wake
69
+ broker and `oats host run` as one user, with its own OATS deployment at
70
+ `/state/deploy`, reached from the host as an OATS server over SSH
71
+ ([container.md](../container.md)).
72
+ - Its egress component has five base roles (aweb, registry, secrets, logs, signer), of
73
+ which a policy may declare a subset (#1955); teamctl's profile declares four of them
74
+ (all but signer). It adds two optional external roles, `source` (`https://github.com`)
75
+ and `model` (`https://api.anthropic.com`). It does not take arbitrary origins
76
+ ([egress README](../../container/agent/egress/README.md)). The Compose boundary probe
77
+ takes a `namePrefix` and reports `--json` receipts (#1958).
78
+ - aweb's team bundle, `deploy/team` (`teamctl`, aweb's maintainers), renders one
79
+ `deployment.yaml` into an aweb server, the egress proxy and the agent container. It
80
+ sets `AWEB_FEDERATION_OUTBOUND` to `off` by default. `teamctl start` probes the
81
+ boundary, brings up the agent, and exits 3 on purpose with the agents held: it admits
82
+ no seat.
83
+ - Seats: today a container agent takes a retained seat (`identity.source`) that the
84
+ operator provisioned. oats.aweb mints an instance's identity with
85
+ `aw init --join-from <root> --join-team <team>`, which works only where the team key
86
+ is, and at retire it prints `aw id team remove-member` rather than running it.
87
+ - The kernel has no Docker code, and must not gain any: provider behaviour belongs in a
88
+ capability.
89
+ - `oats-workspace.yaml` and `oats-local.yaml` are closed schemas. An older kernel
90
+ refuses a new root key with `E_WORKSPACE_SCHEMA` and, for the workspace file, an
91
+ "upgrade OATS" hint.
92
+ - A `run: spawn` schedule spawns on the host its `runsOn` matches (`host.name`). A
93
+ remote spawn (`--server`) runs preview and apply on the server's kernel, and the home
94
+ lives there.
95
+
96
+ ## The design
97
+
98
+ ### Who does what
99
+
100
+ | Piece | Owner | Does |
101
+ | --- | --- | --- |
102
+ | Declaration, validation, placement, CLI verbs, sync | the kernel (lane:product) | Reads `sandboxes:`, refuses the ways round the boundary, decides where a soul runs, calls the sandbox provider, and reports. No Docker. |
103
+ | Sandbox provider | a new capability, `oats.aweb-sandbox`, in the oats-aweb package | Turns a sandbox into teamctl input, runs teamctl, registers the sandbox as a server, prepares the in-sandbox deployment, mints and delivers seats, removes members at retire. |
104
+ | The team bundle | teamctl, aweb `deploy/team` (aweb's maintainers) | Three new inputs: the credential mount, the protected-sources file and the `forge` role (C8). |
105
+ | The agent image and Compose | `container/agent` (lane:juan) | A read-only credential mount fragment (C8). |
106
+
107
+ ### Placement
108
+
109
+ A soul runs in sandbox S when its resolved default team is S's team. Otherwise it runs
110
+ on the host, as today. Placement is derived in v1; explicit placement, if it ever comes,
111
+ is declared in the workspace and never in a machine's local file.
112
+
113
+ - On a host that lists S and has it started, a spawn of such a soul (by hand, or by a
114
+ schedule tick) is routed into S, as a remote spawn through S's server registration.
115
+ S1 builds on #1912's floor (lane:juan, held): the task goes on stdin, the apply is
116
+ bound to its preview and keyed, and a host below 0.69.15 is refused. This costs
117
+ nothing, because the sandbox's kernel must already be the release with `sandboxes`.
118
+ S1 may be built now, but does not merge before #1912. If #1912 is withdrawn, S1 itself requires the same
119
+ three properties of the sandbox's kernel, rather than relying on today's fallbacks.
120
+ - On a host that does not list S, the spawn is refused with `E_SANDBOX_NOT_HERE`, naming
121
+ S and the local key that would list it. A sandboxed soul never falls back to the host.
122
+ - Inside S, its deployment refuses to spawn any soul not placed in S
123
+ (`E_SANDBOX_PLACEMENT`).
124
+
125
+ ### The clock
126
+
127
+ There is one clock per machine, and it is the host's. A schedule runs on the host its
128
+ `runsOn` names, and its spawn is routed into the sandbox. The in-sandbox deployment
129
+ registers no deployment for ticking, so its `oats host run` keeps only the resume sweep
130
+ and the ordered stop, and ticks nothing. This replaces the container's clock; it does
131
+ not add a second one.
132
+
133
+ ### Identities
134
+
135
+ Every instance in a sandbox has its own identity, minted on the host at spawn and
136
+ removed at retire. The team's controller key and team key stay on the host, under the
137
+ operator's account, and never enter the container.
138
+
139
+ 1. Before routing the spawn, the provider mints the instance's identity on the host
140
+ from the host's root for the sandbox team (`roots[T]`), into a private staging
141
+ directory. Where the sandbox team's registry is private, the host deployment sets
142
+ `settings.oats.aweb.registry` for the mint (C3).
143
+ 2. It delivers the identity's authority files (the same list retained seats copy
144
+ today) and a seat descriptor into the sandbox's state, at
145
+ `/state/seats/<seat-id>/`, and deletes the staging copy. The seat ID is derived from
146
+ the routed spawn's idempotency key, so a seat directory names one spawn, never an
147
+ instance name that can be reused (r2).
148
+ 3. The remote spawn takes that seat as a one-use seat (C6). The agent's own private key
149
+ is then inside the container, which is what aweb's answer requires: there is no
150
+ alternative short of a grant home, and that route is untested.
151
+ 4. At retire, the routed retire removes the home and releases the seat. The provider
152
+ then runs `aw id team remove-member` on the host, where the controller key is,
153
+ instead of printing it.
154
+
155
+ The exact order of a routed spawn, with the value each step binds (r2, r3):
156
+
157
+ 1. The kernel makes the spawn's idempotency key (`spawnKey`) and asks the provider for
158
+ a seat plan (`plan`, target `seat`, with `instance: {soul, spawnKey}`). The plan is
159
+ read-only and needs no instance name: it answers the seat ID (derived from
160
+ `spawnKey`), its path and the `spawnProvider` options. Its `planRevision` fences
161
+ only the sandbox's provider state and `spawnKey`.
162
+ 2. The kernel runs the remote preview **with those options**. The preview chooses the
163
+ instance name when the caller gave none (a schedule passes `--purpose`, not
164
+ `--name`), and answers `decision.revision`, `D`, the hash of the whole decision
165
+ that the apply's `--expect-decision` must match, as #1912 requires. The in-sandbox
166
+ kernel admits a preview that carries a seat option without reading the seat; only
167
+ an apply needs it.
168
+ 3. **Before anything is minted, the kernel keeps the whole routed request** (r3,
169
+ contract): server, `spawnKey`, `D`, the exact argv and provider options, and the
170
+ task text, in `~/.oats/remote/<server>/pending/<spawnKey>.json` (0600, under the
171
+ operator account, beside today's remote snapshots). It holds the task text, which
172
+ #1912 took off argv for a reason, so: it is removed as soon as its seat settles
173
+ (bound, released, or refused terminally); it is never copied into a receipt, a log
174
+ or the ledger; and readiness reports one older than 24 hours as
175
+ `sandbox-pending-stale`, naming the spawn key, never the task. S1 pins a test that
176
+ its content never reaches a receipt, a log or a readiness line.
177
+ 4. The kernel runs `seat` with the plan's revision, `spawnKey` and
178
+ `instance: {name, soul, decision: D}`. The name and `D` are inputs to the mint, not
179
+ part of the plan's revision. The provider writes the ledger entry (`minting`, with
180
+ `spawnKey`, `D`, the alias it will mint and the seat ID) before it mints, mints,
181
+ records the certificate ID, delivers, and moves the entry to `delivered`.
182
+ 5. The kernel runs the remote apply with `--expect-decision D` and
183
+ `--idempotency-key spawnKey`, from the kept request, with the same provider options
184
+ as the preview. No provider input changes between 2 and 5.
185
+ 6. The kernel passes the apply's own answer to the provider (`bind`, C4), which acts
186
+ on it by this table (r4, contract):
187
+
188
+ | The apply's answer | Evidence | The seat |
189
+ | --- | --- | --- |
190
+ | Success, or the keyed replay of one | the home's `capabilityMeta["oats.aweb"].seat`, `{seatApi:1, seatId, certificateId, spawnKey}`, written by oats.aweb's spawn hook once the seat is connected, matching the ledger entry | `active` |
191
+ | `E_DECISION_STALE` | the kernel's key recovery found no home holding `spawnKey` and refused before placing anything; the descriptor admits only that key (C6), so no home holds the seat | released (`spawn-failed`) |
192
+ | `E_REQUIRED_HOOK_FAILED` or `E_HOOK_ENVIRONMENT_CONTRACT` whose details carry no `unconfirmed: true` (r4d) | the spawn's rollback confirmed its home is gone, so no home holds the seat, whatever the hook did before it failed (oats.aweb's `seat-binding` refusal arrives this way) | released (`spawn-failed`) |
193
+ | `E_IDEMPOTENCY_CONFLICT` (r4d) | a home already holds `spawnKey` under another decision and may hold the seat | stays `delivered` |
194
+ | `E_SPAWN_INCOMPLETE`, a hook failure with `unconfirmed: true`, a failed or uncertain seat connect, any other refusal, or no answer | none of these proves that no home holds the seat | stays `delivered` |
195
+
196
+ A seat is released only on proof that no home can hold it (r4d): releasing revokes
197
+ the member, which is right for a seat that no home holds, used or not, and wrong
198
+ for one a live home holds. Before such a release the provider deletes any copy at
199
+ `/state/seats/<seat-id>/` through the server route. If that deletion cannot be
200
+ confirmed, the entry stays `delivered`, the kept request is deleted (its refusal
201
+ was terminal), and readiness reports `sandbox-seat-unsettled`. The server route's
202
+ "copy deleted" answer comes from the sandbox, so it is untrusted input: it can
203
+ release only a seat of that sandbox's own ledger, and a false "deleted" can at
204
+ worst revoke that sandbox's own member, never another's (r4d). `ok: false` alone is
205
+ never evidence, and the provider reads no field of a refusal beyond its code and
206
+ `unconfirmed`. S1 pins that the routed apply's answer, and its keyed replay, carry
207
+ the new home's `capabilityMeta`; that the routed answer carries the host's refusal
208
+ code and its `unconfirmed` detail unchanged; that `E_DECISION_STALE` is raised
209
+ only when no home holds the key, before any placement or hook; and that a required
210
+ hook's failure carries `unconfirmed: true` whenever the rollback could not confirm
211
+ the home gone. S2 pins the meta oats.aweb writes and a `bind` test per row,
212
+ including a prior home holding the key under another decision
213
+ (`E_IDEMPOTENCY_CONFLICT`: the member is kept) and a failed copy deletion.
214
+ 7. **The kernel settles a `delivered` seat** (r3, r4): `oats sandbox reconcile`, and
215
+ so sync, first runs the provider's `reconcile` act, which settles interrupted mints
216
+ and deliveries (below) and answers the ledger's seats. Only then does it replay a
217
+ kept request, and only one whose ledger entry that answer shows durably
218
+ `delivered`: a kept request whose entry is `minting` or `mint-uncertain` is never
219
+ applied or replayed, and one whose seat was released is deleted. Each replay is
220
+ unchanged, keyed by its `spawnKey`, and its answer goes to `bind` as in 6. A replay of an apply that was
221
+ never sent is that apply, with its task, and a stale `D` refuses it terminally. The
222
+ provider never builds or replays a spawn itself. Absence of the instance's name, or
223
+ an unused seat directory, is never evidence. A `delivered` seat with no kept request
224
+ stays `delivered`, and readiness reports `sandbox-seat-unsettled`.
225
+
226
+ **A mint whose outcome is uncertain (r3, contract).** An entry found in `minting` was
227
+ interrupted, and the registry may hold an identity whose result was never recorded, or
228
+ a seat copy may already have landed in the sandbox before the `delivered` write (r4).
229
+ The next mutating act reads the certificate ID from the staging copy, if one is there,
230
+ into the entry before it deletes that copy, and moves the entry to `mint-uncertain`.
231
+ With a certificate ID, it first deletes any copy at `/state/seats/<seat-id>/` through
232
+ the server route, then releases the seat (reason `spawn-failed`): no apply was sent
233
+ for it, because the apply follows the `delivered` write and its kept request is
234
+ fenced (step 7). If that copy cannot be confirmed deleted, the entry stays
235
+ `mint-uncertain` and is reported as unsettled. A pinned test kills the provider
236
+ between the copy landing and the `delivered` write, then runs reconcile and an
237
+ otherwise no-op sync: no home is created, the copy is gone and the member is
238
+ removed. Without one, the entry stays `mint-uncertain`, readiness
239
+ reports `sandbox-seat-unsettled` naming the alias, and the operator checks the team's
240
+ members. A replay of that `seat` key answers `unknown` and never mints again. A test
241
+ pins a kill after registration and before the receipt.
242
+
243
+ ### Lifecycle calls made inside a sandbox (r1)
244
+
245
+ Minting and removing identities need the host's keys, so in v1 the host is the only
246
+ place a sandboxed instance is spawned from, and the host finishes every retire:
247
+
248
+ - **Spawn inside the sandbox.** The in-sandbox deployment has no root for the team.
249
+ Its kernel accepts a spawn only when it carries a host-delivered seat (the routed
250
+ spawn's `identity.seat`, C4 and C6). Any other spawn there, by an agent or by hand,
251
+ is refused with `E_SANDBOX_PLACEMENT`, reason `spawn-from-host`, whose remedy is to
252
+ spawn from the host. A sandboxed agent that needs a helper asks for one; it cannot
253
+ start one.
254
+ - **Retire inside the sandbox** (`oats retire --self`, or a retire run there by hand)
255
+ works as today: the home goes, and oats.aweb prints the `remove-member` command it
256
+ cannot run. The host completes it through the provider's `reconcile` act (C4), which
257
+ `oats sandbox start` and sync run for each listed sandbox, under the sandbox's lock.
258
+ `status` only observes (r2).
259
+ - **The sandbox's report is untrusted input.** Reconcile reads the sandbox's instances
260
+ through the server route, and that report comes from inside the boundary. So it can
261
+ only move seats of that sandbox's own ledger toward `released`, and it triggers no
262
+ other act. A seat is released by reconcile only when all of these hold: its entry is
263
+ `active` (never `minting`, `delivered` or `removal-uncertain`), the report lists no
264
+ home holding its seat ID, and its seat directory is gone. The release's receipt
265
+ records that the sandbox's report drove it (reason `reconcile`), so it can be told
266
+ from a retire's removal. A test pins that a report naming a seat of another
267
+ sandbox, or an unknown certificate, changes nothing.
268
+ - **Retire from the host** (`oats retire <name> --server sandbox-<name>`, or the
269
+ kernel routing a retire of a sandboxed instance) runs the remote retire, then the
270
+ provider's `release` act (C4) for that seat at once (reason `retired`).
271
+ - **The ledger** lives in the provider's state on the host, scoped to the deployment
272
+ (C7): `~/.oats/sandboxes/<deployment-key>/<sandbox>/seats.json`, one entry per seat:
273
+ seat ID, `spawnKey`, `D`, instance, alias, certificate ID, team, state (`minting`,
274
+ `mint-uncertain`, `delivered`, `active`, `removing`, `released`,
275
+ `removal-uncertain`), and the receipt
276
+ of each step. It outlives the remote home, and is the only evidence
277
+ `remove-member` acts on.
278
+ - **Removal is written before it runs (r2).** The provider moves an entry to
279
+ `removing`, durably, before it calls `remove-member`, then to `released` or
280
+ `removal-uncertain` with the receipt. An entry found in `removing` was interrupted:
281
+ it becomes `removal-uncertain`, and is never removed again automatically (C6).
282
+ - **Compensation.** If the mint succeeds but delivery fails, the provider releases
283
+ the seat at once (reason `spawn-failed`) and deletes any delivered copy. After
284
+ delivery, only step 6 or 7 above settles the seat.
285
+
286
+ ### Credentials (v1)
287
+
288
+ The workspace names a sandbox's credentials. The host's local file says where each
289
+ value is. The provider mounts each named file read-only at `/run/oats-credentials/<name>`
290
+ in that sandbox's agent container only. Nothing else gets a mount, and an undeclared or
291
+ missing credential refuses the start. A capability inside the sandbox reads a credential
292
+ through its own file setting (for example `settings.oats.okf.github-token-file`), which
293
+ the provider writes into the in-sandbox local file from the host's settings for that
294
+ sandbox.
295
+
296
+ **No other mount may expose them (r1, r2).** A credential source is a regular file,
297
+ read through its real path; a symlink is resolved, and one that leads to anything but
298
+ a regular file is refused (`E_SANDBOX_CREDENTIAL`, reason `not-a-file`). The bind
299
+ source is the resolved path. A credential source with more than one hard link is
300
+ refused too (reason `hardlinked`, r3, contract): a second link could sit inside another
301
+ sandbox's work directory, where no path check sees it. This applies to every source in
302
+ the host's `credentials`, used or not, at every sandbox's start; the container's own
303
+ acceptance already refuses a public CA with more than one link. A pinned test puts a
304
+ hard link of one sandbox's credential in another sandbox's work directory.
305
+
306
+ The provider derives a protected inventory, in two parts:
307
+
308
+ - **Hard-denied:** the host's team roots (`roots`), the seat staging directory, the
309
+ provider's own state (`~/.oats/sandboxes`) and the host deployment directory. No
310
+ bind may equal, contain or lie inside one of these, a declared credential included:
311
+ a credential source inside a team root is refused.
312
+ - **Credential sources:** every source in the host's `credentials`, whether a listed
313
+ sandbox declares it or not (an unused one, or one of a delisted sandbox, included),
314
+ and every other sandbox's state, work and mirror directories. Only the exact
315
+ read-only bind of a credential this sandbox declares, at
316
+ `/run/oats-credentials/<name>`, is excepted.
317
+
318
+ The check runs on **every bind of the real agent container**, before any agent runs
319
+ (r2): the provider renders the teamctl deployment and checks each agent bind source in
320
+ the rendered configuration (the state, work and mirror directories, the harness login
321
+ directory from `agents.secrets`, the authorized-keys file, and the credential binds),
322
+ then the container's own mount acceptance checks the started agent's actual mounts
323
+ against the same inventory before any seat is admitted (C8). Today's boundary probe
324
+ substitutes an empty login directory, so it cannot stand in for this check. The
325
+ started-agent check reads the agent container by its exact identity (the container ID
326
+ teamctl's start returned, or an ownership label as in #1958), never by name alone: a
327
+ same-named container that is not this sandbox's refuses admission (a pinned negative
328
+ in S2 and S3). A failing
329
+ bind refuses the start (`E_SANDBOX_MOUNT`, reason `overlap`, naming both paths), and so
330
+ do two sandboxes sharing any such directory. Pinned negative tests: a work or mirror
331
+ directory containing an unused credential; one containing a delisted sandbox's
332
+ credential; a harness login directory pointing at a team root.
333
+
334
+ **The first use's GitHub API route: the `forge` role (decided).** `source` admits
335
+ `https://github.com` only, and a knowledge proposer also calls `https://api.github.com`
336
+ (OKF's own setup check requires both). Both sides decided a third external role for
337
+ it:
338
+
339
+ - `forge` selects exactly `https://api.github.com`, defaults to false and, like the
340
+ other external roles, needs `egress.external.resolvers`. Its wrapper input is
341
+ `egress.external.forge` (teamctl's schema), its policy entry
342
+ `externalTargets.forge.origin`, and the component checks the exact origin again.
343
+ - **What it guarantees (r3, contract: corrects a decided item).** External roles are
344
+ TLS pass-through: the proxy routes on the SNI and never sees the encrypted
345
+ Host/`:authority` (egress README, "Optional external source and model roles").
346
+ So `forge`'s guarantee is the external roles' own: exact SNI `api.github.com` and a
347
+ validated public destination. The probe tests what the proxy enforces: an
348
+ unlisted SNI is refused, and `api.github.com` resolves only to the proxy. **The
349
+ risk that remains:** with SNI `api.github.com` admitted, the connection reaches
350
+ whatever GitHub's front end for that name serves to a Host it accepts; domain
351
+ fronting is not refused here. So the one-repository credential is the control that
352
+ matters. A Host
353
+ that differs from the SNI inside the encrypted stream, on a `forge` or another
354
+ admitted connection, is not refused by this component; whether GitHub serves it is
355
+ GitHub's. Refusing it would need TLS interception, which this record does not
356
+ propose. This statement replaced the earlier "SNI/Host mismatch" item; both sides
357
+ decided it in r3, with the risk statement above.
358
+ - The external-egress image test and the boundary probe name the hosts that stay
359
+ refused: `uploads.github.com`, `codeload.github.com`, `raw.githubusercontent.com`,
360
+ `objects.githubusercontent.com` and `gist.github.com`.
361
+ - **The credential is scoped to one repository, as a requirement.** With a token the
362
+ API can write, and the boundary limits services, not accounts. So the sandbox's
363
+ proposal credential (`knowledge-propose` in C1's example) must be scoped to the one
364
+ knowledge-base repository, as a push credential is today. The egress README's role
365
+ section, this section and the first use's setup steps all say so.
366
+ - C1's `egress` set becomes `{model, source, forge}`. `forge` has its own feature,
367
+ `sandbox-egress-forge`, because a kernel that already has `sandboxes` refuses the new
368
+ value through C1's closed set: a workspace uses `forge` only once every one of its
369
+ hosts lists that feature.
370
+ - Order: the egress component and teamctl first, on lane:juan (aweb's maintainers launch
371
+ that developer once this record is final); then C1's value, on the kernel side.
372
+
373
+ ### What sync does
374
+
375
+ After its current steps (the lock, package souls, the automation snapshot), `oats sync`
376
+ reconciles each sandbox the local file lists:
377
+
378
+ - not built, or built from other inputs: build and start it;
379
+ - stopped: start it;
380
+ - running with the same inputs: no infrastructure change (`action: "none"`).
381
+
382
+ Whatever the action, sync then reconciles each listed, running sandbox's seats
383
+ (`oats sandbox reconcile`'s work: the provider's `reconcile` act, then the replay of
384
+ each kept request whose entry it answers durably `delivered`, as in step 7 of the
385
+ Identities section) (r4d), so a self-retire is completed by the next sync even when nothing else changed
386
+ (r3). A pinned test: a self-retire, then an otherwise no-op sync, removes the member.
387
+
388
+ A sandbox declared in the workspace but not listed locally is never started. A sandbox
389
+ listed earlier and now delisted is stopped, never destroyed. The provider keeps the
390
+ last declaration it started each sandbox with in its own state, so a sandbox whose
391
+ workspace entry was removed together with its local listing is still stopped, from
392
+ that record (r1). `oats sync --plan` shows
393
+ these actions and performs none. A failed sandbox does not undo the lock. It is reported
394
+ in `problems`, and sync exits nonzero.
395
+
396
+ teamctl's exit 3 ("agents held") is the expected end of a start. The provider reports
397
+ it as `ready`: in this design seats are admitted per spawn, never at start.
398
+
399
+ ### Images
400
+
401
+ In v1 the agent and egress image digests are host facts in the teamctl deployment file.
402
+ teamctl already requires the digest form. The image is not yet published: the release
403
+ job is disabled pending the registry decision. Once the release lane publishes it, the
404
+ digest moves into the lock with the release. That is a lock format change, proposed
405
+ then, not here.
406
+
407
+ ## The contracts (decided)
408
+
409
+ ### C1. Workspace `sandboxes:` (new root key)
410
+
411
+ ```yaml
412
+ teams:
413
+ ingest-team: { team: "ingest:example.org" }
414
+ souls:
415
+ knowledge/knowledge-ingestor: { default: ingest-team }
416
+ sandboxes:
417
+ ingest:
418
+ team: ingest-team # one sandbox per team in v1
419
+ egress: [model, source, forge] # closed set, added to the base routes
420
+ credentials: [sources-read, knowledge-propose] # names only
421
+ description: Knowledge ingestors # optional
422
+ ```
423
+
424
+ - The name matches `^[a-z0-9]$|^[a-z0-9][a-z0-9-]{0,30}[a-z0-9]$`. `team` must be a label in
425
+ this file's `teams:`, and no other sandbox may name it (v1).
426
+ - `egress` is a subset of `{model, source, forge}` (`forge` behind feature
427
+ `sandbox-egress-forge`), because those are the external roles the egress component
428
+ supports. Adding another destination is a change to the egress
429
+ component, not a free-form list.
430
+ - `credentials` names match `^[a-z0-9][a-z0-9-]{0,62}$`, and are distinct.
431
+ - **A team not yet created (r2).** A shared team may omit its provider id (declared,
432
+ not created). A sandbox may name such a team: the workspace stays valid, so other
433
+ hosts are not refused. Its start refuses (`E_SANDBOX_TEAM`, reason
434
+ `team-not-created`), and so does a routed spawn, with the existing remedy: its owner
435
+ runs `oats aweb setup`, then commits the id. The id is never inferred from the label
436
+ or an active team. Until it is set, C2's checks compare the label.
437
+ - `team` is required. `egress` and `credentials` are optional and default to `[]`;
438
+ `egress` entries are distinct. A duplicate in either list is refused (reason
439
+ `duplicate-entry`) (r1).
440
+ - It is closed (`additionalProperties: false`), like every workspace block. An older
441
+ kernel refuses the file with `E_WORKSPACE_SCHEMA` and its existing "upgrade OATS"
442
+ hint, which is the error that tells existing deployments what to do.
443
+ - **Adding it breaks every older host of the workspace, not only the sandbox host.**
444
+ Every host reads the shared file, so the first commit that adds `sandboxes:` makes
445
+ each host on an older kernel refuse the whole workspace. A workspace adds the block
446
+ only once every one of its hosts runs the release that has feature `sandboxes`. The
447
+ person who commits it checks that first: the kernel cannot see another person's host.
448
+ The release notes' Upgrade section and the reference page that owns the workspace
449
+ file ([workspaces.md](../workspaces.md)) both say this, and give the check:
450
+ `oats version --json` on each host lists `sandboxes`.
451
+ - Feature `sandboxes` in `oats version --json`.
452
+
453
+ ### C2. The three ways round a sandbox are refused (aweb's maintainers' edge cases)
454
+
455
+ All are refused when the workspace file is read, with `E_WORKSPACE_SCHEMA` and a reason
456
+ code:
457
+
458
+ 1. **A sandboxed team as a soul's extra team** (`teams: [ingest-team]`): refused, reason
459
+ `sandboxed-team-not-default`. The `"any"` value means every shared team without a
460
+ sandbox. An explicitly declared bridge is not in v1.
461
+ 2. **A sandboxed team reached through a wildcard or the default:** a `"*"` or
462
+ `<member>/*` entry whose `default` is a sandboxed team, and a workspace `defaultTeam`
463
+ that is one, are refused (reason `sandboxed-team-by-wildcard`). A sandboxed team is
464
+ reached only through a named soul (`<member>/<soul>`).
465
+ 3. **A local override:** an `oats-local.yaml` cannot move a sandboxed soul. Local files
466
+ have no soul-to-team mapping today, and a local `defaultTeam` already loses to a
467
+ soul's `souls:` default. A local team may not reuse a sandboxed team's label or
468
+ provider id (reason `sandboxed-team-local`).
469
+ 4. **A shared alias (r1):** two shared labels may today name one provider id. A
470
+ sandboxed team's provider id must be named by exactly one shared label; another
471
+ shared label with that id is refused (reason `sandboxed-team-alias`). Every check
472
+ above, and placement, compare provider ids, never labels alone, so two sandboxes
473
+ cannot name one team through two labels either (reason `sandbox-team-taken`).
474
+
475
+ ### C3. `oats-local.yaml`: `sandboxes` and `credentials` (new root keys)
476
+
477
+ ```yaml
478
+ host: { name: cloud-1 }
479
+ sandboxes: [ingest] # the sandboxes this machine runs
480
+ credentials:
481
+ sources-read: { fromFile: /srv/oats-operator/credentials/sources-read }
482
+ knowledge-propose: { fromFile: /srv/oats-operator/credentials/knowledge-propose }
483
+ settings:
484
+ oats.aweb-sandbox:
485
+ sandboxes:
486
+ ingest:
487
+ deployment: /srv/oats-operator/ingest/deployment.yaml # teamctl host facts
488
+ settings:
489
+ oats.aweb: { registry: https://registry.example.org } # private registry only
490
+ oats.okf: { github-token-file: /run/oats-credentials/knowledge-propose }
491
+ oats.aweb: { registry: https://registry.example.org } # the host-side mint (C6)
492
+ ```
493
+
494
+ - `sandboxes` lists distinct names that the workspace declares. An unknown name is
495
+ refused (`E_WORKSPACE_SCHEMA`, reason `sandbox-unknown`), a duplicate likewise
496
+ (`duplicate-entry`), and so is a listed sandbox with no `host.name` (reason
497
+ `sandbox-host-name-required`) (r1).
498
+ - `credentials` uses the kernel's existing `fromFile` form. A listed sandbox whose
499
+ declared credential has no source here refuses its start, naming the credential.
500
+ - The teamctl file holds infrastructure only (images, network, ports, state directory,
501
+ limits). The provider refuses a file that sets a boundary field the workspace owns
502
+ (`team.id`, the role booleans `egress.external.source`, `.model` and `.forge`,
503
+ `aweb.federationOutbound`): boundaries are declared once. The refusal is
504
+ `E_SANDBOX_DEPLOYMENT`, reason `boundary-field`, naming the field (r1). The
505
+ resolvers the external roles need, `egress.external.resolvers`, are host
506
+ infrastructure and stay in the teamctl file; a sandbox whose workspace egress names
507
+ an external role and whose file gives no resolvers refuses its start (reason
508
+ `resolvers-required`) (r3, contract). The provider writes the role booleans from
509
+ the workspace. Example: `egress: { external: { resolvers: [1.1.1.1, 9.9.9.9] } }`
510
+ in the teamctl file, with C1's `egress: [model, source, forge]`.
511
+ - **A private registry.** oats.aweb refuses an ambient `AWID_REGISTRY_URL`
512
+ (awebai/oats-aweb#284), so where the sandbox team's registry is private the setting
513
+ is written twice: `settings.oats.aweb.registry` on the host deployment, for the mint
514
+ and for `remove-member` (C6), and the same key in the sandbox's `settings`, which the
515
+ provider writes into the in-sandbox local file. Without the in-sandbox one, the
516
+ in-sandbox spawn refuses with `registry-setting-required`.
517
+
518
+ ### C3b. `oats-local.yaml` inside a sandbox: `sandbox: { self: <name> }` (new root key)
519
+
520
+ The provider writes it into the in-sandbox deployment's local file. It is a contract of
521
+ its own because a kernel reads it:
522
+
523
+ - `self` must name a sandbox the workspace declares. That deployment then spawns only
524
+ souls placed in that sandbox, and refuses others with `E_SANDBOX_PLACEMENT`.
525
+ - It may not be combined with `sandboxes:` (a sandbox runs no sandboxes),
526
+ `credentials:` (credentials reach it as mounts only), local `teams:` or local
527
+ `defaultTeam`. Each combination is refused with `E_WORKSPACE_SCHEMA`, reason
528
+ `sandbox-self-conflict`.
529
+ - An older kernel refuses the key as unknown. That is why the agent image's kernel is
530
+ the release that has feature `sandboxes`.
531
+
532
+ ### C4. The kernel–provider hook: `sandbox`
533
+
534
+ A new capability hook event, `sandbox`.
535
+
536
+ **Which capability provides it (r1).** Sandbox acts run at deployment level, with no
537
+ soul. The candidates are the capabilities the workspace's `defaults` compose (the
538
+ same resolution a spawn uses, without a soul's layer) whose manifest declares the
539
+ `sandbox` hook. Exactly one must exist: none refuses any sandbox act with
540
+ `E_SANDBOX_PROVIDER`, reason `none`; two or more, reason `ambiguous`, naming them. Its
541
+ settings are its manifest defaults, then the workspace defaults, then the host's
542
+ `settings.<capability>` in `oats-local.yaml`, merged as for a spawn.
543
+
544
+ **The call.** The kernel runs the hook with `OATS_SANDBOX_ACT` set to `plan`, `start`,
545
+ `stop`, `status`, `reconcile`, `seat`, `bind` or `release`, one JSON request on stdin, and reads one JSON
546
+ answer on stdout. The kernel holds a per-sandbox lock around every act but `plan` and
547
+ `status`, so two mutating acts on one sandbox never run at once (a second gets
548
+ `E_LIFECYCLE_BUSY`). The lock, the plan revisions and the idempotency keys are all
549
+ scoped to the deployment and the sandbox (C7's deployment key) (r2). A
550
+ hook that exits nonzero, times out or prints anything but one valid answer is read as
551
+ `state: "unknown"` with problem `E_SANDBOX_PROVIDER`, reason `hook-failed`.
552
+
553
+ **Every request** carries:
554
+
555
+ ```json
556
+ {"sandboxApi":1,"act":"start","sandbox":"ingest","host":"cloud-1",
557
+ "team":{"label":"ingest-team","id":"ingest:example.org"},
558
+ "egress":["model","source"],
559
+ "credentials":[{"name":"sources-read","path":"/srv/…"}],
560
+ "workspace":{"url":"…","commit":"…","lock":"<sha256>"}}
561
+ ```
562
+
563
+ and by act:
564
+
565
+ | Act | Extra request fields | Answer fields beyond the envelope |
566
+ | --- | --- | --- |
567
+ | `plan` | `target`: `start`, `stop`, `reconcile`, `seat`, `bind` or `release`; for target `seat`, `instance: {soul, spawnKey}`; for `bind` and `release`, the `instance` fields of that act | `planRevision`, `actions: [{step, detail}]`; for target `seat` also `seat: {id, path}` and `spawnProvider: {capability, options: {<key>: <value>}}` |
568
+ | `start`, `stop`, `reconcile` | `planRevision`, `idempotencyKey` | `server`; for `reconcile`, `seats` as in `status` |
569
+ | `status` | none | `server`, `seats: [{seatId, instance, alias, certificateId, state}]` |
570
+ | `seat` | `planRevision`, `idempotencyKey`, `instance: {name, soul, spawnKey, decision}` (`decision` is `D`, the remote preview's `decision.revision`) | `seat: {id, path, alias, certificateId, team}` |
571
+ | `bind` | `planRevision`, `idempotencyKey`, `instance: {name, spawnKey}`, `apply`: the routed apply's answer as the kernel received it | `seat: {id, certificateId, state}` |
572
+ | `release` | `planRevision`, `idempotencyKey`, `instance: {name, seatId}`, `reason`: `retired` or `spawn-failed` | `seat: {id, certificateId, state}` |
573
+
574
+ **The envelope** of every answer:
575
+
576
+ ```json
577
+ {"sandboxApi":1,"act":"…","state":"ready|stopped|absent|failed|unknown|stale",
578
+ "receipts":[{"step":"render|probe|start|register|deploy|mint|deliver|remove","ok":true,"detail":"…"}],
579
+ "problem":{"code":"…","reason":"…","message":"…","remedy":"…"}}
580
+ ```
581
+
582
+ - `plan` and `status` are read-only: they change no state, delete no staging and remove
583
+ no member (r2). Every other act mutates, and runs under the lock.
584
+ - `plan` is read-only. Its `planRevision` binds the request's inputs and the
585
+ provider's own state for that sandbox (and, for `seat` and `release`, that
586
+ instance's ledger entry).
587
+ - **The provider owns revisions and receipts.** It checks `planRevision` on every
588
+ act that carries one, and answers `state: "stale"` with a fresh plan in `plan`; the
589
+ kernel reports that as `E_PLAN_STALE` with the fresh plan, on the pattern of `oats
590
+ instance stop`. It keeps each `idempotencyKey`'s receipt in its state on the host,
591
+ and the same key replays that receipt and changes nothing.
592
+ - `seat` mints and delivers one instance's seat, in the order the Identities section
593
+ gives. A replay of its key returns the same seat, or `unknown`, and never mints a
594
+ second identity. The kernel passes the seat plan's `spawnProvider` to the final
595
+ preview and to the apply alike, as `--provider <capability> <key>=<value>`, one per
596
+ option, so the kernel names no messaging provider. Dotted keys nest, so oats.aweb
597
+ answers `{capability: "oats.aweb", options: {"identity.seat": "<path>"}}`, which sets
598
+ its `identity.seat` (C6) (r2).
599
+ - `bind` and `reconcile` settle seats as the Identities and Lifecycle sections say:
600
+ `bind` from the routed apply's answer or the kernel's keyed replay of it (for
601
+ `delivered` seats), `reconcile` from the sandbox's untrusted report (for `active`
602
+ seats) and the interrupted-mint rule. The provider runs no spawn. The
603
+ staging sweep for a killed hook runs in the mutating acts only: under the lock no
604
+ `seat` can be running, so any staging copy found is a leftover.
605
+ - An act whose outcome is uncertain answers `unknown`, never `ready`.
606
+
607
+ ### C5. CLI and JSON
608
+
609
+ - `oats sandbox status [--json]`, `oats sandbox start|stop <name> (--plan | --plan-revision <r> --idempotency-key <k>)`.
610
+ - `oats sandbox status --json` answers
611
+ `{sandboxApi:1, host, sandboxes:[{name, team:{label,id}, listedHere, state, server, egress, credentials:[{name, source:"present"|"missing"}], problems}]}`.
612
+ - `oats sandbox start|stop <name> --plan --json` answers
613
+ `{sandboxApi:1, sandbox, act, planRevision, actions}`; the apply answers
614
+ `{sandboxApi:1, sandbox, act, state, server, receipts, problems}`, and a stale
615
+ revision refuses `E_PLAN_STALE` with the fresh plan in its detail (r1).
616
+ - `oats sync --json` gains `sandboxes` with the same entries plus `action`
617
+ (`build|start|stop|none`). The field is additive, so `syncApi` stays 1.
618
+ - `oats status --json` gains `placement: {sandbox, seatId}` on each instance placed in
619
+ one; `seatId` is the seat its home took (r2).
620
+ - `oats sandbox status --json`'s entries also carry `seats` (as C4's `status`), and
621
+ `oats sandbox reconcile <name> (--plan | --plan-revision <r> --idempotency-key <k>)`
622
+ runs on its own what sync runs for each sandbox: the `reconcile` act, then the
623
+ replays of the kept requests whose entries it answers durably `delivered` (r2, r3,
624
+ r4d).
625
+ - **That these are additive must be shown, not assumed.** The readers of sync's answer
626
+ are `packages/desktop/server/workspace-sync.mjs`,
627
+ `packages/desktop/renderer/workspace-sync-view.mjs`,
628
+ `packages/client/deployment-data.mjs` and `packages/client/workspace-cli.mjs`. The
629
+ readers of the status answer are the client's roster readers and the warm reader. S1
630
+ lists every reader it finds, with file and line, and pins one test per reader feeding
631
+ it an answer with the new fields. If a reader refuses unknown fields, the change is
632
+ not additive: that answer's API version goes up, and the reader changes first, in its
633
+ own PR.
634
+
635
+ ### C6. oats.aweb settings and behaviour
636
+
637
+ - `identity.seat` (new): an absolute path to a one-use seat delivered by the host. The
638
+ spawn copies it the way it copies `identity.source`, takes no retained-seat lock, and
639
+ deletes the delivered copy after connecting. It is refused together with
640
+ `identity.source` and with global mode. A preview reads nothing from it; an apply
641
+ needs it.
642
+ - **The seat descriptor (r2).** The retained route reads its service from the
643
+ source's `workspace.yaml`, which is not an authority file. A delivered seat instead
644
+ carries `seat.json`, written by the host at mint:
645
+ `{seatApi:1, seatId, spawnKey, service, team, alias, certificateId}`, where `service`
646
+ is the aweb origin of the sandbox's own server (the egress `aweb` role's origin).
647
+ The spawn reads its service from that descriptor only, never from `OATS_AWEB_URL` or
648
+ a copied coordination workspace, and checks it: `team` equals the team the spawn
649
+ resolved, `alias` equals the instance name, `spawnKey` equals the apply's key, and
650
+ `service` is a plain https origin. The apply's key reaches the spawn hook through a
651
+ new, generic hook variable, `OATS_SPAWN_IDEMPOTENCY_KEY`, set by the kernel on a
652
+ keyed apply and absent otherwise (r3, contract: the hook environment; S1 sets it and
653
+ pins it, S2 consumes it). An unkeyed apply with `identity.seat` is refused (reason
654
+ `seat-binding`, field `spawnKey`); the provider never takes the expected key from
655
+ the descriptor it validates. A missing, malformed or contradictory descriptor
656
+ refuses the spawn (reason `seat-binding`, naming the field). The host's registry pin
657
+ is a separate setting (C3), never the service.
658
+ - Retire, for an identity minted by the host for a sandbox: the host runs
659
+ `aw id team remove-member` with the controller key it holds, and reports it, from
660
+ the routed retire or from reconcile (the Lifecycle section). It
661
+ removes by the certificate ID that the mint recorded, never by alias. It removes only
662
+ an identity listed in the provider's ledger of seats this host minted for this
663
+ sandbox. An identity it did not mint is never removed, and is reported instead. It
664
+ uses the host's configured registry pin (`settings.oats.aweb.registry`, C3), and
665
+ records its receipt in the retire's meta. A failure, or an outcome it cannot be sure
666
+ of, keeps today's recorded command and warning, and is never retried automatically.
667
+ - Between mint and delivery, the instance's private key sits in the host's staging
668
+ directory (0700, under the operator account). `seat` deletes the staging copy on
669
+ every path: success, a failed mint, a failed delivery, a timeout and an interrupted
670
+ hook. The next mutating act (C4) finds and removes a copy left by a killed hook, and
671
+ reports it; `status` only reports it (r2). One test per path pins this.
672
+ - `oats.aweb-sandbox` (new capability, same package): its settings are
673
+ `sandboxes.<name>.deployment` and `sandboxes.<name>.settings` (C3).
674
+
675
+ ### C7. The sandbox's server registration
676
+
677
+ The provider registers each started sandbox as server `sandbox-<name>`, using the
678
+ existing Docker-context SSH relay from container.md.
679
+
680
+ - It uses only the fields `servers.json` accepts today (`sshHost`, `workspace`,
681
+ `oatsPath`, `path`), so an older kernel still reads the file. Anything else the
682
+ provider keeps goes in its own state, never in `servers.json`.
683
+ - The `sshHost` alias lives in an OpenSSH file the provider owns,
684
+ `~/.oats/sandboxes/ssh_config`, which holds the relay, the per-sandbox operator key
685
+ it generates and the known-hosts file it provisions from the sandbox's host key. The
686
+ operator adds one `Include` of that file to their own SSH configuration once. Readiness
687
+ reports `sandbox-ssh-include-missing` until they have.
688
+ - The `sandbox-` prefix is reserved. A new `oats server add|connect` with that prefix is
689
+ refused (`E_SERVER_INVALID`, reason `reserved-prefix`). A `sandbox-*` server that is
690
+ already registered is reported by `oats sandbox status`, not refused: refusing
691
+ configuration that was accepted before would itself be a contract change. The provider
692
+ will not adopt or overwrite it, and that sandbox's start refuses, naming the server
693
+ (`E_SANDBOX_SERVER`, reason `server-taken`).
694
+ - **Its own registration is not "already registered" (r1).** The provider records
695
+ each registration it made in its state, with the `servers.json` entry it wrote. A
696
+ `sandbox-<name>` server that matches its record is its own: a restart reuses it, and
697
+ stop and delisting keep it and the record, so the sandbox can start again. Only a
698
+ `sandbox-*` server with no matching record counts as taken.
699
+ - **Scoped to the deployment (r2).** `servers.json`, the SSH file and the provider's
700
+ state are per OS user, and two deployments of that user may each declare a sandbox
701
+ of the same name. So the provider's state lives under a deployment key, the first 16
702
+ hex digits of the SHA-256 of the host deployment directory's real path:
703
+ `~/.oats/sandboxes/<deployment-key>/<sandbox>/`. The registration record names its
704
+ deployment key. A `sandbox-<name>` server recorded for another deployment key is
705
+ never reused, stopped or overwritten: this deployment's start refuses
706
+ (`E_SANDBOX_SERVER`, reason `server-owned-elsewhere`, naming the other deployment
707
+ directory). The public name stays `sandbox-<name>`.
708
+ - **A moved deployment.** Moving or renaming the deployment directory changes its key
709
+ and orphans its sandboxes' ledger, lock and receipts. Readiness reports
710
+ `sandbox-state-orphaned` when provider state under another key holds a sandbox this
711
+ deployment lists, naming the old key. It is never adopted automatically; the remedy
712
+ names moving the directory back, or the manual adoption step S2 specifies.
713
+
714
+ ### C8. teamctl and the container (aweb's maintainers)
715
+
716
+ - **Credential mount:** a new teamctl input, `agents.credentials`, a map from name to a
717
+ host file. It is rendered as read-only binds at `/run/oats-credentials/<name>` through a
718
+ new `container/agent/compose.agent.credentials.yaml` fragment. teamctl's
719
+ `agents.secrets` stays the harness login only.
720
+ - **Probe:** the boundary probe asserts that each credential mount is read-only, that
721
+ it lies only under `/run/oats-credentials`, and that no undeclared credential path is
722
+ mounted. Its receipt joins the probe's `--json` receipts (#1958).
723
+ - **Protected sources (r1, r2, r3):** the provider writes one JSON file per start,
724
+ `{"protectedSourcesApi":1, "hardDenied":[<path>], "credentialSources":[<path>],
725
+ "declaredBinds":[{"source":<path>,"target":"/run/oats-credentials/<name>"}]}`, with
726
+ real paths, and gives it to teamctl as a new input, `agents.protectedSourcesFile`
727
+ (contract: teamctl's schema, aweb's maintainers). teamctl passes it to the container's
728
+ mount acceptance, which takes those three parts and, on the started
729
+ agent's actual mounts, asserts that no bind equals, contains or lies inside a
730
+ protected path, the declared credential binds being the only exception to the
731
+ credential-source part. It runs before any seat is admitted.
732
+ - **Optional, later:** a slimmer profile without Secrets and Logs. v1 runs with
733
+ teamctl's four base routes.
734
+ - teamctl's changes are these three inputs: `agents.credentials`,
735
+ `agents.protectedSourcesFile` and `egress.external.forge`. OATS reads its exit codes
736
+ as they are.
737
+
738
+ ### C9. Broker contracts (designed now, built against the first real provider)
739
+
740
+ Both follow aweb's three rules. An agent never reads or exports a value. Approval is a
741
+ state with a reference, and the same request is resubmitted under the same request ID.
742
+ Authority, custody, approval, where execution happens, audit and withholding all stay
743
+ with the provider. Inside a sandbox, an agent reaches a broker through the sandbox's
744
+ egress routes only.
745
+
746
+ - **Secrets:** `oats credential list [--json]` shows only the names the caller is
747
+ granted. `oats credential use <name> --action <action> --request-id <id> [--input-file <f>] --json`
748
+ answers `{requestId, state: "done"|"awaiting-approval"|"refused"|"unknown"|"withheld", approvalRef?, result?}`.
749
+ There is no verb that returns a value. A capability implements the contract through a
750
+ `credential-broker` hook with the same request and answer.
751
+ - **Connectors:** a sandbox may list `connectors: [<name>]` in C1, a later optional
752
+ key. `oats connector call <name> <operation> --request-id <id> [--input-file <f>] --json`
753
+ takes the same outcome states, through a `connector-broker` hook. aweb has no
754
+ connectors broker built or filed, and whether one is planned is for aweb's maintainers to say. The
755
+ shape is offered so that a provider-neutral gateway can implement it. It stays
756
+ designed only, and is not built, until aweb's maintainers say whether aweb plans a connectors
757
+ broker and a provider exists.
758
+ - **Order:** both contracts are agreed in this record. Each is built when its first real
759
+ provider ships, and checked against that provider's interface before it is released.
760
+ This keeps the product owner's decision to design both now, and aweb's maintainers' point that a public
761
+ contract must not take its shape from one unshipped product.
762
+ - **What S4's spec settles before it is built (r1),** each a contract both sides
763
+ agree: the `credential list` JSON and its hook request; how the broker capability
764
+ is selected, and the no-provider refusal; how the caller and its grant are bound
765
+ to a request; the scope of a request ID, and what a resubmission with the same ID
766
+ but a different payload gets; and how `result` is kept free of secret values.
767
+ Agreement on this outline is not permission for a provider to choose those.
768
+ - **A change the provider forces is a contract decision.** If checking against the
769
+ first real provider shows the agreed shape must change, the change goes back to both
770
+ sides as a contract decision before it is built. It is never a doc edit.
771
+
772
+ ### C10. Readiness reports; the acts refuse
773
+
774
+ `oats readiness` reports, and refuses nothing. Its new items are:
775
+
776
+ - `sandbox-listed-not-running`;
777
+ - `sandbox-credential-missing`;
778
+ - `sandbox-host-agents`: a deployment that lists a sandbox has host-placed instances,
779
+ running or stopped;
780
+ - `sandbox-provider-missing`;
781
+ - `sandbox-ssh-include-missing`;
782
+ - `sandbox-seat-unsettled`: a `mint-uncertain` seat, with or without a certificate
783
+ ID (r4d: one whose delivered copy could not be confirmed deleted stays here); a
784
+ `delivered` seat with no kept request, including one whose release waits on a copy
785
+ deletion that could not be confirmed; or a `delivered` seat whose last replay
786
+ answered `E_IDEMPOTENCY_CONFLICT` or `E_SPAWN_INCOMPLETE` (r2, r3, r4d). A pinned
787
+ negative: a known certificate ID whose copy deletion fails gives no replay, no home,
788
+ and this item;
789
+ - `sandbox-state-orphaned`: provider state under another deployment key for a
790
+ sandbox this deployment lists (r2);
791
+ - `sandbox-pending-stale`: a kept routed request older than 24 hours, named by its
792
+ spawn key, never its task (r3).
793
+
794
+ The refusals belong to the acts:
795
+
796
+ | Condition | Refused by | Code |
797
+ | --- | --- | --- |
798
+ | Listed sandbox, no provider | `oats sandbox start`, sync's start, a routed spawn | `E_SANDBOX_PROVIDER` |
799
+ | A declared credential with no source, or a missing source file | `oats sandbox start`, sync's start | `E_SANDBOX_CREDENTIAL` |
800
+ | A host-placed spawn in a deployment that lists a sandbox | `oats spawn`, a schedule's spawn | `E_SANDBOX_HOST_AGENT` |
801
+ | Starting, restarting or resuming a host-placed home there (r1) | `oats session start`, the resume sweep | `E_SANDBOX_HOST_AGENT` |
802
+ | A running or unreadable host-placed home when a sandbox starts (r1) | `oats sandbox start`, sync's start | `E_SANDBOX_HOST_AGENT` |
803
+ | A spawn inside a sandbox without a host-delivered seat (r1) | the in-sandbox `oats spawn` | `E_SANDBOX_PLACEMENT`, `spawn-from-host` |
804
+ | A teamctl file that sets a boundary field (r1) | `oats sandbox start`, sync's start | `E_SANDBOX_DEPLOYMENT`, `boundary-field` |
805
+ | A mount that overlaps a protected path, or shared sandbox state (r1) | `oats sandbox start`, sync's start | `E_SANDBOX_MOUNT`, `overlap` |
806
+ | A credential source that is not a regular file (r1) | `oats sandbox start`, sync's start | `E_SANDBOX_CREDENTIAL`, `not-a-file` |
807
+ | A credential source with more than one hard link (r3) | `oats sandbox start`, sync's start | `E_SANDBOX_CREDENTIAL`, `hardlinked` |
808
+ | An external egress role with no resolvers in the teamctl file (r3) | `oats sandbox start`, sync's start | `E_SANDBOX_DEPLOYMENT`, `resolvers-required` |
809
+ | An unkeyed apply carrying `identity.seat` (r3) | the in-sandbox apply | `seat-binding` (oats.aweb), field `spawnKey` |
810
+ | `sandbox-<name>` registered by someone else (r1) | `oats sandbox start`, sync's start | `E_SANDBOX_SERVER`, `server-taken` |
811
+ | `sandbox-<name>` owned by another deployment (r2) | `oats sandbox start`, sync's start | `E_SANDBOX_SERVER`, `server-owned-elsewhere` |
812
+ | The sandbox's team has no provider id yet (r2) | `oats sandbox start`, sync's start, a routed spawn | `E_SANDBOX_TEAM`, `team-not-created` |
813
+ | A delivered seat with a missing or contradictory descriptor (r2) | the in-sandbox apply | `seat-binding` (oats.aweb) |
814
+ | No provider, or more than one (r1) | every sandbox act | `E_SANDBOX_PROVIDER`, `none` or `ambiguous` |
815
+ | A sandboxed soul on a host that does not list or run its sandbox | `oats spawn`, a schedule's spawn | `E_SANDBOX_NOT_HERE` |
816
+ | A soul not placed in this sandbox, inside it | the in-sandbox `oats spawn` | `E_SANDBOX_PLACEMENT` |
817
+
818
+ **Why `E_SANDBOX_HOST_AGENT`.** The controller key and the credential sources sit under
819
+ the account that runs the deployment, because that account mints the seats. A host-side
820
+ agent of the same deployment would run as that account and could read them. So in v1, a
821
+ deployment that lists a sandbox runs every agent in a sandbox. Agents that belong on the
822
+ host run from another deployment, under another OS user. This replaces checking file
823
+ modes against users, which cannot be proved from inside one account.
824
+
825
+ ## Left out of v1
826
+
827
+ - Creating or deleting machines.
828
+ - Several sandboxes for one team, and explicit placement.
829
+ - A bridge soul between a sandboxed team and another team.
830
+ - Human IDs by default and `oats sandbox adopt`. These wait on aweb's maintainers' decision
831
+ on reversing "strictly opt-in" (#1665). Adoption is specified once
832
+ those are settled.
833
+ - Kubernetes. The provider contract (C4) is platform-neutral, and v1's provider is
834
+ Compose through teamctl.
835
+ - Publishing the image, and its digest in the lock.
836
+
837
+ ## Alternatives rejected
838
+
839
+ - **A groups block with its own soul list:** it writes the soul-to-team mapping twice.
840
+ - **Sandbox fields inside team entries:** no named container would remain to list, build
841
+ or show.
842
+ - **`hostedBy: everyone` for containers:** Docker could start on a laptop that never
843
+ asked for it.
844
+ - **A sandbox that lists its own souls and gets an automatic team:** rejected by the product owner.
845
+ - **Docker in the kernel:** the kernel stays runtime-neutral; the provider owns
846
+ containers.
847
+ - **The container's own clock beside the host's:** two owners of one schedule.
848
+ - **Free-form egress origins:** the egress component's guarantee rests on a closed set
849
+ of roles.
850
+ - **Credentials through teamctl's `agents.secrets`:** that mount is the harness login
851
+ only, by its own contract.
852
+ - **A lease service for schedules:** none exists, and `runsOn` already names one host.
853
+
854
+ ## Delivery
855
+
856
+ | Spec | Surface | Lane | Builds first |
857
+ | --- | --- | --- | --- |
858
+ | S1 Kernel: C1, C2, C3, C4's caller, C5, C10, placement and routing | `lib/`, `bin/`, schemas, `docs/` | lane:product | first; built now, merged after #1912's hold lifts |
859
+ | S2 Provider: `oats.aweb-sandbox`, C4's hook, C6, C7, the registry setting (C3) | the oats-aweb package | lane:setup, aweb's maintainers read first | after S1's contract is merged |
860
+ | S3 Credential mount and the `forge` role: C8, the egress component, teamctl's inputs | `container/agent`, and teamctl on aweb's maintainers' side | lane:juan | in parallel with S1 |
861
+ | S4 Broker contracts: C9 docs, then the client verbs | `docs/`, `lib/` | lane:product | after the first real provider |
862
+
863
+ Each spec carries its own reference pages and a release-notes entry of its own under
864
+ `docs/release-notes/next/` (r1):
865
+
866
+ - S1: [workspaces.md](../workspaces.md) (`sandboxes:`, the rollout rule, C2's
867
+ refusals), [configuration.md](../configuration.md) (C3, C3b), [capabilities.md](../capabilities.md)
868
+ and the manifest schema (the `sandbox` hook, C4), the CLI and JSON pages (C5),
869
+ [servers.md](../servers.md) (the reserved prefix, C7), and readiness (C10).
870
+ - S2: the oats-aweb package's own docs (`identity.seat`, the registry setting,
871
+ `oats.aweb-sandbox`'s settings, the ledger and reconcile).
872
+ - S3: [container.md](../container.md) (the credential fragment and its probe) and
873
+ teamctl's docs on aweb's maintainers' side.
874
+ - S4: the broker contracts' reference page, when it is built.
875
+
876
+ The live rehearsal runs on a disposable Linux Docker host, never on a person's machine.
877
+ It covers every "done means" line, with the egress and boundary probes' receipts kept as
878
+ evidence.