@awebai/oats 0.69.22 → 0.69.24

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 (98) hide show
  1. package/bin/oats.mjs +185 -38
  2. package/docs/capabilities.md +365 -7
  3. package/docs/capability-manifest.schema.json +37 -1
  4. package/docs/configuration.md +27 -7
  5. package/docs/container.md +206 -228
  6. package/docs/design/2026-11-19-sandboxes.md +1352 -0
  7. package/docs/design/2026-11-20-provider-home-lifecycle.md +320 -0
  8. package/docs/design/README.md +7 -0
  9. package/docs/desktop-cli-api.md +673 -81
  10. package/docs/desktop.md +241 -65
  11. package/docs/execution-targets.md +186 -3
  12. package/docs/first-team.md +11 -0
  13. package/docs/implementation.md +6 -2
  14. package/docs/integrations.md +3 -3
  15. package/docs/knowledge-capability-authoring.md +10 -7
  16. package/docs/knowledge-reference/acceptance.md +21 -19
  17. package/docs/knowledge-reference/adoption.md +18 -4
  18. package/docs/knowledge-reference/model.md +11 -9
  19. package/docs/knowledge-reference/package-craft.md +2 -2
  20. package/docs/knowledge-reference/proposal.md +127 -0
  21. package/docs/knowledge-reference/provider-mapping.md +10 -10
  22. package/docs/knowledge-reference/reader-capture.md +26 -22
  23. package/docs/knowledge-theory.md +1 -1
  24. package/docs/knowledge.md +25 -16
  25. package/docs/official-catalog.md +4 -4
  26. package/docs/packages.md +13 -13
  27. package/docs/release-notes/v0.69.23.md +231 -0
  28. package/docs/release-notes/v0.69.24.md +264 -0
  29. package/docs/servers.md +10 -6
  30. package/docs/souls-and-instances.md +96 -22
  31. package/docs/tui.md +25 -4
  32. package/docs/upgrading.md +19 -5
  33. package/docs/workspaces.md +14 -6
  34. package/lib/argv.mjs +6 -2
  35. package/lib/capability-contract.mjs +2 -2
  36. package/lib/capability-show.mjs +11 -1
  37. package/lib/command-flags.mjs +40 -3
  38. package/lib/compile-cache.mjs +1 -1
  39. package/lib/core.mjs +1201 -195
  40. package/lib/errors.mjs +4 -1
  41. package/lib/hook-env.mjs +106 -0
  42. package/lib/host-run.mjs +11 -3
  43. package/lib/instance-board.mjs +337 -0
  44. package/lib/instance-events.mjs +48 -10
  45. package/lib/instance-inspect.mjs +44 -0
  46. package/lib/instance-lifecycle.mjs +34 -18
  47. package/lib/instance-listing.mjs +113 -16
  48. package/lib/instance-related-work.mjs +143 -0
  49. package/lib/kernel-features.mjs +13 -1
  50. package/lib/node-version.mjs +9 -0
  51. package/lib/provider-call-child.mjs +60 -0
  52. package/lib/provider-resume.mjs +83 -0
  53. package/lib/provider-test-seams.mjs +20 -0
  54. package/lib/read-call.mjs +2 -0
  55. package/lib/reserved-launch-env.mjs +8 -1
  56. package/lib/retire-admission.mjs +5 -1
  57. package/lib/schedule.mjs +14 -4
  58. package/lib/servers.mjs +151 -17
  59. package/lib/session-inspect.mjs +104 -13
  60. package/lib/session-providers.mjs +528 -0
  61. package/lib/session-resume.mjs +68 -15
  62. package/lib/stable-node.mjs +3 -0
  63. package/lib/triggers.mjs +3 -1
  64. package/package-catalog.json +3 -3
  65. package/package.json +2 -1
  66. package/packages/client/capability-list.mjs +21 -0
  67. package/packages/client/cli-adapter.mjs +19 -4
  68. package/packages/client/cli-locator.mjs +5 -1
  69. package/packages/client/deployment-data.mjs +27 -3
  70. package/packages/client/deployment-panel.mjs +27 -4
  71. package/packages/client/home-board.mjs +33 -19
  72. package/packages/client/inspect-boundary.mjs +18 -8
  73. package/packages/client/instance-acts.mjs +30 -3
  74. package/packages/client/instance-board.mjs +206 -0
  75. package/packages/client/instance-presentation.mjs +55 -0
  76. package/packages/client/instance-tree.mjs +34 -4
  77. package/packages/client/keymap.mjs +5 -0
  78. package/packages/client/liveness.mjs +15 -4
  79. package/packages/client/mail-contract.mjs +130 -0
  80. package/packages/client/own-codes.mjs +5 -1
  81. package/packages/client/panel-views.mjs +7 -7
  82. package/packages/client/related-work.mjs +84 -0
  83. package/packages/client/remote-roster.mjs +9 -3
  84. package/packages/client/session-backends.mjs +31 -0
  85. package/packages/client/session-start.mjs +18 -6
  86. package/packages/client/spawn-apply-cli.mjs +5 -3
  87. package/packages/client/spawn-apply-contract.mjs +25 -2
  88. package/packages/client/spawn-apply.mjs +5 -1
  89. package/packages/client/spawn-messages.mjs +3 -0
  90. package/packages/client/terminal-contract.mjs +4 -0
  91. package/packages/client/waiting-on-you.mjs +12 -2
  92. package/packages/client/workspace-cli.mjs +13 -2
  93. package/packages/tui/lib/model.mjs +14 -3
  94. package/packages/tui/lib/store.mjs +12 -3
  95. package/skills/oats-getting-started/SKILL.md +11 -8
  96. package/docs/knowledge-reference/harvester.md +0 -109
  97. package/lib/instance-same-work.mjs +0 -67
  98. package/packages/client/same-work.mjs +0 -49
@@ -0,0 +1,1352 @@
1
+ # Sandboxes: boundaries declared in the workspace, started by `oats sync`
2
+
3
+ **Amended in r5 (2026-11-20), decided by both sides.** Placement no longer follows a
4
+ team. A sandbox lists the souls it may run, admits the capabilities their resolved
5
+ compositions need (with optional exclusions, behind an applied-plan gate), and has no
6
+ team. A soul's team is declared once, in `souls:`, and
7
+ placement never changes it. Messaging between agents is governed by aweb's policy,
8
+ whichever sandboxes they run in. What can an agent do? That's authorized per team or
9
+ per long-lived principal, by the resource's owner. This replaces the rule "a soul runs
10
+ in sandbox S when its resolved default team is S's team" everywhere below, and with it
11
+ C2's team routes. Items changed in r5 are marked "(r5)". The reviewed behaviour that
12
+ never depended on team placement is unchanged: the keyed replay, proof before a seat
13
+ is released (r4d), one owner of each schedule's clock, and explicit local selection.
14
+
15
+ **Status:** contracts decided, 2026-11-19. The product owner's side and aweb's maintainers agreed
16
+ C1–C10 and C3b as written at 0849ef12, with aweb's maintainers' four changes, which
17
+ the product owner's side accepted: the registry setting (C3, C6), a keyed `seat` (C4), the receipt of the host's
18
+ `remove-member` (C6) and the credential-mount probe (C8). The connector half of C9
19
+ stays designed only. Nothing is built yet. **Revised after review round 1** (marked
20
+ "(r1)" below): existing host homes, lifecycle calls made inside a sandbox, C4's
21
+ per-act wire shapes and provider selection, shared team aliases, mount overlap, the
22
+ first use's GitHub API route, managed server registrations, and the missing refusal
23
+ codes. Both sides decided those, with two precisions from aweb's maintainers, and decided the
24
+ `forge` egress role for the GitHub API. **Revised again after review round 2** (marked
25
+ "(r2)"): every real agent bind is checked, `status` mutates nothing, the routed
26
+ spawn's exact sequence and seat binding, the seat's service descriptor, provider state
27
+ scoped per deployment, a team not yet created, and the seat option's key. Both sides
28
+ decided the r2 additions, with `sandbox-state-orphaned`. **Revised after review round
29
+ 3** (marked "(r3)"): the apply is bound to the preview's `decision.revision`; the seat
30
+ plan needs only the spawn key; the spawn hook learns the apply's key; the kernel keeps
31
+ the full routed request for replay; mint recovery; hardlinked credentials; the
32
+ resolvers are host infrastructure; the protected-sources input shape; and the `forge`
33
+ role's Host guarantee corrected to what a TLS pass-through can enforce. Both sides
34
+ decided the r3 contracts, with the domain-fronting risk statement and the pending
35
+ request's custody. **Revised after review round 4** (marked "(r4)"): the apply
36
+ evidence `bind` acts on, and the fence that keeps a replay away from an interrupted
37
+ delivery. **Revised after the round-4 delta read** (marked "(r4d)"): a seat is
38
+ released only on proof that no home can hold it, and the readiness and ordering text
39
+ that follows from that. A later change to a contract goes back to
40
+ both sides (the lane map's "Contract changes" line). When this record and a reference
41
+ page disagree after it is built, the reference page wins.
42
+
43
+ ## The goal
44
+
45
+ One machine runs `oats sync` on a deployment, and the sandboxes that deployment lists
46
+ are built and started, with their boundaries declared once in the workspace. The first
47
+ use is scheduled knowledge-base ingestor agents on a cloud machine: they read untrusted
48
+ content, so they must not reach the engineers' agents, credentials or network.
49
+
50
+ **Done means:** on a Linux machine with Docker, a workspace that declares one sandbox,
51
+ and a deployment whose local file lists it, `oats sync` builds and starts the sandbox,
52
+ and one reviewed `oats sync --admission-revision` admits its souls' capabilities (an
53
+ ordinary sync widens nothing, so the first tick needs that first admission). A workspace schedule whose `runsOn` names that machine spawns a soul the sandbox lists
54
+ inside it, with an identity minted on the host. The agent reaches only the declared
55
+ destinations and reads only the declared credentials. It messages only as its team,
56
+ its server and aweb's policy allow. For the ingestors that is a closed topology: their
57
+ own team on their own aweb server, with federation outbound off. That's a policy
58
+ configured for that use, not something placement implies (r5). Retiring the agent
59
+ removes its identity from the team. Delisting the sandbox stops it and destroys
60
+ nothing. All of this is shown by a live rehearsal and by the tests pinned in each spec.
61
+
62
+ ## Decided with the product owner
63
+
64
+ - **Five separate decisions (r5).** A team is membership and messaging. A sandbox is a
65
+ runtime boundary (its local state, mounts and egress). Placement is which sandbox a
66
+ soul may run in. Identity is who an instance acts as. Authority is what it may do.
67
+ Each is declared and checked on its own (The design, "Five independent decisions").
68
+ This replaces "in v1 a team has at most one sandbox, so the two coincide" (decided
69
+ 2026-11-20 by both sides; the product owner's direction, and aweb's maintainers'
70
+ requirement of 2026-11-18).
71
+ - **The one-team limit is the v1 provider's, not the model's (r5).** The model admits
72
+ several teams in one sandbox, as co-resident trust the operator accepts. v1's
73
+ provider, teamctl, serves one team per sandbox, so in practice v1 still runs one
74
+ team per sandbox. That limit lifts when a provider serves several teams, and C1's
75
+ reference text and the release notes say so plainly (decided 2026-11-20).
76
+ - **`souls:` is the one declaration of a soul's team (r5).** Its `default` is the team
77
+ that soul's instances join, and its `teams` the others they may join. A pattern
78
+ entry sets them for a set of souls. A sandbox places souls and never changes their
79
+ team (decided 2026-11-20). Whether the key itself gets another name is a separate
80
+ question, outside this record.
81
+ - **Capabilities are derived from the souls, per soul (r5).** A sandbox admits each
82
+ listed soul's resolved composition at the lock's versions, less an optional
83
+ `excludeCapabilities`. Admission widens only when the operator applies a plan that
84
+ shows the change (C1, "The applied-plan gate"; decided 2026-11-20 by both sides).
85
+ - **Credential files are a bridge for the whole sandbox (r5).** v1 ships read-only
86
+ credential files mounted into the sandbox, because the first use has no other path
87
+ to its tokens. Every process in the sandbox can read them. Read-only stops writes,
88
+ not disclosure or use. A secret meant for one principal never goes through them
89
+ (Credentials; decided 2026-11-20, replacing "acceptable with one team per sandbox").
90
+ - **OATS does not create or delete machines in v1.** Sync builds and starts listed
91
+ sandboxes on a machine that already exists. Creating machines comes later, as a
92
+ provider capability (decided 2026-11-19).
93
+ - **Kubernetes is a provider option (r5).** C4 is the contract a Kubernetes provider
94
+ implements, as Compose through teamctl does. Its qualification and release scope
95
+ are decided separately (decided 2026-11-20).
96
+ - **Both broker contracts are designed in this effort**: one for secrets, one for
97
+ connectors (decided 2026-11-18). The connector broker stays designed only, with no
98
+ build and no verb until a real provider exists (decided 2026-11-20).
99
+ - **Messaging isolation is by server, when a workload wants it:** an isolated team gets
100
+ its own aweb server with federation outbound off. This needs no aw contract change
101
+ (decided 2026-11-17). It's a policy chosen for that workload (the ingestors), not a
102
+ consequence of placement (r5).
103
+ - **Kept as they are:** the word "team"; the schedule file, with `runsOn` naming the
104
+ machine and no lease; there is no workspace list of shared deployments. A sandbox
105
+ now lists its own souls; only the earlier "automatic team" stays rejected (r5).
106
+
107
+ ## What exists today, and what this builds on
108
+
109
+ - `container/agent` is one team's container. It runs every agent, sshd, the wake
110
+ broker and `oats host run` as one user, with its own OATS deployment at
111
+ `/state/deploy`, reached from the host as an OATS server over SSH
112
+ ([container.md](../container.md)).
113
+ - Its egress component has five base roles (aweb, registry, secrets, logs, signer), of
114
+ which a policy may declare a subset (#1955); teamctl's profile declares four of them
115
+ (all but signer). It adds two optional external roles, `source` (`https://github.com`)
116
+ and `model` (`https://api.anthropic.com`). It does not take arbitrary origins
117
+ ([egress README](../../container/agent/egress/README.md)). The Compose boundary probe
118
+ takes a `namePrefix` and reports `--json` receipts (#1958).
119
+ - aweb's team bundle, `deploy/team` (`teamctl`, aweb's maintainers), renders one
120
+ `deployment.yaml` into an aweb server, the egress proxy and the agent container. It
121
+ sets `AWEB_FEDERATION_OUTBOUND` to `off` by default. `teamctl start` probes the
122
+ boundary, brings up the agent, and exits 3 on purpose with the agents held: it admits
123
+ no seat.
124
+ - Seats: today a container agent takes a retained seat (`identity.source`) that the
125
+ operator provisioned. oats.aweb mints an instance's identity with
126
+ `aw init --join-from <root> --join-team <team>`, which works only where the team key
127
+ is, and at retire it prints `aw id team remove-member` rather than running it.
128
+ - The kernel has no Docker code, and must not gain any: provider behaviour belongs in a
129
+ capability.
130
+ - `oats-workspace.yaml` and `oats-local.yaml` are closed schemas. An older kernel
131
+ refuses a new root key with `E_WORKSPACE_SCHEMA` and, for the workspace file, an
132
+ "upgrade OATS" hint.
133
+ - A `run: spawn` schedule spawns on the host its `runsOn` matches (`host.name`). A
134
+ remote spawn (`--server`) runs preview and apply on the server's kernel, and the home
135
+ lives there.
136
+
137
+ ## The design
138
+
139
+ ### Five independent decisions (r5)
140
+
141
+ | Question | Who decides, and how |
142
+ | --- | --- |
143
+ | What runs where? | The shared workspace names sandboxes and the souls each may run; the capabilities admitted for each soul are derived from its resolved composition, less any exclusions, and widen only through an applied plan. A machine's local file selects which declared sandboxes it runs, and nothing else. A spawn or a schedule selects a soul; if the soul is placed, it resolves to an eligible sandbox (C2). |
144
+ | What does the runtime isolate? | Each sandbox has its own name, workload, private state, and declared egress and mounts. Several sandboxes may run on one machine. Agents that share readable state, credential files or a process trust boundary are mutually trusted. |
145
+ | Who can communicate? | aweb team membership, service routes, and contact, inbound and federation policy. A sandbox needs egress to a service to reach it. Sharing a sandbox joins no team. Sharing a team neither colocates agents nor gives them each other's local state. |
146
+ | Who is acting? | The identity provider binds each instance to an authenticated principal, from that instance's identity configuration, resolved per instance. Its messaging context, the team it joins, is resolved separately, from `souls:` and the documented fallbacks. Neither comes from its sandbox. |
147
+ | What can the actor do? | The resource's owner grants operations, to a team or to a long-lived principal, and the broker or provider checks them at use. Placement, a capability, membership or an address grants nothing on its own. |
148
+
149
+ One team per sandbox is a useful starting layout, and tooling may generate it as
150
+ explicit placement. The contract admits the same team in several sandboxes, and
151
+ several teams in one sandbox when the operator accepts that they share one trust
152
+ boundary, subject to each sandbox's egress and the owners' grants. v1's provider
153
+ limits this (C8, "One served team"). The ingestors are the case of a separate sandbox
154
+ combined with a separate team, server and federation policy, chosen for that workload.
155
+
156
+ **The case a reader can test (r5).** A reviewer and a deployer are in one team and
157
+ placed in two sandboxes. They exchange the messages aweb allows. Each keeps its own
158
+ state, session material and mounts. The reviewer can't use the deployment
159
+ credential, and revoking the deploy grant stops the next deployment without moving
160
+ either agent. The Acceptance section pins this.
161
+
162
+ ### Who does what
163
+
164
+ | Piece | Owner | Does |
165
+ | --- | --- | --- |
166
+ | 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. |
167
+ | 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. |
168
+ | 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). |
169
+ | The agent image and Compose | `container/agent` (lane:juan) | A read-only credential mount fragment (C8). |
170
+
171
+ ### Placement
172
+
173
+ A soul runs in sandbox S when S's `souls` lists it (C1), S is selected for the spawn
174
+ (C2), and this host lists S. Otherwise, a soul that no sandbox lists runs on the host,
175
+ as today, apart from `E_SANDBOX_HOST_AGENT` (C10). Placement never follows a team, and
176
+ a machine's local file never moves a soul: it only chooses which declared sandboxes
177
+ the machine runs (r5, replacing the derived rule "a soul runs in S when its resolved
178
+ default team is S's team").
179
+
180
+ - On a host that lists the selected sandbox S and has it started, a spawn (by hand, or
181
+ by a schedule tick) is routed into S, as a remote spawn through S's server
182
+ registration. S1 builds on #1912's floor (lane:juan; its hold is lifted, and it is not yet merged): the task goes on stdin,
183
+ the apply is bound to its preview and keyed, and a host below 0.69.15 is refused.
184
+ This costs nothing, because the sandbox's kernel must already be the release with
185
+ `sandboxes`. S1 does not merge before #1912. If #1912 is withdrawn, S1 itself
186
+ requires the same three properties of the sandbox's kernel, rather than relying on
187
+ today's fallbacks.
188
+ - On a host that does not list S, the spawn is refused with `E_SANDBOX_NOT_HERE`,
189
+ naming S and the local key that would list it. A placed soul never falls back to
190
+ the host.
191
+ - **After placement, the provider checks it can serve the instance's messaging
192
+ context (r5).** Once the workspace's placement has selected S, the provider checks
193
+ that it can serve the team the instance joins (C6, C8). A context it can't serve
194
+ fails with a remedy. It never routes the spawn to another sandbox, changes the
195
+ agent's team or falls back to the host.
196
+ - Inside S, its deployment refuses a spawn of any soul S does not list, and a routed
197
+ request that names another sandbox (`E_SANDBOX_PLACEMENT`, C3b).
198
+
199
+ ### The clock
200
+
201
+ There is one clock per machine, and it is the host's. A schedule runs on the host its
202
+ `runsOn` names, and its spawn is routed into the sandbox. The in-sandbox deployment
203
+ registers no deployment for ticking, so its `oats host run` keeps only the resume sweep
204
+ and the ordered stop, and ticks nothing. This replaces the container's clock; it does
205
+ not add a second one.
206
+
207
+ ### Identities
208
+
209
+ Every instance in a sandbox has its own identity, minted on the host at spawn and
210
+ removed at retire. The team's controller key and team key stay on the host, under the
211
+ operator's account, and never enter the container.
212
+
213
+ **Whose identity (r5).** The seat binds the instance's own identity kind and messaging
214
+ context, resolved per instance, never from the sandbox's name, a team label or an
215
+ alias. In v1 the one kind a sandbox takes is a local member seat. Its team T is the
216
+ team the instance joins: its soul's resolved default (`souls:`, or the fallbacks
217
+ workspaces.md gives). The kernel resolves T and hands it to the provider in the seat
218
+ plan and the `seat` act (C4). Two kinds stay out of sandboxes in v1, each refused
219
+ before anything is minted, with a remedy:
220
+
221
+ - **Extra teams** (`join-not-seated`): a join mints a per-team identity from that
222
+ team's root, and no root enters a sandbox. So a spawn into a sandbox joins its
223
+ default team only. Seats for extra teams are a later layout.
224
+ - **A resident's grant seat** (`grant-seat-not-sandboxable`): a grant seat calls the
225
+ resident's custody service over a host-local Unix socket while it runs, not only at
226
+ mint (oats-aweb's resident and grant-seat docs). That socket must never enter a
227
+ sandbox, because it serves the resident's root key. A soul whose identity
228
+ configuration makes it a grant seat is refused in a sandbox until a qualified,
229
+ revocable remote delegation exists, which is aweb's to design. There is no
230
+ downgrade from resident to local.
231
+
232
+ 1. Before routing the spawn, the provider mints the instance's identity on the host
233
+ from the host's root for the instance's team (`roots[T]`), into a private staging
234
+ directory. Where that team's registry is private, the host deployment sets
235
+ `settings.oats.aweb.registry` for the mint (C3).
236
+ 2. It delivers the identity's authority files (the same list retained seats copy
237
+ today) and a seat descriptor into the sandbox's state, at
238
+ `/state/seats/<seat-id>/`, and deletes the staging copy. The seat ID is derived from
239
+ the routed spawn's idempotency key, so a seat directory names one spawn, never an
240
+ instance name that can be reused (r2).
241
+ 3. The remote spawn takes that seat as a one-use seat (C6). The agent's own private key
242
+ is then inside the container, which is what aweb's answer requires: there is no
243
+ alternative short of a grant home, and that route is untested.
244
+ 4. At retire, the routed retire removes the home and releases the seat. The provider
245
+ then runs `aw id team remove-member` on the host, where the controller key is,
246
+ instead of printing it.
247
+
248
+ The exact order of a routed spawn, with the value each step binds (r2, r3):
249
+
250
+ 1. The kernel makes the spawn's idempotency key (`spawnKey`) and asks the provider for
251
+ a seat plan (`plan`, target `seat`, with `instance: {soul, spawnKey, team}`, where
252
+ `team` is T, r5). The plan is read-only and needs no instance name: it answers the
253
+ seat ID (derived from `spawnKey`), its path and the `spawnProvider` options, or
254
+ refuses a team it can't serve (C8, `team-not-served`). Its `planRevision` fences the
255
+ sandbox's provider state, `spawnKey` and T.
256
+ 2. The kernel runs the remote preview **with those options**, and with
257
+ `--sandbox <S>`, the same selector as the outer spawn, naming the sandbox the host
258
+ placed it in (r5). The in-sandbox kernel compares it with its `self` (C3b), and a
259
+ different sandbox refuses at the preview with `wrong-sandbox`, before anything is
260
+ kept or minted. The selector is part of the decision, so `D` binds it, and the
261
+ apply carries the same `--sandbox <S>` from the kept request. The preview chooses the
262
+ instance name when the caller gave none (a schedule passes `--purpose`, not
263
+ `--name`), and answers `decision.revision`, `D`, the hash of the whole decision
264
+ that the apply's `--expect-decision` must match, as #1912 requires. The in-sandbox
265
+ kernel admits a preview that carries a seat option without reading the seat; only
266
+ an apply needs it.
267
+ **The admission check (r5).** The preview's answer lists the composition the apply
268
+ will materialize: each module with its resolved id and source. `D` binds that
269
+ composition, because the apply's `--expect-decision D` refuses any other
270
+ (`E_DECISION_STALE`). So `D` is the gate's carrier into the sandbox, and the
271
+ in-sandbox kernel needs no new input. Before step 3, the host compares that
272
+ composition with the recorded admission entry for this sandbox and soul (C1, "The
273
+ applied-plan gate"), and with the current `excludeCapabilities`. A capability or a
274
+ source outside the entry refuses (`capability-not-applied`), an excluded one refuses
275
+ (`capability-excluded`), and nothing is kept, minted or applied.
276
+ 3. **Before anything is minted, the kernel keeps the whole routed request** (r3,
277
+ contract): server, `spawnKey`, `D`, the composition `D` binds and the revision of
278
+ the recorded entry it was checked against (r5), the exact argv and provider options, and the
279
+ task text, in `~/.oats/remote/<server>/pending/<spawnKey>.json` (0600, under the
280
+ operator account, beside today's remote snapshots). It holds the task text, which
281
+ #1912 took off argv for a reason, so: it is removed as soon as its seat settles
282
+ (bound, released, or refused terminally); it is never copied into a receipt, a log
283
+ or the ledger; and readiness reports one older than 24 hours as
284
+ `sandbox-pending-stale`, naming the spawn key, never the task. S1 pins a test that
285
+ its content never reaches a receipt, a log or a readiness line.
286
+ 4. The kernel runs `seat` with the plan's revision, `spawnKey` and
287
+ `instance: {name, soul, spawnKey, team, decision: D, settings}`. `settings` is the preview's
288
+ composed settings for the capability the seat plan named
289
+ (`spawnProvider.capability`), passed through unread, so the provider can refuse a
290
+ seat it must not mint (C6, r5). The name, `D` and `settings` are inputs to the mint,
291
+ not part of the plan's revision. The provider writes the ledger entry (`minting`, with
292
+ `spawnKey`, `D`, T, the alias it will mint and the seat ID) before it mints, mints,
293
+ records the certificate ID, delivers, and moves the entry to `delivered`.
294
+ 5. The kernel runs the remote apply with `--expect-decision D` and
295
+ `--idempotency-key spawnKey`, from the kept request, with the same provider options
296
+ as the preview. No provider input changes between 2 and 5.
297
+ - **The request's in-flight lock (r5).** From step 3 until its seat settles in step 6,
298
+ the spawn holds an exclusive lock on its kept request. A reconcile skips a request
299
+ whose lock is held (`held-in-flight`), and replays or binds nothing for it. A lock
300
+ whose holder is gone is taken over, and its request is replayable again.
301
+ - **The apply-time admission fence (r5).** Under that lock, immediately before it
302
+ sends the apply, the host recomputes the admission inputs: the workspace's commit
303
+ and lock, the exclusions, and the recorded entry for this sandbox and soul. It
304
+ then rechecks the composition `D` binds against them. `D` fingerprints the
305
+ composition, not workspace policy, so this recheck is what catches an exclusion
306
+ committed between the seat and the apply.
307
+ - **When the fence refuses** (`capability-excluded` or `capability-not-applied`),
308
+ the apply is not sent. The kept request records every send durably before it's
309
+ made, so one with no recorded send, refused here under its lock, is proof that no
310
+ apply carrying `spawnKey` was ever sent. `bind` then gets that proof in place of an
311
+ answer (step 6).
312
+ - **Later edits:** an exclusion committed after this check applies to the next
313
+ spawn, as it does to a home already running.
314
+ 6. The kernel passes the apply's own answer to the provider (`bind`, C4), which acts
315
+ on it by this table (r4, contract):
316
+
317
+ | The apply's answer | Evidence | The seat |
318
+ | --- | --- | --- |
319
+ | 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` |
320
+ | `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`) |
321
+ | No apply sent: `{sent: false, code}`, from the admission fence, for a request with no recorded send (r5) | the host refused under the request's lock before any apply carrying `spawnKey` was made, and the request is deleted once the seat is released, so no home can hold the seat | released (`spawn-failed`) |
322
+ | `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`) |
323
+ | `E_IDEMPOTENCY_CONFLICT` (r4d) | a home already holds `spawnKey` under another decision and may hold the seat | stays `delivered` |
324
+ | `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` |
325
+
326
+ A seat is released only on proof that no home can hold it (r4d): releasing revokes
327
+ the member, which is right for a seat that no home holds, used or not, and wrong
328
+ for one a live home holds. Before such a release the provider deletes any copy at
329
+ `/state/seats/<seat-id>/` through the server route. If that deletion cannot be
330
+ confirmed, the entry stays `delivered`, the kept request is deleted (its refusal
331
+ was terminal), and readiness reports `sandbox-seat-unsettled`. The server route's
332
+ "copy deleted" answer comes from the sandbox, so it is untrusted input: it can
333
+ release only a seat of that sandbox's own ledger, and a false "deleted" can at
334
+ worst revoke that sandbox's own member, never another's (r4d). `ok: false` alone is
335
+ never evidence, and the provider reads no field of a refusal beyond its code and
336
+ `unconfirmed`. S1 pins that the routed apply's answer, and its keyed replay, carry
337
+ the new home's `capabilityMeta`; that the routed answer carries the host's refusal
338
+ code and its `unconfirmed` detail unchanged; that `E_DECISION_STALE` is raised
339
+ only when no home holds the key, before any placement or hook; and that a required
340
+ hook's failure carries `unconfirmed: true` whenever the rollback could not confirm
341
+ the home gone. S2 pins the meta oats.aweb writes and a `bind` test per row,
342
+ including a prior home holding the key under another decision
343
+ (`E_IDEMPOTENCY_CONFLICT`: the member is kept) and a failed copy deletion.
344
+ 7. **The kernel settles a `delivered` seat** (r3, r4): `oats sandbox reconcile`, and
345
+ so sync, first runs the provider's `reconcile` act, which settles interrupted mints
346
+ and deliveries (below) and answers the ledger's seats. Only then does it replay a
347
+ kept request, and only one whose ledger entry that answer shows durably
348
+ `delivered`: a kept request whose entry is `minting` or `mint-uncertain` is never
349
+ applied or replayed, and one whose seat was released is deleted. Each replay is
350
+ unchanged, keyed by its `spawnKey`, and its answer goes to `bind` as in 6. A replay of an apply that was
351
+ never sent is that apply, with its task, and a stale `D` refuses it terminally.
352
+ Before each replay, the host runs step 5's admission fence under the request's
353
+ lock (r5). The recorded entry only widens or replaces a capability's source, so a source
354
+ replaced since, or an exclusion added since, can refuse the replay. A request with no recorded send that the fence refuses settles as in
355
+ step 6 ("No apply sent"). A replay of a request that was sent before, and fails the
356
+ fence, is not sent. Its request is kept and reported (`held-not-admitted`), and
357
+ its seat stays `delivered` (readiness, `sandbox-seat-unsettled`), because an
358
+ earlier send may have made a home that holds it. The
359
+ provider never builds or replays a spawn itself. Absence of the instance's name, or
360
+ an unused seat directory, is never evidence. A `delivered` seat with no kept request
361
+ stays `delivered`, and readiness reports `sandbox-seat-unsettled`.
362
+
363
+ **A mint whose outcome is uncertain (r3, contract).** An entry found in `minting` was
364
+ interrupted, and the registry may hold an identity whose result was never recorded, or
365
+ a seat copy may already have landed in the sandbox before the `delivered` write (r4).
366
+ The next mutating act reads the certificate ID from the staging copy, if one is there,
367
+ into the entry before it deletes that copy, and moves the entry to `mint-uncertain`.
368
+ With a certificate ID, it first deletes any copy at `/state/seats/<seat-id>/` through
369
+ the server route, then releases the seat (reason `spawn-failed`): no apply was sent
370
+ for it, because the apply follows the `delivered` write and its kept request is
371
+ fenced (step 7). If that copy cannot be confirmed deleted, the entry stays
372
+ `mint-uncertain` and is reported as unsettled. A pinned test kills the provider
373
+ between the copy landing and the `delivered` write, then runs reconcile and an
374
+ otherwise no-op sync: no home is created, the copy is gone and the member is
375
+ removed. Without one, the entry stays `mint-uncertain`, readiness
376
+ reports `sandbox-seat-unsettled` naming the alias, and the operator checks the team's
377
+ members. A replay of that `seat` key answers `unknown` and never mints again. A test
378
+ pins a kill after registration and before the receipt.
379
+
380
+ ### Lifecycle calls made inside a sandbox (r1)
381
+
382
+ Minting and removing identities need the host's keys, so in v1 the host is the only
383
+ place a sandboxed instance is spawned from, and the host finishes every retire:
384
+
385
+ - **Spawn inside the sandbox.** The in-sandbox deployment has no root for any team.
386
+ Its kernel accepts a spawn only when it carries a host-delivered seat (the routed
387
+ spawn's `identity.seat`, C4 and C6). Any other spawn there, by an agent or by hand,
388
+ is refused with `E_SANDBOX_PLACEMENT`, reason `spawn-from-host`, whose remedy is to
389
+ spawn from the host. A sandboxed agent that needs a helper asks for one; it cannot
390
+ start one.
391
+ - **Retire inside the sandbox** (`oats retire --self`, or a retire run there by hand)
392
+ works as today: the home goes, and oats.aweb prints the `remove-member` command it
393
+ cannot run. The host completes it through the provider's `reconcile` act (C4), which
394
+ `oats sandbox start` and sync run for each listed sandbox, under the sandbox's lock.
395
+ `status` only observes (r2).
396
+ - **The sandbox's report is untrusted input.** Reconcile reads the sandbox's instances
397
+ through the server route, and that report comes from inside the boundary. So it can
398
+ only move seats of that sandbox's own ledger toward `released`, and it triggers no
399
+ other act. A seat is released by reconcile only when all of these hold: its entry is
400
+ `active` (never `minting`, `delivered` or `removal-uncertain`), the report lists no
401
+ home holding its seat ID, and its seat directory is gone. The release's receipt
402
+ records that the sandbox's report drove it (reason `reconcile`), so it can be told
403
+ from a retire's removal. A test pins that a report naming a seat of another
404
+ sandbox, or an unknown certificate, changes nothing.
405
+ - **Retire from the host** (`oats retire <name> --server sandbox-<name>`, or the
406
+ kernel routing a retire of a sandboxed instance) runs the remote retire, then the
407
+ provider's `release` act (C4) for that seat at once (reason `retired`).
408
+ - **The ledger** lives in the provider's state on the host, scoped to the deployment
409
+ (C7): `~/.oats/sandboxes/<deployment-key>/<sandbox>/seats.json`, one entry per seat:
410
+ seat ID, `spawnKey`, `D`, instance, alias, certificate ID, team, state (`minting`,
411
+ `mint-uncertain`, `delivered`, `active`, `removing`, `released`,
412
+ `removal-uncertain`), and the receipt
413
+ of each step. It outlives the remote home, and is the only evidence
414
+ `remove-member` acts on.
415
+ - **Removal is written before it runs (r2).** The provider moves an entry to
416
+ `removing`, durably, before it calls `remove-member`, then to `released` or
417
+ `removal-uncertain` with the receipt. An entry found in `removing` was interrupted:
418
+ it becomes `removal-uncertain`, and is never removed again automatically (C6).
419
+ - **Compensation.** If the mint succeeds but delivery fails, the provider releases
420
+ the seat at once (reason `spawn-failed`) and deletes any delivered copy. After
421
+ delivery, only step 6 or 7 above settles the seat.
422
+
423
+ ### Credentials (v1)
424
+
425
+ **Two routes, with different scopes (r5).**
426
+
427
+ - **The credential files are a bridge whose scope is the whole sandbox.** The
428
+ sandbox's reviewed entry in `oats-workspace.yaml`, `sandboxes.<id>.credentials`
429
+ (C1), is the explicit approval: committing it approves exposing each named file to
430
+ everything in that sandbox. Every process in the sandbox can read the files.
431
+ Read-only stops writes, not disclosure or use. The bridge can never provide a
432
+ per-principal secret, and a secret meant for one principal never goes through it.
433
+ It ships in v1 because the first use, the knowledge ingestors, has no other path to
434
+ its tokens: they reach the okf capability only as file settings today.
435
+ - **A per-principal secret goes through aweb's Secrets,** designed while its provider
436
+ is pending:
437
+ - A per-principal Secrets grant authorizes a defined operation in its verified
438
+ team/installation context.
439
+ - The secret may enter the environment of the designated, isolated runner job for
440
+ that operation. Its value stays out of the agent's ordinary environment, shared
441
+ mounts, persistent runtime metadata and results.
442
+ - A value injected into an agent process is a disclosure to that process, and must
443
+ be treated according to the actual execution boundary.
444
+ - The reviewed workspace credential-file entry approves exposure to the whole
445
+ sandbox trust group, and cannot provide a per-principal secret.
446
+
447
+ The sandbox reaches Secrets through the egress base role `secrets`, which teamctl
448
+ already declares. Egress permits access to the service; it changes neither the
449
+ grants nor the runtime's disclosure boundary. Per-principal enforcement is marked
450
+ designed until the provider exists. When it's built, its acceptance covers
451
+ co-resident agents as well as separate sandboxes (aweb's Secrets design, §4.6 and
452
+ §9; its runner protocol, §4.4).
453
+ - **Per team:** a team's credentials are a sandbox's files in a sandbox whose souls are
454
+ all that team's, or a grant to a Secrets role the team's owner assigns. Neither
455
+ needs a new OATS key. Ordinary membership never grants use.
456
+
457
+ The workspace names a sandbox's credentials. The host's local file says where each
458
+ value is. The provider mounts each named file read-only at `/run/oats-credentials/<name>`
459
+ in that sandbox's agent container only. Nothing else gets a mount, and an undeclared or
460
+ missing credential refuses the start. A capability inside the sandbox reads a credential
461
+ through its own file setting (for example `settings.oats.okf.github-token-file`), which
462
+ the provider writes into the in-sandbox local file from the host's settings for that
463
+ sandbox.
464
+
465
+ **No other mount may expose them (r1, r2).** A credential source is a regular file,
466
+ read through its real path; a symlink is resolved, and one that leads to anything but
467
+ a regular file is refused (`E_SANDBOX_CREDENTIAL`, reason `not-a-file`). The bind
468
+ source is the resolved path. A credential source with more than one hard link is
469
+ refused too (reason `hardlinked`, r3, contract): a second link could sit inside another
470
+ sandbox's work directory, where no path check sees it. This applies to every source in
471
+ the host's `credentials`, used or not, at every sandbox's start; the container's own
472
+ acceptance already refuses a public CA with more than one link. A pinned test puts a
473
+ hard link of one sandbox's credential in another sandbox's work directory.
474
+
475
+ The provider derives a protected inventory, in two parts:
476
+
477
+ - **Hard-denied:** the host's team roots (`roots`), the seat staging directory, the
478
+ provider's own state (`~/.oats/sandboxes`) and the host deployment directory. No
479
+ bind may equal, contain or lie inside one of these, a declared credential included:
480
+ a credential source inside a team root is refused.
481
+ - **Credential sources:** every source in the host's `credentials`, whether a listed
482
+ sandbox declares it or not (an unused one, or one of a delisted sandbox, included),
483
+ and every other sandbox's state, work and mirror directories. Only the exact
484
+ read-only bind of a credential this sandbox declares, at
485
+ `/run/oats-credentials/<name>`, is excepted.
486
+
487
+ The check runs on **every bind of the real agent container**, before any agent runs
488
+ (r2): the provider renders the teamctl deployment and checks each agent bind source in
489
+ the rendered configuration (the state, work and mirror directories, the harness login
490
+ directory from `agents.secrets`, the authorized-keys file, and the credential binds),
491
+ then the container's own mount acceptance checks the started agent's actual mounts
492
+ against the same inventory before any seat is admitted (C8). Today's boundary probe
493
+ substitutes an empty login directory, so it cannot stand in for this check. The
494
+ started-agent check reads the agent container by its exact identity (the container ID
495
+ teamctl's start returned, or an ownership label as in #1958), never by name alone: a
496
+ same-named container that is not this sandbox's refuses admission (a pinned negative
497
+ in S2 and S3). A failing
498
+ bind refuses the start (`E_SANDBOX_MOUNT`, reason `overlap`, naming both paths), and so
499
+ do two sandboxes sharing any such directory. Pinned negative tests: a work or mirror
500
+ directory containing an unused credential; one containing a delisted sandbox's
501
+ credential; a harness login directory pointing at a team root.
502
+
503
+ **The first use's GitHub API route: the `forge` role (decided).** `source` admits
504
+ `https://github.com` only, and a knowledge proposer also calls `https://api.github.com`
505
+ (OKF's own setup check requires both). Both sides decided a third external role for
506
+ it:
507
+
508
+ - `forge` selects exactly `https://api.github.com`, defaults to false and, like the
509
+ other external roles, needs `egress.external.resolvers`. Its wrapper input is
510
+ `egress.external.forge` (teamctl's schema), its policy entry
511
+ `externalTargets.forge.origin`, and the component checks the exact origin again.
512
+ - **What it guarantees (r3, contract: corrects a decided item).** External roles are
513
+ TLS pass-through: the proxy routes on the SNI and never sees the encrypted
514
+ Host/`:authority` (egress README, "Optional external source and model roles").
515
+ So `forge`'s guarantee is the external roles' own: exact SNI `api.github.com` and a
516
+ validated public destination. The probe tests what the proxy enforces: an
517
+ unlisted SNI is refused, and `api.github.com` resolves only to the proxy. **The
518
+ risk that remains:** with SNI `api.github.com` admitted, the connection reaches
519
+ whatever GitHub's front end for that name serves to a Host it accepts; domain
520
+ fronting is not refused here. So the one-repository credential is the control that
521
+ matters. A Host
522
+ that differs from the SNI inside the encrypted stream, on a `forge` or another
523
+ admitted connection, is not refused by this component; whether GitHub serves it is
524
+ GitHub's. Refusing it would need TLS interception, which this record does not
525
+ propose. This statement replaced the earlier "SNI/Host mismatch" item; both sides
526
+ decided it in r3, with the risk statement above.
527
+ - The external-egress image test and the boundary probe name the hosts that stay
528
+ refused: `uploads.github.com`, `codeload.github.com`, `raw.githubusercontent.com`,
529
+ `objects.githubusercontent.com` and `gist.github.com`.
530
+ - **The credential is scoped to one repository, as a requirement.** With a token the
531
+ API can write, and the boundary limits services, not accounts. So the sandbox's
532
+ proposal credential (`knowledge-propose` in C1's example) must be scoped to the one
533
+ knowledge-base repository, as a push credential is today. The egress README's role
534
+ section, this section and the first use's setup steps all say so.
535
+ - C1's `egress` set becomes `{model, source, forge}`. `forge` has its own feature,
536
+ `sandbox-egress-forge`, because a kernel that already has `sandboxes` refuses the new
537
+ value through C1's closed set: a workspace uses `forge` only once every one of its
538
+ hosts lists that feature.
539
+ - Order: the egress component and teamctl first, on lane:juan (aweb's maintainers launch
540
+ that developer once this record is final); then C1's value, on the kernel side.
541
+
542
+ ### What sync does
543
+
544
+ After its current steps (the lock, package souls, the automation snapshot), `oats sync`
545
+ reconciles each sandbox the local file lists:
546
+
547
+ - not built, or built from other inputs: build and start it;
548
+ - stopped: start it;
549
+ - running with the same inputs: no infrastructure change (`action: "none"`).
550
+
551
+ Whatever the action, sync then reconciles each listed, running sandbox's seats
552
+ (`oats sandbox reconcile`'s work: the provider's `reconcile` act, then the replay of
553
+ each kept request whose entry it answers durably `delivered`, as in step 7 of the
554
+ Identities section) (r4d), so a self-retire is completed by the next sync even when nothing else changed
555
+ (r3). A pinned test: a self-retire, then an otherwise no-op sync, removes the member.
556
+
557
+ A sandbox declared in the workspace but not listed locally is never started. A sandbox
558
+ listed earlier and now delisted is stopped, never destroyed: its state and its
559
+ identities are kept. A later schedule tick whose spawn selects it is refused
560
+ (`E_SANDBOX_NOT_HERE`), and no provider receipt implies a retire or the removal of
561
+ compute (r5). The provider keeps the
562
+ last declaration it started each sandbox with in its own state, so a sandbox whose
563
+ workspace entry was removed together with its local listing is still stopped, from
564
+ that record (r1). `oats sync --plan` shows
565
+ these actions and performs none. A failed sandbox does not undo the lock. It is reported
566
+ in `problems`, and sync exits nonzero.
567
+
568
+ teamctl's exit 3 ("agents held") is the expected end of a start. The provider reports
569
+ it as `ready`: in this design seats are admitted per spawn, never at start.
570
+
571
+ ### Images
572
+
573
+ In v1 the agent and egress image digests are host facts in the teamctl deployment file.
574
+ teamctl already requires the digest form. The image is not yet published: the release
575
+ job is disabled pending the registry decision. Once the release lane publishes it, the
576
+ digest moves into the lock with the release. That is a lock format change, proposed
577
+ then, not here.
578
+
579
+ ## The contracts (decided)
580
+
581
+ ### C1. Workspace `sandboxes:` (new root key; r5)
582
+
583
+ ```yaml
584
+ teams:
585
+ eng: { team: "eng:example.org" }
586
+ ingest-team: { team: "ingest:example.org" }
587
+ defaultTeam: eng
588
+ souls: # the one declaration of each soul's team
589
+ "*": { default: eng } # default: the team this soul's instances join
590
+ knowledge/*: { default: ingest-team } # a pattern sets it for a set of souls
591
+ knowledge/knowledge-reviewer: { default: eng, teams: [ingest-team] } # a deliberate bridge
592
+ sandboxes:
593
+ ingest:
594
+ souls: [knowledge/knowledge-ingestor] # who may run here; never their team
595
+ excludeCapabilities: [acme-deploy] # optional: never admitted here
596
+ egress: [model, source, forge] # closed set, added to the base routes
597
+ credentials: [sources-read, knowledge-propose] # names only: a whole-sandbox bridge
598
+ description: Knowledge ingestors # optional
599
+ ```
600
+
601
+ - **The key** is the sandbox ID, matching `^[a-z0-9]$|^[a-z0-9][a-z0-9-]{0,30}[a-z0-9]$`.
602
+ Its storage, status, server registration and lifecycle are keyed by that ID and the
603
+ deployment, never by a team label, a team ID or an agent alias.
604
+ - **`souls`** (required, non-empty) is the workspace's placement allowlist, and the one
605
+ place it is declared. Each entry is an exact soul reference as `souls:` keys spell a
606
+ single soul (`<member>/<soul>` or `<package>/<soul>`), never a pattern. Entries are
607
+ distinct (`duplicate-entry`). It makes a soul eligible to run here, and spawns
608
+ nothing: spawns and schedules still decide which instances run. A soul may be listed
609
+ by several sandboxes; C2 says how a spawn chooses. A reference no member or package
610
+ offers is reported by readiness (`sandbox-soul-unknown`), and a spawn of it is
611
+ refused (`E_SANDBOX_PLACEMENT`, `soul-unknown`).
612
+ - **Capabilities are derived, per soul (r5).** For each soul a sandbox lists, the
613
+ admitted capabilities are that soul's fully resolved composition (workspace defaults,
614
+ the soul's own layer and required dependencies) at the lock's versions. Each one is
615
+ identified by its resolved id and its authorized source, a canonical member or a
616
+ package. Admission is per (sandbox, canonical soul): one soul never rides on a
617
+ capability admitted for another, and the sandbox-wide union is for display only.
618
+ Package integrity and member trust are unchanged, and the gate adds no per-commit
619
+ consent for member code.
620
+ - **`excludeCapabilities`** (optional) names capabilities never admitted in this
621
+ sandbox. A soul whose composition needs one is refused (`E_SANDBOX_PLACEMENT`,
622
+ `capability-excluded`, naming the capability and the soul), never trimmed. The remedy
623
+ is a workspace soul, or a variant of one, whose composition doesn't need it, or a
624
+ reviewed change to the exclusion. The image's contents and the egress are separate
625
+ limits, and choosing software grants nothing.
626
+ - **The sandbox provider is composed like any default (r5).** A capability in the
627
+ workspace's `defaults`, the sandbox provider included (C4), is part of every listed
628
+ soul's resolved composition, and it's admitted by the same rule as the rest. Nothing
629
+ removes it. Inside a sandbox its `sandbox` hook is simply never called: a deployment
630
+ with `sandbox: {self}` runs no sandboxes (C3b). A sandbox that wants to keep it out
631
+ excludes it, and a soul that needs it is then refused, never trimmed.
632
+ - **The applied-plan gate.** Before minting a seat or starting a session through spawn
633
+ or a schedule tick, the kernel compares the actual resolved composition to the last
634
+ successfully applied plan entry for this sandbox and soul. Missing admission, a new
635
+ capability or a changed capability source refuses with `E_SANDBOX_PLACEMENT`,
636
+ reason `capability-not-applied`, naming the soul, the sandbox, the applicable
637
+ capability and source, and how to review and apply the updated plan (`oats sync
638
+ --plan`, then `oats sync --admission-revision <revision>`). The routed apply rechecks
639
+ the recorded entry for this sandbox and soul against what it will materialize: the host checks the
640
+ composition `D` binds, after the remote preview and before anything is kept or
641
+ minted, and again before each replay (Identities, steps 2 and 7). An explicitly excluded capability refuses as
642
+ `capability-excluded`. Never strip a capability to make a spawn pass. Narrowing
643
+ within the approved set needs no additional apply, and does not edit the recorded
644
+ plan.
645
+ - Only a successful, operator-authorized apply of the plan revision that shows the
646
+ change widens admission. A plan-only run, a failed sync, a schedule tick or a
647
+ recovery never does.
648
+ - Sync's plan, and readiness, show each soul's additions and source changes before
649
+ they're applied. Sandbox status and readiness show the recorded set and the
650
+ current derived set.
651
+ - **The admission revision and its commit (r5).** `oats sync --plan` answers one
652
+ admission revision for the whole sync, with the per-soul changes it would admit,
653
+ grouped by sandbox (C5). The revision is one hash over the entire admission plan:
654
+ the workspace's commit and the lock sync would install (the plan's lock) and, for
655
+ every listed sandbox and soul, its derived
656
+ set (ids and sources), the exclusions and the currently recorded entry.
657
+ - **Widening:** only `oats sync --admission-revision <revision>` widens admission,
658
+ and only when its revision equals the one the current inputs give, checked
659
+ after sync's own lock step. An upstream
660
+ change anywhere in the plan after it was reviewed changes the revision, so the
661
+ apply refuses all admission for that sync (`E_PLAN_STALE`, with the fresh
662
+ `admissionRevision` and changes in its detail) and records nothing. The refusal
663
+ is reported once in the answer's top-level `problems`, the rest of the sync
664
+ goes on, and sync exits nonzero.
665
+ - **First admission.** A listed soul with no recorded entry is a change of its
666
+ own (`first: true`), whatever its derived set, the empty set included. A missing
667
+ entry and a recorded empty entry are different states: the first refuses every
668
+ spawn (`capability-not-applied`), and the second admits a composition with no
669
+ capabilities. The first reviewed apply writes the entry.
670
+ - **The commit point:** a sync that applies an admission revision writes, in one
671
+ atomic write under sync's own lock, only the entries whose changes are
672
+ non-empty: a first admission, an added capability or a changed source. Each such entry records its
673
+ recorded set plus the additions, with the source changes applied, and the
674
+ revision. A capability the soul no longer derives stays recorded, so if the
675
+ soul derives it again from the same source it is admitted without a new apply,
676
+ because it was reviewed once already; from another source it is a
677
+ `sourceChanged` and needs one. An entry with
678
+ no additions or source changes keeps its recorded set and revision, so
679
+ narrowing never edits the recorded plan. The write happens only when the whole
680
+ sync has succeeded, with no problem in any sandbox. A sync that fails
681
+ anywhere writes none. Its infrastructure changes stand, as they always have,
682
+ and a later sync with a fresh revision applies the admission. So when sandbox A
683
+ succeeds and sandbox B fails, A's admission isn't widened either.
684
+ - **The commit fence.** The rows written are the ones captured from the exact
685
+ plan whose revision matched, and they are never re-resolved for writing. Under
686
+ sync's lock, immediately before the write, the kernel recomputes the hashed
687
+ inputs and compares them with the plan's inputs as sync applied them. Sync's
688
+ own lock and package steps are not a change; an edit from outside sync is. If
689
+ any input changed that way while the sync ran (a member's composition, the
690
+ lock, an exclusion or this host's listing), the whole admission is refused as
691
+ `E_PLAN_STALE` and nothing is written. No newer or partly recomputed plan is ever
692
+ written under the earlier revision.
693
+ - **Where they live:** in the host deployment's own state, per sandbox and soul.
694
+ The in-sandbox kernel never reads them: the host checks them against what `D`
695
+ binds (Identities, step 2).
696
+ - **Sync without the flag** applies everything else and widens nothing. It reports
697
+ each pending change as a warning (readiness, `sandbox-admission-pending`).
698
+ Narrowing writes nothing.
699
+ - An unattended sync that applies its own plan would admit changes without review,
700
+ weakening the gate to "since the last apply". A deployment that wants the gate
701
+ keeps the apply operator-authorized.
702
+ - **No team (r5).** A sandbox has no `team` field. `souls:` is the one declaration of
703
+ each soul's team (Decided with the product owner), and placing a soul never changes
704
+ it. The `team` field of the earlier, unreleased shape is refused when the file is
705
+ read (`E_WORKSPACE_SCHEMA`, reason `sandbox-team-field`). The remedy names the
706
+ migration: the souls whose default team it was go in `souls`, under the same sandbox
707
+ ID. There's no silent inference from a team.
708
+ - **One served team, in v1 (r5).** The model admits several teams in one sandbox. v1's
709
+ provider, teamctl, serves one team per sandbox (C8), so in practice v1 runs one team
710
+ per sandbox. That's the provider's limit, not the model's, and it lifts when a
711
+ provider serves several teams. C1's reference text and the release notes say so.
712
+ - `egress` is a subset of `{model, source, forge}` (`forge` behind feature
713
+ `sandbox-egress-forge`), because those are the external roles the egress component
714
+ supports. Adding another destination is a change to the egress component, not a
715
+ free-form list.
716
+ - `credentials` names match `^[a-z0-9][a-z0-9-]{0,62}$`, and are distinct. Committing
717
+ them approves exposing each file to the whole sandbox (Credentials).
718
+ - `egress`, `credentials`, `excludeCapabilities` and `description` are optional; the
719
+ lists default to `[]`. A duplicate in any list is refused (reason `duplicate-entry`)
720
+ (r1).
721
+ - **A team not yet created (r2, r5).** A shared team may omit its provider id
722
+ (declared, not created). A soul whose team has none stays valid, so other hosts are
723
+ not refused. A routed spawn of it refuses (`E_SANDBOX_TEAM`, reason
724
+ `team-not-created`), and so does a start whose provider would serve that team (C8),
725
+ with the existing remedy: its owner runs `oats aweb setup`, then commits the id. The
726
+ id is never inferred from the label or an active team.
727
+ - It is closed (`additionalProperties: false`), like every workspace block. An older
728
+ kernel refuses the file with `E_WORKSPACE_SCHEMA` and its existing "upgrade OATS"
729
+ hint, which is the error that tells existing deployments what to do.
730
+ - **Adding it breaks every older host of the workspace, not only the sandbox host.**
731
+ Every host reads the shared file, so the first commit that adds `sandboxes:` makes
732
+ each host on an older kernel refuse the whole workspace. A workspace adds the block
733
+ only once every one of its hosts runs the release that has feature `sandboxes`. The
734
+ person who commits it checks that first: the kernel cannot see another person's host.
735
+ The release notes' Upgrade section and the reference page that owns the workspace
736
+ file ([workspaces.md](../workspaces.md)) both say this, and give the check:
737
+ `oats version --json` on each host lists `sandboxes`.
738
+ - Feature `sandboxes` in `oats version --json`.
739
+
740
+ ### C2. Choosing a sandbox (r5: replaces the team routes)
741
+
742
+ A soul's **eligible sandboxes** are the workspace's sandboxes whose `souls` lists it.
743
+ The choice is made from the shared workspace, at the spawn or the schedule, before
744
+ anything happens:
745
+
746
+ - **None:** the soul is a host soul. It runs on the host as today, apart from
747
+ `E_SANDBOX_HOST_AGENT` (C10).
748
+ - **Exactly one:** it's inferred.
749
+ - **More than one:** the spawn names its target. That's `oats spawn <soul> --sandbox
750
+ <id>`, and a `run: spawn` schedule's `sandbox: <id>` field, both new contracts (the
751
+ CLI, and the schedule file). A spawn without one is refused (`E_SANDBOX_PLACEMENT`,
752
+ reason `sandbox-ambiguous`, naming the candidates and the flag or field). It's
753
+ refused even when this host lists only one of the candidates: a local file never
754
+ chooses a placement.
755
+ - **A named target** that the workspace doesn't declare (`sandbox-unknown`), or that
756
+ doesn't list the soul (`sandbox-not-eligible`), is refused with
757
+ `E_SANDBOX_PLACEMENT`. Both remedies list the soul's eligible sandboxes and say to
758
+ name one of them. `sandbox-not-eligible` also says the soul can be added to that
759
+ sandbox's `souls` in the workspace, by a reviewed change. A target this host doesn't list is refused with
760
+ `E_SANDBOX_NOT_HERE`. Each refusal comes before any effect, and none falls back to
761
+ the host.
762
+ - `runsOn` still names the one machine that owns a schedule's clock. `sandbox:` names
763
+ only where its spawn runs.
764
+
765
+ **Withdrawn (r5).** C2's team routes go: `sandboxed-team-not-default`,
766
+ `sandboxed-team-by-wildcard`, `sandboxed-team-local`, `sandboxed-team-alias` and
767
+ `sandbox-team-taken`. So does the rule that `"any"` excludes sandboxed teams. They
768
+ existed only because placement followed the default team. Now a team reached through
769
+ a wildcard, an extra team or a local default places nothing, and an eligible extra
770
+ membership is never a way to a placement or a grant. Operators who want a narrower
771
+ communication policy configure it on the messaging service and in egress. Messages
772
+ aweb allows can carry data between sandboxes, so separate storage promises no data
773
+ isolation across a permitted conversation.
774
+
775
+ ### C3. `oats-local.yaml`: `sandboxes` and `credentials` (new root keys)
776
+
777
+ ```yaml
778
+ host: { name: cloud-1 }
779
+ sandboxes: [ingest] # the sandboxes this machine runs
780
+ credentials:
781
+ sources-read: { fromFile: /srv/oats-operator/credentials/sources-read }
782
+ knowledge-propose: { fromFile: /srv/oats-operator/credentials/knowledge-propose }
783
+ settings:
784
+ oats.aweb-sandbox:
785
+ sandboxes:
786
+ ingest:
787
+ deployment: /srv/oats-operator/ingest/deployment.yaml # teamctl host facts
788
+ settings:
789
+ oats.aweb: { registry: https://registry.example.org } # private registry only
790
+ oats.okf: { github-token-file: /run/oats-credentials/knowledge-propose }
791
+ oats.aweb: { registry: https://registry.example.org } # the host-side mint (C6)
792
+ ```
793
+
794
+ - `sandboxes` lists distinct names that the workspace declares. An unknown name is
795
+ refused (`E_WORKSPACE_SCHEMA`, reason `sandbox-unknown`), a duplicate likewise
796
+ (`duplicate-entry`), and so is a listed sandbox with no `host.name` (reason
797
+ `sandbox-host-name-required`) (r1). The list selects which sandboxes this machine
798
+ runs, and nothing else: it holds sandbox IDs and infrastructure facts only, and it
799
+ can't place, move or choose between souls (C2, r5).
800
+ - `credentials` uses the kernel's existing `fromFile` form. A listed sandbox whose
801
+ declared credential has no source here refuses its start, naming the credential.
802
+ - The teamctl file holds infrastructure only (images, network, ports, state directory,
803
+ limits). The provider refuses a file that sets a boundary field the workspace owns
804
+ (`team.id`, which v1's provider derives from the souls the sandbox lists (C8, r5); the role booleans `egress.external.source`, `.model` and `.forge`,
805
+ `aweb.federationOutbound`): boundaries are declared once. The refusal is
806
+ `E_SANDBOX_DEPLOYMENT`, reason `boundary-field`, naming the field (r1). The
807
+ resolvers the external roles need, `egress.external.resolvers`, are host
808
+ infrastructure and stay in the teamctl file; a sandbox whose workspace egress names
809
+ an external role and whose file gives no resolvers refuses its start (reason
810
+ `resolvers-required`) (r3, contract). The provider writes the role booleans from
811
+ the workspace. Example: `egress: { external: { resolvers: [1.1.1.1, 9.9.9.9] } }`
812
+ in the teamctl file, with C1's `egress: [model, source, forge]`.
813
+ - **A private registry.** oats.aweb refuses an ambient `AWID_REGISTRY_URL`
814
+ (awebai/oats-aweb#284), so where the instance's team's registry is private the setting
815
+ is written twice: `settings.oats.aweb.registry` on the host deployment, for the mint
816
+ and for `remove-member` (C6), and the same key in the sandbox's `settings`, which the
817
+ provider writes into the in-sandbox local file. Without the in-sandbox one, the
818
+ in-sandbox spawn refuses with `registry-setting-required`.
819
+
820
+ ### C3b. `oats-local.yaml` inside a sandbox: `sandbox: { self: <name> }` (new root key)
821
+
822
+ The provider writes it into the in-sandbox deployment's local file. It is a contract of
823
+ its own because a kernel reads it:
824
+
825
+ - `self` must name a sandbox the workspace declares. That deployment then spawns only
826
+ souls that sandbox's `souls` lists, with the capabilities admitted for them, and refuses
827
+ others with `E_SANDBOX_PLACEMENT`, reason `not-placed-here` (r5), whose remedy says
828
+ to spawn it from the host into a sandbox that lists it. A routed request must name
829
+ the sandbox, soul and composition its preview showed, and its sandbox must equal
830
+ `self`. The sandbox reaches the in-sandbox kernel as `--sandbox <S>` on both the
831
+ remote preview and the apply (Identities, step 2); a request carrying a seat option (a
832
+ routed request) without `--sandbox` is refused with `E_SANDBOX_PLACEMENT`,
833
+ `wrong-sandbox`, and `D` binds the selector. An ordinary local spawn without a host-delivered
834
+ seat is not subject to the routed selector check. It remains subject to the placement
835
+ check and to the host-delivered-seat requirement (Lifecycle calls made inside a
836
+ sandbox, `spawn-from-host`). One that names another sandbox is refused with `E_SANDBOX_PLACEMENT`,
837
+ reason `wrong-sandbox`, even when the soul is eligible in both. Its remedy says the
838
+ host routed it to the wrong registration, and to check the host's `sandbox-<name>`
839
+ server entry (C7). Nothing is spawned. `D`
840
+ already binds the composition, and the `self` check refuses a request that names
841
+ another sandbox. A request through the sandbox's own deployment can never place a
842
+ soul on the host or in another sandbox.
843
+ - It may not be combined with `sandboxes:` (a sandbox runs no sandboxes),
844
+ `credentials:` (credentials reach it as mounts only), local `teams:` or local
845
+ `defaultTeam`. Each combination is refused with `E_WORKSPACE_SCHEMA`, reason
846
+ `sandbox-self-conflict`.
847
+ - An older kernel refuses the key as unknown. That is why the agent image's kernel is
848
+ the release that has feature `sandboxes`.
849
+
850
+ ### C4. The kernel–provider hook: `sandbox`
851
+
852
+ A new capability hook event, `sandbox`.
853
+
854
+ **Which capability provides it (r1).** Sandbox acts run at deployment level, with no
855
+ soul. The candidates are the capabilities the workspace's `defaults` compose (the
856
+ same resolution a spawn uses, without a soul's layer) whose manifest declares the
857
+ `sandbox` hook. Exactly one must exist: none refuses any sandbox act with
858
+ `E_SANDBOX_PROVIDER`, reason `none`; two or more, reason `ambiguous`, naming them. Its
859
+ settings are its manifest defaults, then the workspace defaults, then the host's
860
+ `settings.<capability>` in `oats-local.yaml`, merged as for a spawn.
861
+
862
+ **The call.** The kernel runs the hook with `OATS_SANDBOX_ACT` set to `plan`, `start`,
863
+ `stop`, `status`, `reconcile`, `seat`, `bind` or `release`, one JSON request on stdin, and reads one JSON
864
+ answer on stdout. The kernel holds a per-sandbox lock around every act but `plan` and
865
+ `status`, so two mutating acts on one sandbox never run at once (a second gets
866
+ `E_LIFECYCLE_BUSY`). The lock, the plan revisions and the idempotency keys are all
867
+ scoped to the deployment and the sandbox (C7's deployment key) (r2). A
868
+ hook that exits nonzero, times out or prints anything but one valid answer is read as
869
+ `state: "unknown"` with problem `E_SANDBOX_PROVIDER`, reason `hook-failed`.
870
+
871
+ **Every request** carries:
872
+
873
+ ```json
874
+ {"sandboxApi":1,"act":"start","sandbox":"ingest","host":"cloud-1",
875
+ "souls":[{"soul":"knowledge/knowledge-ingestor",
876
+ "team":{"label":"ingest-team","id":"ingest:example.org"}}],
877
+ "excludeCapabilities":["acme-deploy"],
878
+ "egress":["model","source"],
879
+ "credentials":[{"name":"sources-read","path":"/srv/…"}],
880
+ "workspace":{"url":"…","commit":"…","lock":"<sha256>"}}
881
+ ```
882
+
883
+ There's no sandbox-wide `team` (r5). `souls` carries each listed soul with the team
884
+ its instances join, as the kernel resolved it from `souls:`, so a provider that serves
885
+ one team (C8) can check what it would serve. The kernel never derives an identity
886
+ from the sandbox's name, a team label or an alias.
887
+
888
+ and by act:
889
+
890
+ | Act | Extra request fields | Answer fields beyond the envelope |
891
+ | --- | --- | --- |
892
+ | `plan` | `target`: `start`, `stop`, `reconcile`, `seat`, `bind` or `release`; for target `seat`, `instance: {soul, spawnKey, team}` (r5); 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>}}` |
893
+ | `start`, `stop`, `reconcile` | `planRevision`, `idempotencyKey` | `server`; for `reconcile`, `seats` as in `status` |
894
+ | `status` | none | `server`, `seats: [{seatId, instance, alias, certificateId, team, state}]` |
895
+ | `seat` | `planRevision`, `idempotencyKey`, `instance: {name, soul, spawnKey, team, decision, settings}` (`decision` is `D`, the remote preview's `decision.revision`; `team` is the team the instance joins; `settings` is the preview's composed settings for the seat's capability, passed unread; r5) | `seat: {id, path, alias, certificateId, team}` |
896
+ | `bind` | `planRevision`, `idempotencyKey`, `instance: {name, spawnKey}`, `apply`: the routed apply's answer as the kernel received it, or `{sent: false, code}` when the admission fence refused a request with no recorded send (r5) | `seat: {id, certificateId, state}` |
897
+ | `release` | `planRevision`, `idempotencyKey`, `instance: {name, seatId}`, `reason`: `retired` or `spawn-failed` | `seat: {id, certificateId, state}` |
898
+
899
+ **The envelope** of every answer:
900
+
901
+ ```json
902
+ {"sandboxApi":1,"act":"…","state":"ready|stopped|absent|failed|unknown|stale",
903
+ "receipts":[{"step":"render|probe|start|register|deploy|mint|deliver|remove","ok":true,"detail":"…"}],
904
+ "problem":{"code":"…","reason":"…","message":"…","remedy":"…"}}
905
+ ```
906
+
907
+ - `plan` and `status` are read-only: they change no state, delete no staging and remove
908
+ no member (r2). Every other act mutates, and runs under the lock.
909
+ - `plan` is read-only. Its `planRevision` binds the request's inputs and the
910
+ provider's own state for that sandbox (and, for `seat` and `release`, that
911
+ instance's ledger entry).
912
+ - **The provider owns revisions and receipts.** It checks `planRevision` on every
913
+ act that carries one, and answers `state: "stale"` with a fresh plan in `plan`; the
914
+ kernel reports that as `E_PLAN_STALE` with the fresh plan, on the pattern of `oats
915
+ instance stop`. It keeps each `idempotencyKey`'s receipt in its state on the host,
916
+ and the same key replays that receipt and changes nothing.
917
+ - `seat` mints and delivers one instance's seat, in the order the Identities section
918
+ gives. A replay of its key returns the same seat, or `unknown`, and never mints a
919
+ second identity. The kernel passes the seat plan's `spawnProvider` to the final
920
+ preview and to the apply alike, as `--provider <capability> <key>=<value>`, one per
921
+ option, so the kernel names no messaging provider. Dotted keys nest, so oats.aweb
922
+ answers `{capability: "oats.aweb", options: {"identity.seat": "<path>"}}`, which sets
923
+ its `identity.seat` (C6) (r2).
924
+ - `bind` and `reconcile` settle seats as the Identities and Lifecycle sections say:
925
+ `bind` from the routed apply's answer or the kernel's keyed replay of it (for
926
+ `delivered` seats), `reconcile` from the sandbox's untrusted report (for `active`
927
+ seats) and the interrupted-mint rule. The provider runs no spawn. The
928
+ staging sweep for a killed hook runs in the mutating acts only: under the lock no
929
+ `seat` can be running, so any staging copy found is a leftover.
930
+ - An act whose outcome is uncertain answers `unknown`, never `ready`.
931
+
932
+ ### C5. CLI and JSON
933
+
934
+ - `oats sandbox status [--json]`, `oats sandbox start|stop <name> (--plan | --plan-revision <r> --idempotency-key <k>)`.
935
+ - `oats sandbox status --json` answers
936
+ `{sandboxApi:1, host, sandboxes:[{name, souls, excludeCapabilities, admission:[{soul, recorded:[{id, source}], current:[{id, source}]}], listedHere, state, server, egress, credentials:[{name, source:"present"|"missing"}], problems}]}`.
937
+ `admission` shows, per soul, the set the last applied plan recorded and the set
938
+ derived now. The sandbox-wide union is the client's to display.
939
+ A sandbox has no `team` (r5): what the sandbox allows (`souls`, `excludeCapabilities`, `admission`) is
940
+ shown apart from the team each instance actually joined, which is on its seat
941
+ (`seats[].team`). The answer's readers change with it (below).
942
+ - `oats spawn <soul> --sandbox <id>` selects among a soul's eligible sandboxes, and a
943
+ `run: spawn` schedule's `sandbox: <id>` does the same (C2, r5). Both are new
944
+ contracts. Inside a sandbox, the host's routed preview and apply carry the same
945
+ `--sandbox <S>`, which must equal `self` (C3b). `--sandbox` is refused together with `--server`, which names a target of
946
+ its own (`E_BAD_ARGS`). That refusal applies to the caller's argv; the routed
947
+ preview and apply run inside S with `--sandbox` and no `--server`.
948
+ - `oats sandbox start|stop <name> --plan --json` answers
949
+ `{sandboxApi:1, sandbox, act, planRevision, actions}`; the apply answers
950
+ `{sandboxApi:1, sandbox, act, state, server, receipts, problems}`, and a stale
951
+ revision refuses `E_PLAN_STALE` with the fresh plan in its detail (r1).
952
+ - `oats sync --json` gains `sandboxes` with the same entries plus `action`
953
+ (`build|start|stop|none`), and, in a plan, the admission it would apply: each
954
+ sandbox entry carries `admissionChanges: [{soul, first, added:[{id, source}], sourceChanged:[{id, from, to}]}]`
955
+ (`first: true` for a soul with no recorded entry, whose `added` is its whole derived
956
+ set, excluded capabilities omitted since they refuse at spawn regardless, possibly
957
+ empty),
958
+ and the answer carries one top-level `admissionRevision`, the hash of the whole
959
+ admission plan (C1) (r5). `oats sync --admission-revision <revision>` takes that one value and
960
+ applies all of it or none (C1, "The applied-plan gate"), and a sync without the
961
+ flag widens nothing. The fields are additive, so
962
+ `syncApi` stays 1; the flag is new.
963
+ - `oats status --json` gains `placement: {sandbox, seatId}` on each instance placed in
964
+ one; `seatId` is the seat its home took (r2).
965
+ - `oats sandbox status --json`'s entries also carry `seats` (as C4's `status`), and
966
+ `oats sandbox reconcile <name> (--plan | --plan-revision <r> --idempotency-key <k>)`
967
+ runs on its own what sync runs for each sandbox: the `reconcile` act, then the
968
+ replays of the kept requests whose entries it answers durably `delivered` (r2, r3,
969
+ r4d).
970
+ - **That these are additive must be shown, not assumed.** The readers of sync's answer
971
+ are `packages/desktop/server/workspace-sync.mjs`,
972
+ `packages/desktop/renderer/workspace-sync-view.mjs`,
973
+ `packages/client/deployment-data.mjs` and `packages/client/workspace-cli.mjs`. The
974
+ readers of the status answer are the client's roster readers and the warm reader. S1
975
+ lists every reader it finds, with file and line, and pins one test per reader feeding
976
+ it an answer with the new fields. If a reader refuses unknown fields, the change is
977
+ not additive: that answer's API version goes up, and the reader changes first, in its
978
+ own PR. The sandbox status answer had no released shape, so dropping `team` breaks
979
+ no release. The two client readers already merged for this effort (#2016, sync's
980
+ exit; #2021, a spawn refusal's words) read no `team`. S1 checks both against r5's
981
+ shape, including the new `E_SANDBOX_PLACEMENT` reasons (r5).
982
+
983
+ ### C6. oats.aweb settings and behaviour
984
+
985
+ - `identity.seat` (new): an absolute path to a one-use seat delivered by the host. The
986
+ spawn copies it the way it copies `identity.source`, takes no retained-seat lock, and
987
+ deletes the delivered copy after connecting. It is refused together with
988
+ `identity.source` and with global mode. A preview reads nothing from it; an apply
989
+ needs it.
990
+ - **The seat descriptor (r2).** The retained route reads its service from the
991
+ source's `workspace.yaml`, which is not an authority file. A delivered seat instead
992
+ carries `seat.json`, written by the host at mint:
993
+ `{seatApi:1, seatId, spawnKey, service, team, alias, certificateId}`, where `team` is
994
+ the team the instance joins and `service` is that team's aweb origin. That origin is
995
+ one the sandbox's egress `aweb` role admits, and in v1 it's the sandbox's own server
996
+ (C8, r5).
997
+ The spawn reads its service from that descriptor only, never from `OATS_AWEB_URL` or
998
+ a copied coordination workspace, and checks it: `team` equals the team the spawn
999
+ resolved, `alias` equals the instance name, `spawnKey` equals the apply's key, and
1000
+ `service` is a plain https origin. The apply's key reaches the spawn hook through a
1001
+ new, generic hook variable, `OATS_SPAWN_IDEMPOTENCY_KEY`, set by the kernel on a
1002
+ keyed apply and absent otherwise (r3, contract: the hook environment; S1 sets it and
1003
+ pins it, S2 consumes it). An unkeyed apply with `identity.seat` is refused (reason
1004
+ `seat-binding`, field `spawnKey`); the provider never takes the expected key from
1005
+ the descriptor it validates. A missing, malformed or contradictory descriptor
1006
+ refuses the spawn (reason `seat-binding`, naming the field). The host's registry pin
1007
+ is a separate setting (C3), never the service.
1008
+ - **Seats a sandbox doesn't take in v1 (r5),** refused by `seat` before anything is
1009
+ minted, from the `settings` it's handed (step 4):
1010
+ - A spawn into a sandbox that asks to join a team beyond its default (`join=`):
1011
+ `E_SANDBOX_PLACEMENT`, reason `join-not-seated`. The remedy says that extra-team
1012
+ seats are a later layout, and that the soul's other teams stay eligible on the host.
1013
+ - A soul whose identity settings make it a resident's grant seat:
1014
+ `E_SANDBOX_PLACEMENT`, reason `grant-seat-not-sandboxable`. The remedy says to run
1015
+ it on the host, or to remove it from the sandbox's `souls`, until a qualified
1016
+ remote delegation exists. There's no downgrade from resident to local.
1017
+ The provider removes only a membership it minted for a disposable seat and can prove
1018
+ it owns. Stop, restart and removing a sandbox never retire a resident or revoke its
1019
+ other memberships.
1020
+ - Retire, for an identity minted by the host for a sandbox: the host runs
1021
+ `aw id team remove-member` with the controller key it holds, and reports it, from
1022
+ the routed retire or from reconcile (the Lifecycle section). It
1023
+ removes by the certificate ID that the mint recorded, never by alias. It removes only
1024
+ an identity listed in the provider's ledger of seats this host minted for this
1025
+ sandbox. An identity it did not mint is never removed, and is reported instead. It
1026
+ uses the host's configured registry pin (`settings.oats.aweb.registry`, C3), and
1027
+ records its receipt in the retire's meta. A failure, or an outcome it cannot be sure
1028
+ of, keeps today's recorded command and warning, and is never retried automatically.
1029
+ - Between mint and delivery, the instance's private key sits in the host's staging
1030
+ directory (0700, under the operator account). `seat` deletes the staging copy on
1031
+ every path: success, a failed mint, a failed delivery, a timeout and an interrupted
1032
+ hook. The next mutating act (C4) finds and removes a copy left by a killed hook, and
1033
+ reports it; `status` only reports it (r2). One test per path pins this.
1034
+ - `oats.aweb-sandbox` (new capability, same package): its settings are
1035
+ `sandboxes.<name>.deployment` and `sandboxes.<name>.settings` (C3).
1036
+
1037
+ ### C7. The sandbox's server registration
1038
+
1039
+ The provider registers each started sandbox as server `sandbox-<name>`, using the
1040
+ existing Docker-context SSH relay from container.md.
1041
+
1042
+ - It uses only the fields `servers.json` accepts today (`sshHost`, `workspace`,
1043
+ `oatsPath`, `path`), so an older kernel still reads the file. Anything else the
1044
+ provider keeps goes in its own state, never in `servers.json`.
1045
+ - The `sshHost` alias lives in an OpenSSH file the provider owns,
1046
+ `~/.oats/sandboxes/ssh_config`, which holds the relay, the per-sandbox operator key
1047
+ it generates and the known-hosts file it provisions from the sandbox's host key. The
1048
+ operator adds one `Include` of that file to their own SSH configuration once. Readiness
1049
+ reports `sandbox-ssh-include-missing` until they have.
1050
+ - The `sandbox-` prefix is reserved. A new `oats server add|connect` with that prefix is
1051
+ refused (`E_SERVER_INVALID`, reason `reserved-prefix`). A `sandbox-*` server that is
1052
+ already registered is reported by `oats sandbox status`, not refused: refusing
1053
+ configuration that was accepted before would itself be a contract change. The provider
1054
+ will not adopt or overwrite it, and that sandbox's start refuses, naming the server
1055
+ (`E_SANDBOX_SERVER`, reason `server-taken`).
1056
+ - **Its own registration is not "already registered" (r1).** The provider records
1057
+ each registration it made in its state, with the `servers.json` entry it wrote. A
1058
+ `sandbox-<name>` server that matches its record is its own: a restart reuses it, and
1059
+ stop and delisting keep it and the record, so the sandbox can start again. Only a
1060
+ `sandbox-*` server with no matching record counts as taken.
1061
+ - **Scoped to the deployment (r2).** `servers.json`, the SSH file and the provider's
1062
+ state are per OS user, and two deployments of that user may each declare a sandbox
1063
+ of the same name. So the provider's state lives under a deployment key, the first 16
1064
+ hex digits of the SHA-256 of the host deployment directory's real path:
1065
+ `~/.oats/sandboxes/<deployment-key>/<sandbox>/`. The registration record names its
1066
+ deployment key. A `sandbox-<name>` server recorded for another deployment key is
1067
+ never reused, stopped or overwritten: this deployment's start refuses
1068
+ (`E_SANDBOX_SERVER`, reason `server-owned-elsewhere`, naming the other deployment
1069
+ directory). The public name stays `sandbox-<name>`.
1070
+ - **A moved deployment.** Moving or renaming the deployment directory changes its key
1071
+ and orphans its sandboxes' ledger, lock and receipts. Readiness reports
1072
+ `sandbox-state-orphaned` when provider state under another key holds a sandbox this
1073
+ deployment lists, naming the old key. It is never adopted automatically; the remedy
1074
+ names moving the directory back, or the manual adoption step S2 specifies.
1075
+
1076
+ ### C8. teamctl and the container (aweb's maintainers)
1077
+
1078
+ - **Credential mount:** a new teamctl input, `agents.credentials`, a map from name to a
1079
+ host file. It is rendered as read-only binds at `/run/oats-credentials/<name>` through a
1080
+ new `container/agent/compose.agent.credentials.yaml` fragment. teamctl's
1081
+ `agents.secrets` stays the harness login only.
1082
+ - **Probe:** the boundary probe asserts that each credential mount is read-only, that
1083
+ it lies only under `/run/oats-credentials`, and that no undeclared credential path is
1084
+ mounted. Its receipt joins the probe's `--json` receipts (#1958).
1085
+ - **Protected sources (r1, r2, r3):** the provider writes one JSON file per start,
1086
+ `{"protectedSourcesApi":1, "hardDenied":[<path>], "credentialSources":[<path>],
1087
+ "declaredBinds":[{"source":<path>,"target":"/run/oats-credentials/<name>"}]}`, with
1088
+ real paths, and gives it to teamctl as a new input, `agents.protectedSourcesFile`
1089
+ (contract: teamctl's schema, aweb's maintainers). teamctl passes it to the container's
1090
+ mount acceptance, which takes those three parts and, on the started
1091
+ agent's actual mounts, asserts that no bind equals, contains or lies inside a
1092
+ protected path, the declared credential binds being the only exception to the
1093
+ credential-source part. It runs before any seat is admitted.
1094
+ - **Optional, later:** a slimmer profile without Secrets and Logs. v1 runs with
1095
+ teamctl's four base routes.
1096
+ - teamctl's changes are these three inputs: `agents.credentials`,
1097
+ `agents.protectedSourcesFile` and `egress.external.forge`. OATS reads its exit codes
1098
+ as they are.
1099
+ - **One served team (r5): v1's provider limit, not the model's.** teamctl runs one
1100
+ team's bundle: its aweb server, egress and agent container. So `oats.aweb-sandbox`
1101
+ takes the bundle's team from the souls the sandbox lists (C4's request carries each
1102
+ one's team). It writes it as teamctl's `team.id`, which no host file may set (C3).
1103
+ - **What it refuses:** `oats sandbox start`, sync's start, the seat plan and `seat`
1104
+ refuse, before any seat, a sandbox whose souls join more than one team, or a team
1105
+ whose service isn't the bundle's: `E_SANDBOX_TEAM`, reason `team-not-served`. Each
1106
+ case has its own remedy, and neither changes a team or moves a spawn:
1107
+ - **Several teams:** the remedy names the teams found, and says to list the other
1108
+ team's souls in a sandbox of their own.
1109
+ - **Another service:** the remedy names the team's service and the bundle's
1110
+ server. It says to place that team's souls in a sandbox whose bundle serves that
1111
+ service, or to point this sandbox's bundle at it.
1112
+ - **What the limit covers:** only the combinations of membership inside one sandbox.
1113
+ Messaging between agents of one team in separately placed sandboxes stays
1114
+ governed by aweb's policy.
1115
+ - **A separate question:** whether teamctl can run two sandboxes for one team (two
1116
+ bundles, one team's server) is aweb's maintainers' to say. Until they do, the
1117
+ Acceptance case "same team, separate sandboxes" is pending for v1's provider.
1118
+ - A start never mints a team. The provider reaches only the service origins its plan
1119
+ names, with no ambient URL fallback. A runtime that can build only a team bundle
1120
+ reports that limit before it admits a seat, and never claims independent placement
1121
+ it can't deliver.
1122
+
1123
+ ### C9. Broker contracts (designed now, built against the first real provider)
1124
+
1125
+ **Authority (r5).** Both brokers check the verified actor, its acting team or
1126
+ installation context, the operation and resource it is authorized for, and its current
1127
+ grant or session scope, plus any approval required. They check at admission and again
1128
+ at dispatch, fail closed on missing, ambiguous, expired or revoked authority, and
1129
+ record the decision without returning a secret value.
1130
+ - **Scope:** team scope is a policy the owner authorizes within that team's
1131
+ installation. Identity scope is a grant to one stable principal, with any required
1132
+ team context still verified. A grant in one team can't be spent in another because
1133
+ the DID matches.
1134
+ - **Delegation:** asking a more privileged agent over messaging doesn't authorize it to
1135
+ act for the caller; an explicit delegation must cover the operation.
1136
+ - **Revocation and replacement:** revocation denies new dispatches at the applicable
1137
+ fence, though effects already dispatched may complete. Replacing a resident's
1138
+ runtime session keeps its principal without widening its authority.
1139
+ - **No fallback:** a missing broker or an unsupported provider is reported as
1140
+ unavailable, never replaced by a shared mounted file.
1141
+
1142
+ Both follow aweb's three rules. An agent never reads or exports a value. Approval is a
1143
+ state with a reference, and the same request is resubmitted under the same request ID.
1144
+ Authority, custody, approval, where execution happens, audit and withholding all stay
1145
+ with the provider. Inside a sandbox, an agent reaches a broker through the sandbox's
1146
+ egress routes only.
1147
+
1148
+ - **Secrets:** `oats credential list [--json]` shows only the names the caller is
1149
+ granted. `oats credential use <name> --action <action> --request-id <id> [--input-file <f>] --json`
1150
+ answers `{requestId, state: "done"|"awaiting-approval"|"refused"|"unknown"|"withheld", approvalRef?, result?}`.
1151
+ There is no verb that returns a value. A capability implements the contract through a
1152
+ `credential-broker` hook with the same request and answer.
1153
+ - **Connectors:** a sandbox may list `connectors: [<name>]` in C1, a later optional
1154
+ key. `oats connector call <name> <operation> --request-id <id> [--input-file <f>] --json`
1155
+ takes the same outcome states, through a `connector-broker` hook. aweb has no
1156
+ connectors broker built or filed, and whether one is planned is for aweb's maintainers to say. The
1157
+ shape is offered so that a provider-neutral gateway can implement it. It stays
1158
+ designed only, and is not built, until aweb's maintainers say whether aweb plans a connectors
1159
+ broker and a provider exists.
1160
+ - **Order:** both contracts are agreed in this record. Each is built when its first real
1161
+ provider ships, and checked against that provider's interface before it is released.
1162
+ This keeps the product owner's decision to design both now, and aweb's maintainers' point that a public
1163
+ contract must not take its shape from one unshipped product.
1164
+ - **What S4's spec settles before it is built (r1),** each a contract both sides
1165
+ agree: the `credential list` JSON and its hook request; how the broker capability
1166
+ is selected, and the no-provider refusal; how the caller and its grant are bound
1167
+ to a request; the scope of a request ID, and what a resubmission with the same ID
1168
+ but a different payload gets; and how `result` is kept free of secret values.
1169
+ Agreement on this outline is not permission for a provider to choose those.
1170
+ - **A change the provider forces is a contract decision.** If checking against the
1171
+ first real provider shows the agreed shape must change, the change goes back to both
1172
+ sides as a contract decision before it is built. It is never a doc edit.
1173
+
1174
+ ### C10. Readiness reports; the acts refuse
1175
+
1176
+ `oats readiness` reports, and refuses nothing. Its new items are:
1177
+
1178
+ - `sandbox-listed-not-running`;
1179
+ - `sandbox-credential-missing`;
1180
+ - `sandbox-host-agents`: a deployment that lists a sandbox has host-placed instances,
1181
+ running or stopped;
1182
+ - `sandbox-provider-missing`;
1183
+ - `sandbox-ssh-include-missing`;
1184
+ - `sandbox-seat-unsettled`: a `mint-uncertain` seat, with or without a certificate
1185
+ ID (r4d: one whose delivered copy could not be confirmed deleted stays here); a
1186
+ `delivered` seat with no kept request, including one whose release waits on a copy
1187
+ deletion that could not be confirmed; or a `delivered` seat whose last replay
1188
+ answered `E_IDEMPOTENCY_CONFLICT` or `E_SPAWN_INCOMPLETE` (r2, r3, r4d); or a
1189
+ `delivered` seat whose kept request was sent before and is now `held-not-admitted`
1190
+ (r5). A pinned
1191
+ negative: a known certificate ID whose copy deletion fails gives no replay, no home,
1192
+ and this item;
1193
+ - `sandbox-state-orphaned`: provider state under another deployment key for a
1194
+ sandbox this deployment lists (r2);
1195
+ - `sandbox-pending-stale`: a kept routed request older than 24 hours, named by its
1196
+ spawn key, never its task (r3);
1197
+ - `sandbox-soul-unknown`: a sandbox's `souls` names a soul no member or package
1198
+ offers (r5);
1199
+ - `sandbox-admission-pending`: a listed soul with no recorded entry yet, or one whose
1200
+ current derived capabilities add a capability, or change one's source, beyond the
1201
+ last applied plan, with the first admission, additions and changes listed (r5).
1202
+
1203
+ The refusals belong to the acts:
1204
+
1205
+ | Condition | Refused by | Code |
1206
+ | --- | --- | --- |
1207
+ | Listed sandbox, no provider | `oats sandbox start`, sync's start, a routed spawn | `E_SANDBOX_PROVIDER` |
1208
+ | A declared credential with no source, or a missing source file | `oats sandbox start`, sync's start | `E_SANDBOX_CREDENTIAL` |
1209
+ | A host-placed spawn in a deployment that lists a sandbox | `oats spawn`, a schedule's spawn | `E_SANDBOX_HOST_AGENT` |
1210
+ | Starting, restarting or resuming a host-placed home there (r1) | `oats session start`, the resume sweep | `E_SANDBOX_HOST_AGENT` |
1211
+ | A running or unreadable host-placed home when a sandbox starts (r1) | `oats sandbox start`, sync's start | `E_SANDBOX_HOST_AGENT` |
1212
+ | A spawn inside a sandbox without a host-delivered seat (r1) | the in-sandbox `oats spawn` | `E_SANDBOX_PLACEMENT`, `spawn-from-host` |
1213
+ | A teamctl file that sets a boundary field (r1) | `oats sandbox start`, sync's start | `E_SANDBOX_DEPLOYMENT`, `boundary-field` |
1214
+ | A mount that overlaps a protected path, or shared sandbox state (r1) | `oats sandbox start`, sync's start | `E_SANDBOX_MOUNT`, `overlap` |
1215
+ | A credential source that is not a regular file (r1) | `oats sandbox start`, sync's start | `E_SANDBOX_CREDENTIAL`, `not-a-file` |
1216
+ | A credential source with more than one hard link (r3) | `oats sandbox start`, sync's start | `E_SANDBOX_CREDENTIAL`, `hardlinked` |
1217
+ | An external egress role with no resolvers in the teamctl file (r3) | `oats sandbox start`, sync's start | `E_SANDBOX_DEPLOYMENT`, `resolvers-required` |
1218
+ | An unkeyed apply carrying `identity.seat` (r3) | the in-sandbox apply | `seat-binding` (oats.aweb), field `spawnKey` |
1219
+ | `sandbox-<name>` registered by someone else (r1) | `oats sandbox start`, sync's start | `E_SANDBOX_SERVER`, `server-taken` |
1220
+ | `sandbox-<name>` owned by another deployment (r2) | `oats sandbox start`, sync's start | `E_SANDBOX_SERVER`, `server-owned-elsewhere` |
1221
+ | The team an instance joins, or the team a start would serve, has no provider id yet (r2, r5) | `oats sandbox start`, sync's start, a routed spawn | `E_SANDBOX_TEAM`, `team-not-created` |
1222
+ | The sandbox's souls join more than one team, or a team whose service isn't the bundle's: v1's provider limit (r5) | `oats sandbox start`, sync's start, the seat plan, `seat` | `E_SANDBOX_TEAM`, `team-not-served` |
1223
+ | A delivered seat with a missing or contradictory descriptor (r2) | the in-sandbox apply | `seat-binding` (oats.aweb) |
1224
+ | No provider, or more than one (r1) | every sandbox act | `E_SANDBOX_PROVIDER`, `none` or `ambiguous` |
1225
+ | A placed soul whose selected sandbox this host does not list or run | `oats spawn`, a schedule's spawn | `E_SANDBOX_NOT_HERE` |
1226
+ | A soul this sandbox doesn't list, inside it (r5) | the in-sandbox `oats spawn` | `E_SANDBOX_PLACEMENT`, `not-placed-here` |
1227
+ | A routed request naming another sandbox, or none, inside it (r5) | the in-sandbox remote preview and apply; on the normal host route the preview detects it, before any mint | `E_SANDBOX_PLACEMENT`, `wrong-sandbox` |
1228
+ | Several eligible sandboxes and no `--sandbox` or schedule `sandbox:` (r5) | `oats spawn`, a schedule's spawn | `E_SANDBOX_PLACEMENT`, `sandbox-ambiguous` |
1229
+ | A named target that isn't declared, or doesn't list the soul (r5) | `oats spawn`, a schedule's spawn | `E_SANDBOX_PLACEMENT`, `sandbox-unknown` or `sandbox-not-eligible` |
1230
+ | A soul reference no member or package offers (r5) | `oats spawn`, a schedule's spawn | `E_SANDBOX_PLACEMENT`, `soul-unknown` |
1231
+ | A composition that needs an excluded capability (r5) | the routed spawn, after the remote preview and before anything is kept or minted; a replay's recheck (`held-not-admitted`) | `E_SANDBOX_PLACEMENT`, `capability-excluded` |
1232
+ | A composition with a capability, or a capability source, the last applied plan didn't admit for this soul (r5) | the routed spawn (by hand or a tick), after the remote preview and before anything is kept or minted; a replay's recheck (`held-not-admitted`) | `E_SANDBOX_PLACEMENT`, `capability-not-applied` |
1233
+ | `oats sync --admission-revision` whose revision no longer matches the current inputs (r5) | `oats sync`, for all of that sync's admission; its other steps go on | `E_PLAN_STALE`, with the fresh plan |
1234
+ | `--sandbox` together with `--server` (r5) | `oats spawn` | `E_BAD_ARGS`; the remedy says to choose one target, `--sandbox` for a placed soul or `--server` for a registered server |
1235
+ | A join beyond the default team, into a sandbox (r5) | `seat`, before the mint | `E_SANDBOX_PLACEMENT`, `join-not-seated` |
1236
+ | A resident's grant seat, into a sandbox (r5) | `seat`, before the mint | `E_SANDBOX_PLACEMENT`, `grant-seat-not-sandboxable` |
1237
+ | A sandbox entry with a `team` field (the unreleased shape) (r5) | reading the workspace file | `E_WORKSPACE_SCHEMA`, `sandbox-team-field` |
1238
+ | A local `sandboxes` entry the workspace doesn't declare, a duplicate, or a listed sandbox with no `host.name` (C3) | reading the local file | `E_WORKSPACE_SCHEMA`, `sandbox-unknown`, `duplicate-entry` or `sandbox-host-name-required` |
1239
+ | `sandbox: {self}` combined with `sandboxes`, `credentials`, local `teams` or a local `defaultTeam` (C3b) | reading the in-sandbox local file | `E_WORKSPACE_SCHEMA`, `sandbox-self-conflict` |
1240
+ | A new `oats server add` or `connect` with the reserved `sandbox-` prefix (C7) | `oats server add`, `oats server connect` | `E_SERVER_INVALID`, `reserved-prefix` |
1241
+ | A private registry with no in-sandbox `settings.oats.aweb.registry` (C3) | the in-sandbox spawn | oats.aweb's reason `registry-setting-required`, carried by the kernel's refusal of a required hook's failure |
1242
+
1243
+ Reasons in the table that a provider gives, such as `seat-binding` and
1244
+ `registry-setting-required`, reach the caller inside the kernel's own refusal for a
1245
+ failed required hook. The kernel's codes stay the kernel's; the provider adds only the
1246
+ reason and its remedy (r5).
1247
+
1248
+ **Why `E_SANDBOX_HOST_AGENT`.** The controller key, the team roots, the credential
1249
+ sources and any resident's custody service sit under the account that runs the
1250
+ deployment, because that account mints the seats and serves the residents. A
1251
+ host-side agent of the same deployment would run as that account and could read them,
1252
+ or call the custody socket (r5). So in v1, a
1253
+ deployment that lists a sandbox runs every agent in a sandbox. Agents that belong on the
1254
+ host run from another deployment, under another OS user. This replaces checking file
1255
+ modes against users, which cannot be proved from inside one account.
1256
+
1257
+ ## Left out of v1
1258
+
1259
+ Each restriction sits beside the feature it qualifies (the section named), and goes in
1260
+ the release notes when that feature ships (r5).
1261
+
1262
+ - Creating or deleting machines.
1263
+ - **Several teams in one sandbox, with teamctl:** the model admits it, but v1's provider
1264
+ serves one team per sandbox (C8, `team-not-served`).
1265
+ - **Seats for extra teams** in a sandbox (Identities, `join-not-seated`).
1266
+ - **A resident's grant seat** in a sandbox, until a qualified, revocable remote
1267
+ delegation exists (Identities, `grant-seat-not-sandboxable`).
1268
+ - **Kubernetes qualification.** C4 is the contract a Kubernetes provider implements,
1269
+ and v1's provider is Compose through teamctl. A Kubernetes provider is claimed only
1270
+ after the Acceptance section's Kubernetes case passes on an existing cluster, and its
1271
+ release scope is decided separately.
1272
+ - **Secrets and connector capabilities:** designed only (C9). Per-principal secrets
1273
+ are enforced once the provider exists (Credentials).
1274
+ - Human IDs by default and `oats sandbox adopt`. These wait on aweb's maintainers' decision
1275
+ on reversing "strictly opt-in" (#1665). Adoption is specified once
1276
+ those are settled.
1277
+ - Publishing the image, and its digest in the lock.
1278
+
1279
+ ## Alternatives rejected
1280
+
1281
+ - **A groups block with its own soul list:** it writes the soul-to-team mapping twice.
1282
+ - **Sandbox fields inside team entries:** no named container would remain to list, build
1283
+ or show.
1284
+ - **`hostedBy: everyone` for containers:** Docker could start on a laptop that never
1285
+ asked for it.
1286
+ - **A sandbox that gets an automatic team:** rejected by the product owner. A sandbox
1287
+ listing its own souls was rejected with it at first, then adopted in r5, without the
1288
+ team.
1289
+ - **Placement derived from the default team (r1–r4d):** it tied messaging to the
1290
+ runtime boundary, so one team could never span sandboxes, and one sandbox could
1291
+ never hold two teams without changing the model. Replaced in r5 by explicit
1292
+ placement.
1293
+ - **The local file choosing between eligible sandboxes (r5 draft):** it let a machine's
1294
+ file decide a placement, which only the shared workspace decides. Replaced by the
1295
+ explicit selector (C2).
1296
+ - **A declared `capabilities` list per sandbox (r5 drafts):** first optional, meaning
1297
+ "everything", then a required ceiling where `[]` permitted none. Both made every
1298
+ sandbox repeat the workspace's common capabilities. A `defaults` shorthand was
1299
+ considered and dropped too. Replaced by admission derived per soul, optional
1300
+ exclusions and the applied-plan gate (decided 2026-11-20).
1301
+ - **A `team:` alias for a `souls:` entry's `default`:** two spellings of one key in a
1302
+ closed schema. Left out of this amendment by both sides.
1303
+ - **Docker in the kernel:** the kernel stays runtime-neutral; the provider owns
1304
+ containers.
1305
+ - **The container's own clock beside the host's:** two owners of one schedule.
1306
+ - **Free-form egress origins:** the egress component's guarantee rests on a closed set
1307
+ of roles.
1308
+ - **Credentials through teamctl's `agents.secrets`:** that mount is the harness login
1309
+ only, by its own contract.
1310
+ - **A lease service for schedules:** none exists, and `runsOn` already names one host.
1311
+
1312
+ ## Acceptance (r5)
1313
+
1314
+ | Case | What it shows |
1315
+ | --- | --- |
1316
+ | Same team, separate sandboxes | A reviewer and a deployer in one team, in two sandboxes, exchange the messages aweb allows. Their state, session material and mounts stay separate, and the reviewer can't use the deployment credential. The same holds with cross-team messaging allowed, and with it denied, by aweb's policy. Pending for v1's provider until aweb's maintainers say whether teamctl runs two sandboxes for one team (C8). |
1317
+ | Teams independent of the runtime | Changing a soul's default team, or a label's alias, moves no soul. Two teams in one sandbox, accepted as co-resident trust, run on a provider that serves several teams; v1's provider refuses it with `team-not-served`. One team in two sandboxes introduces no second team. |
1318
+ | Placement and capability refusals | An ambiguous target, a wrong host, a wrong sandbox, an excluded capability, a capability not yet applied, a forged seat binding and an unavailable provider route each fail with the responsible decision and a remedy, before any placement succeeds or usable authority leaks. A route meant for sandbox A that resolves to sandbox B's registration, for a soul eligible in both, refuses at the remote preview with `wrong-sandbox`, and no seat is minted. |
1319
+ | The admission fence and its commit | An exclusion committed between the seat and the apply: the apply is not sent, the seat is released with no home made, and the request is gone. The same exclusion before a replay of an apply that was sent: the replay isn't sent and the seat stays delivered (`held-not-admitted`). Sandbox A's sync step succeeds and B's fails under `--admission-revision`: neither's admission is recorded. Both succeed under the plan's one revision: both sandboxes' widened entries are recorded in one write. A's entry had narrowed while B's widens: A keeps its recorded set. An upstream change in B after the plan: `--admission-revision` refuses `E_PLAN_STALE` in the top-level `problems`, neither A's nor B's admission is recorded, both sandboxes' infrastructure steps still run, and sync exits nonzero. A member's composition, or this host's listing, changes while sandbox B starts, after the plan matched: the commit fence refuses the whole admission with `E_PLAN_STALE` and writes nothing. A soul with no recorded entry is refused until the first reviewed apply, which records it, an empty derived set included (`first: true`); a recorded empty entry admits it. |
1320
+ | Capabilities widen only through an applied plan | One sandbox lists review (capability `read`) and deploy (`read` and `deploy`). Upstream adds `deploy` to review, with no new applied plan. A manual spawn of review and its tick both refuse before minting (`capability-not-applied`), and deploy still works. After the revised plan is approved and applied, review may load the capability, which still grants it no credential or operation. |
1321
+ | Identity apart from the route | Designed while grant seats stay on the host. A grant-backed agent restarts with the same stable DID and a new valid session; one without public inbound reach stays usable as the same principal; an alias match, a wrong team or a stale session can't spend its grant; revocation stops the next dispatch with both sandboxes left in place. |
1322
+ | Target and policy | With Compose: start, authorized work, stop, resume and delist, with separate state and one clock. The same contract against an existing Kubernetes cluster, including storage across a workload replacement and a check of the network policy, before that provider is claimed. |
1323
+
1324
+ ## Delivery
1325
+
1326
+ | Spec | Surface | Lane | Builds first |
1327
+ | --- | --- | --- | --- |
1328
+ | S1a Kernel, the part placement doesn't touch: C1's shape (validated when read), C3, C3b, C4's caller and runner, C5's lifecycle and sync, C7, the kept-request custody and replay fence, readiness | `lib/`, `bin/`, schemas, `docs/` | lane:product | first; reuses the reviewed work of #2025 that no team placement touches, merged after #1912 |
1329
+ | S1b Kernel, placement: C2's selection, derived admission and the applied-plan gate (C1), the seat's team and settings (C4), C3b's checks, the r5 refusals (C10), the status answer without `team` | `lib/`, `bin/`, schemas, `docs/` | lane:product | after S1a |
1330
+ | S2 Provider: `oats.aweb-sandbox`, C4's hook, C6, C7, C8's one served team, the registry setting (C3) | the oats-aweb package | lane:setup, aweb's maintainers read first | after S1b's contract is merged |
1331
+ | 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 |
1332
+ | S4 Broker contracts: C9 docs, then the client verbs | `docs/`, `lib/` | lane:product | after the first real provider |
1333
+
1334
+ Each spec carries its own reference pages and a release-notes entry of its own under
1335
+ `docs/release-notes/next/` (r1):
1336
+
1337
+ - S1a and S1b: [workspaces.md](../workspaces.md) (`sandboxes:`, the rollout rule,
1338
+ C2's selection, and the one-served-team limit stated plainly), [configuration.md](../configuration.md) (C3, C3b), [capabilities.md](../capabilities.md)
1339
+ and the manifest schema (the `sandbox` hook, C4), the CLI and JSON pages (C5),
1340
+ [servers.md](../servers.md) (the reserved prefix, C7), and readiness (C10).
1341
+ - S2: the oats-aweb package's own docs (`identity.seat`, the registry setting,
1342
+ `oats.aweb-sandbox`'s settings, the ledger and reconcile).
1343
+ - S3: [container.md](../container.md) (the credential fragment and its probe) and
1344
+ teamctl's docs on aweb's maintainers' side.
1345
+ - S4: the broker contracts' reference page, when it is built.
1346
+
1347
+ Who builds each slice is decided apart from this record, and reviewing the record
1348
+ commits no side to building one (r5).
1349
+
1350
+ The live rehearsal runs on a disposable Linux Docker host, never on a person's machine.
1351
+ It covers every "done means" line and the Acceptance cases v1's provider can run,
1352
+ with the egress and boundary probes' receipts kept as evidence.