@awebai/oats 0.69.24 → 0.70.1
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.
- package/bin/oats.mjs +62 -6
- package/docs/capabilities.md +374 -18
- package/docs/capability-manifest.schema.json +30 -0
- package/docs/design/2026-11-20-provider-home-lifecycle.md +3 -1
- package/docs/design/2026-11-21-human-ids-contract.md +342 -0
- package/docs/design/README.md +2 -0
- package/docs/desktop-cli-api.md +111 -4
- package/docs/execution-targets.md +24 -1
- package/docs/implementation.md +26 -3
- package/docs/release-notes/v0.70.0.md +155 -0
- package/docs/release-notes/v0.70.1.md +70 -0
- package/docs/schedules.md +42 -3
- package/docs/souls-and-instances.md +12 -0
- package/docs/trust-model.md +8 -1
- package/docs/upgrading.md +16 -5
- package/lib/automation-scope.mjs +1 -1
- package/lib/capability-show.mjs +10 -1
- package/lib/core.mjs +408 -66
- package/lib/home-integrity.mjs +329 -0
- package/lib/hook-env.mjs +2 -1
- package/lib/instance-events.mjs +32 -5
- package/lib/instance-git.mjs +9 -0
- package/lib/instance-inspect.mjs +64 -10
- package/lib/instance-listing.mjs +5 -1
- package/lib/instance-resolution.mjs +85 -2
- package/lib/instance-upgrade.mjs +170 -14
- package/lib/remote.mjs +33 -1
- package/lib/retire-admission.mjs +7 -0
- package/lib/sandbox-allowances.mjs +329 -0
- package/lib/schedule.mjs +6 -4
- package/lib/servers.mjs +10 -1
- package/lib/session-inspect.mjs +20 -75
- package/lib/session-providers.mjs +68 -19
- package/lib/session-receipt.mjs +93 -0
- package/lib/upgrade-state.mjs +6 -1
- package/lib/worktree-hooks.mjs +18 -2
- package/lib/worktree.mjs +21 -7
- package/package.json +1 -1
|
@@ -0,0 +1,342 @@
|
|
|
1
|
+
# Human IDs: the contract between aweb's primitives and OATS
|
|
2
|
+
|
|
3
|
+
**Status:** DRAFT r2, 2026-11-21 (r1 read by aweb's maintainers and the OATS deployment owner's side). It isn't in force until aweb's maintainers and the
|
|
4
|
+
OATS deployment owner's side approve it on this PR. Items marked **OPEN** are undecided and
|
|
5
|
+
mustn't be built on.
|
|
6
|
+
|
|
7
|
+
**What it is.** aweb lets a person adopt an agent (a "root") so that every agent the root
|
|
8
|
+
creates afterwards carries a verified chain back to that person. OATS consumes this:
|
|
9
|
+
- it creates agents from a root, so new instances inherit the chain;
|
|
10
|
+
- it reads each instance's verified human and shows it as **Owning human**.
|
|
11
|
+
|
|
12
|
+
This record is the one place that says which aweb primitives OATS relies on, exactly how
|
|
13
|
+
OATS calls them, what each side owns, and the gates before anything ships. When aw changes
|
|
14
|
+
one of these primitives, or OATS changes how it uses one, this record changes first.
|
|
15
|
+
|
|
16
|
+
**Sources.**
|
|
17
|
+
- aweb: main `d8d0bfa1e7` (`docs/id-certificates.md`, `docs/identity.md`,
|
|
18
|
+
`docs/cli-integration-contract.md`, `docs/cli-command-reference.md`) and aweb's primitive
|
|
19
|
+
list at that SHA.
|
|
20
|
+
- Cloud: the person's dashboard steps read at Cloud `15591632` (tag v0.8.80) and main
|
|
21
|
+
`234882b7`.
|
|
22
|
+
- OATS: the integration plan v1.7 (`0d8b9e1159c6`), read with oats-aweb main `717d0fd`.
|
|
23
|
+
|
|
24
|
+
Every behaviour below is pinned at **the 1.36.59 cut SHA**, which aweb names when it cuts.
|
|
25
|
+
Commit ids are background only.
|
|
26
|
+
|
|
27
|
+
## 1. Principles both sides keep
|
|
28
|
+
|
|
29
|
+
1. **Opt-in is the adoption itself.** A deployment whose roots nobody adopted changes in
|
|
30
|
+
nothing: no OATS setting, no config key, no new aw requirement.
|
|
31
|
+
2. **People sign; agents never act as people.**
|
|
32
|
+
- No agent holds or uses a person's signing key, or a team-scoped owner/admin API key of
|
|
33
|
+
a person's account (P6's key). This is an OATS rule in its own right.
|
|
34
|
+
- A BYOT team's controller key on the deployment host, which the provider's mint uses
|
|
35
|
+
(`aw init --join-from` signs the local invite with it), is unchanged. It belongs to the
|
|
36
|
+
deployment's user, not to a person's account.
|
|
37
|
+
- aw also refuses every person signature inside an OATS instance or without a terminal
|
|
38
|
+
(`human_approval_required`). That is a safeguard on native person signing, not a
|
|
39
|
+
custody boundary, so OATS doesn't rely on it.
|
|
40
|
+
- The person's adoption acts happen in Cloud's dashboard.
|
|
41
|
+
- OATS's existing operator-run key flows are unchanged: `oats aweb setup`'s provisioning
|
|
42
|
+
key and `resident create`'s dashboard key are typed by the person into a protected
|
|
43
|
+
child environment and never held by an agent.
|
|
44
|
+
3. **Prospective, never retroactive.**
|
|
45
|
+
- Adoption applies from then on.
|
|
46
|
+
- Instances created before it keep their key, ID, certificate, address, mailbox,
|
|
47
|
+
memberships and actual ancestry. Chainless ones read `unknown` / `legacy_no_chain`.
|
|
48
|
+
Ones with older namespace ancestry can read `no_human`, or refuse superseded evidence.
|
|
49
|
+
- Leaving them alone is the deployment owner's choice. OATS doesn't respawn or re-sign
|
|
50
|
+
them.
|
|
51
|
+
4. **Attribution is information.** No OATS behaviour (gating, routing, permission) depends on
|
|
52
|
+
the human. OATS only reads it and shows it.
|
|
53
|
+
5. **aw's answer is the truth.** OATS copies aw's verdicts and refusals as aw gives them. It
|
|
54
|
+
reads them only from aw's `--json` fields (§5), never from prose.
|
|
55
|
+
|
|
56
|
+
## 2. Primitives OATS uses
|
|
57
|
+
|
|
58
|
+
| # | Primitive (aw at the cut SHA) | Who runs it, where | OATS's use |
|
|
59
|
+
|---|---|---|---|
|
|
60
|
+
| P1 | `aw --identity-home <root>/.aw id parent request --domain D --parent H --invitation-id I --out request.json` | An agent, in the root's home, during adoption, with the root's own key | Documented step (PR b). D, H and I are copied from the dashboard's invitation, never derived. Writes and retains the request. Only a genuinely chainless root, or one parented directly by its namespace, can be adopted. A root with person ancestry or an agent parent can't. |
|
|
61
|
+
| P2 | `aw --identity-home <root>/.aw id parent import response.json --domain D` | An agent, in the root's home | Documented step (PR b). Verifies and installs the exact signed response. If these steps become machine-consumed, they add `--json` and follow §4's refusal rules. |
|
|
62
|
+
| P3 | `aw init --join-from=<root> --join-team=<T> --name=<alias> --json --do-not-touch-agents-md` (oats-aweb `bin/oats-aweb.mjs:2541`), `<root>` being the root's workspace directory | The provider's spawn hook, on the root's host, as the deployment's user | Primary identity of every spawned instance (unchanged). After adoption, aw signs the child under the root through the mint's same-machine hosted issuer link. |
|
|
63
|
+
| P4 | `aw team invite --team-id <T> --json` with the root as the selected identity, then `aw --identity-home <home>/.aweb-identity-<label> id team accept-invite --token-stdin --name <alias> --local [--parent <root>/.aw] --json`, the same token on stdin | The provider, joining an instance to an extra team; `<home>/.aweb-identity-<label>` is fresh, or the same retained target on retry | Joined-team identities. aweb confirms `--parent` as the supported, unattended route (native agent-to-agent exchange through a token-scoped creator link, same user and HOME). The child proves the invite's human before membership is submitted. `nearest_human` selects the explicit `--parent` path. That is decided by one bounded P5 read of `<root>/.aw` at join time, falling back to C3's record when the read is `unavailable`. Otherwise `--parent` is omitted: a genuinely chainless root's join is unchanged, and a chained `no_human` root's same-machine join completes through the retained mint link without it. An adopted root on an aw below 1.36.59 stops before minting any invite. That stop is an oats-aweb diagnostic with an OATS-owned code, and a README line names the fix. |
|
|
64
|
+
| P5 | `aw --identity-home <home>/.aw who --json` | The provider | C1 and C2 (§4). |
|
|
65
|
+
| P6 | `aw id team remove-member --namespace D --team NAME --cert-id C [--aweb-url URL] --json` (or `--member`), with a team-scoped owner/admin API key from `--api-key` or `AWEB_API_KEY`, calling `/api/v1/teams/{team_id}/agents/remove-member` | The person, from a terminal (§6) | Membership removal (§6). The documented person-run CLI uses the setup key. The server also accepts signed-in person authority for the same route. A person's signing key is a separate credential. |
|
|
66
|
+
|
|
67
|
+
Person's steps in Cloud (dashboard, signed in, the root's team selected, from the root's
|
|
68
|
+
Chat or Messages pane):
|
|
69
|
+
1. **Adopt**, which creates invitation I and shows I, H and D.
|
|
70
|
+
2. **Upload request.json**, then **Approve and prepare response**.
|
|
71
|
+
3. **Download response.json**.
|
|
72
|
+
|
|
73
|
+
Preconditions:
|
|
74
|
+
- the person has claimed a human ID;
|
|
75
|
+
- they are the root's recorded creator, with an active account and current membership of
|
|
76
|
+
the root's team, or a team admin or owning-organisation owner/admin.
|
|
77
|
+
|
|
78
|
+
OATS doesn't use, and doesn't build on, these aw primitives:
|
|
79
|
+
- `id create --human-parent`;
|
|
80
|
+
- `id child invite/receive/approve` on an OATS host;
|
|
81
|
+
- `id parent refresh`, `--resign` and `install`;
|
|
82
|
+
- `id revoke`;
|
|
83
|
+
- an explicit `team invite --for-human`;
|
|
84
|
+
- global join-from;
|
|
85
|
+
- hosted `--member-global` mint.
|
|
86
|
+
|
|
87
|
+
## 3. aw's rules OATS relies on
|
|
88
|
+
|
|
89
|
+
- **The `aw who --json` shape** is `{id, domain, outcome, human_id, identity_valid, kind, reason, chain?, evidence?}`.
|
|
90
|
+
- `outcome` is one of `nearest_human`, `no_human`, `unknown` or `unavailable`.
|
|
91
|
+
- `human_id` is set only on `nearest_human`.
|
|
92
|
+
- `chain[{id,kind}]` is present only when the chain is verified.
|
|
93
|
+
- `unavailable` (`evidence_unavailable`, `status_expired`) is a value, not a command
|
|
94
|
+
failure.
|
|
95
|
+
- A `did:key` home with no chain reads `unknown` / `legacy_no_chain`.
|
|
96
|
+
- The same fields exist in aw 1.36.58.
|
|
97
|
+
- **Adoption** is once per root key. P1 and P2 cover two cases:
|
|
98
|
+
- first issuance to a genuinely chainless root;
|
|
99
|
+
- one-time replacement of a chain parented directly by the namespace, under the first
|
|
100
|
+
person.
|
|
101
|
+
- Cloud's browser authority and eligibility checks gate either case.
|
|
102
|
+
- A local `did:key` root adopts only through the browser-file flow above. An
|
|
103
|
+
agent-submitted request is refused with `global_agent_required`.
|
|
104
|
+
- One adoption covers one key. A host with several roots needs one adoption per root.
|
|
105
|
+
- **After adoption:**
|
|
106
|
+
- The root's ordinary hosted member invites default to its verified nearest human
|
|
107
|
+
(`for_human`). There is no opt-out: `--for-human` can only name another valid person.
|
|
108
|
+
- A `--join-from` child satisfies it.
|
|
109
|
+
- Spawning needs current evidence: registry status and the namespace's DNS. Valid cached
|
|
110
|
+
evidence can cover a brief outage. Without current evidence, the spawn is refused
|
|
111
|
+
(`evidence_unavailable`) with no fallback.
|
|
112
|
+
- New children are issued in the person's domain.
|
|
113
|
+
- Alias, address form, roster entry and mail and chat routing are unchanged in form.
|
|
114
|
+
- An instance spawned by another instance has the root as its immediate ID parent,
|
|
115
|
+
because OATS selects the root for every mint. Its OATS parent stays in `spawnedBy`.
|
|
116
|
+
- An evidence failure refuses without dropping a presented chain. The code and reason can
|
|
117
|
+
vary with the command and the cause.
|
|
118
|
+
- **Same machine, same HOME, for the unattended route.** The unattended local-link route runs
|
|
119
|
+
both halves of one mint on the root's host, as the same user with the same HOME. The
|
|
120
|
+
retained link lives under the minting process's HOME.
|
|
121
|
+
- **Signature pending.** A fresh recipient of an invite that pins a self-custodial agent
|
|
122
|
+
issuer stops before membership when it has no installed chain and no accessible local
|
|
123
|
+
issuer exchange. That holds whether or not the invite carries `for_human`, so it covers a
|
|
124
|
+
chained `no_human` issuer too.
|
|
125
|
+
- aw keeps the key, the pending invite selection and any prepared request. The stop can
|
|
126
|
+
come before any request is created. No membership is submitted.
|
|
127
|
+
- On 1.36.59 it exits 1 with `error.code` `native_agent_signature_pending` (aweb
|
|
128
|
+
`802f1674`; pending verification of the published final binary at the cut SHA).
|
|
129
|
+
- aw 1.36.58 takes the same stop, but exits 1 with the generic `error.code` `error`, which
|
|
130
|
+
doesn't identify this state.
|
|
131
|
+
|
|
132
|
+
## 4. OATS's side (oats-aweb PR a; docs PR b)
|
|
133
|
+
|
|
134
|
+
**C1, the attribution read.**
|
|
135
|
+
- **When:** at spawn after the mint, and at each start (the launch hook's real pass only,
|
|
136
|
+
never under `OATS_LAUNCH_PREVIEW=1`).
|
|
137
|
+
- **The read:** P5, bounded at 5 s, run once, with no retry. It never refuses and never
|
|
138
|
+
delays beyond the bound.
|
|
139
|
+
- **What it writes:** the kernel's existing `attribution` in the served identity:
|
|
140
|
+
`{mode, human: {id, label}|null, parent: {id}|null}`.
|
|
141
|
+
- **Mapping from aw's `outcome`:**
|
|
142
|
+
- `nearest_human` → `human`. `label` is `human_id`, because aw gives no display name, so
|
|
143
|
+
the Desktop shows the `did:aw`. `parent {id}` is the chain's next link up from the
|
|
144
|
+
instance, that is, the root.
|
|
145
|
+
- `no_human` → `none`.
|
|
146
|
+
- Anything else → `unknown`.
|
|
147
|
+
- `parent` is null when there is no verified chain.
|
|
148
|
+
- **Carry-forward:** a non-zero exit, a timeout, unparseable output or `unavailable` carries
|
|
149
|
+
the previous value forward, or `unknown` if there is none. An answer aw gave replaces the
|
|
150
|
+
previous value.
|
|
151
|
+
|
|
152
|
+
**C2, the root report in `oats aweb setup --check-only --json`.**
|
|
153
|
+
- **Shape:** `roots[]`, one
|
|
154
|
+
`{label, home, attribution: {outcome, humanId|null, reason|null}, warnings: [string]}` per
|
|
155
|
+
roots-map entry. `warnings` carries the aw-version note and C3's warning, and is empty
|
|
156
|
+
otherwise.
|
|
157
|
+
- **The read:** P5 with `--identity-home <root>/.aw`.
|
|
158
|
+
- **A failed read** gives `unavailable` with its reason.
|
|
159
|
+
- **Old aw:** a root that reads `nearest_human` on an aw below 1.36.59 gets a note that
|
|
160
|
+
spawning from it needs 1.36.59.
|
|
161
|
+
|
|
162
|
+
**C3, the adopted-lineage warning.**
|
|
163
|
+
- **The record:** the provider keeps, in its own state, each root's last *verified*
|
|
164
|
+
`nearest_human` observation (the human and when it was seen), keyed by the root's identity
|
|
165
|
+
and key, not by its label. A later `unknown` or `no_human` doesn't erase it. Only a new
|
|
166
|
+
`nearest_human` replaces it. So the warning shows at every spawn and in every check-only
|
|
167
|
+
while the chain stays missing, not only at the first read.
|
|
168
|
+
- **When it warns:** a root with that record now reads `unknown` or `no_human`, whatever the
|
|
169
|
+
reason. Examples are `legacy_no_chain` after a restore from a
|
|
170
|
+
backup taken before adoption, and `revoked` or `root_replaced`.
|
|
171
|
+
- **How:** it warns at spawn and in check-only (C2's `warnings`), naming the root and aw's
|
|
172
|
+
reason.
|
|
173
|
+
- `unavailable` never triggers it, and the record is kept.
|
|
174
|
+
- It never refuses. A stale copied home is never a reason to adopt again.
|
|
175
|
+
|
|
176
|
+
**Signature pending.**
|
|
177
|
+
- A mint stopped as signature pending is left for the operator. Retiring it would delete the
|
|
178
|
+
kept key.
|
|
179
|
+
- PR a recognises it by `native_agent_signature_pending`.
|
|
180
|
+
- The spawn fails as a failed mint does today. When the kernel's compensation runs the
|
|
181
|
+
provider's retire hook, the hook answers `meta: {retired: false, reason: "signature-pending"}`.
|
|
182
|
+
That is an incomplete cleanup, so the kernel keeps the home, marked
|
|
183
|
+
`.oats-rollback-incomplete.json` (the existing rule in [capabilities](../capabilities.md)).
|
|
184
|
+
No kernel or hook-contract change is involved.
|
|
185
|
+
- The hook answers `signature-pending` only while aw still holds the pending mint: the exact
|
|
186
|
+
home, key and pending selection, including any prepared request. Each `oats retire` retry
|
|
187
|
+
runs the hook again. Once aw settles the mint either way, the hook answers what is true and
|
|
188
|
+
a plain retry clears the home. `--force` is not the route.
|
|
189
|
+
- Nothing remints into that home or compensates it away while it is pending.
|
|
190
|
+
- On an aw without the code (1.36.58, or a cut SHA that lacks it), a signature-pending stop
|
|
191
|
+
can only come from a chained issuer. So PR a keeps a home whose mint failed after aw wrote
|
|
192
|
+
a key only when the mint's issuing root isn't genuinely chainless, by P5's read or by C3's
|
|
193
|
+
record. It never parses prose. A mint from a chainless root keeps today's behaviour, where
|
|
194
|
+
retire settles the recorded mint, so a deployment that doesn't adopt changes in nothing.
|
|
195
|
+
- OATS never retries or remints automatically. An explicit operator recovery keeps the exact
|
|
196
|
+
original home, key, token and selection.
|
|
197
|
+
|
|
198
|
+
**Reading aw's refusals** (aweb's `docs/cli-integration-contract.md` at `e6e9f099c5`).
|
|
199
|
+
- PR a branches only on the exit status and the structured fields: `error.code`,
|
|
200
|
+
`error.http_status` and `error.reason`.
|
|
201
|
+
- `error.message` is for display only. A direct ID-certificate refusal carries a bare reason
|
|
202
|
+
there, but commands may wrap it, so no machine behaviour keys on it.
|
|
203
|
+
- A command may wrap an HTTP refusal under its own code and keep `http_status` and `reason`.
|
|
204
|
+
For example, `aw init --join-from` reports a refused invite as `invite_not_created`, and a
|
|
205
|
+
direct `aw team invite` reports it as `http_error`.
|
|
206
|
+
- Tests assert the fields the actual command returns.
|
|
207
|
+
|
|
208
|
+
**The aw floor.**
|
|
209
|
+
- `min` stays 1.36.33, so a deployment that doesn't adopt needs no new aw.
|
|
210
|
+
- `tested` moves to the 1.36.59 final.
|
|
211
|
+
- A deployment that adopts a root needs aw 1.36.59 on that root's host (C2's note; PR b says
|
|
212
|
+
to upgrade before adopting).
|
|
213
|
+
|
|
214
|
+
**Where OATS mints, and the connect rule.**
|
|
215
|
+
- Spawns (including routed spawns, schedules and sandbox seats made by sync) mint through P3
|
|
216
|
+
on the host that runs them, from that host's own root.
|
|
217
|
+
- Joined teams mint through P4.
|
|
218
|
+
- GLOBAL grant seats, retained seats and `setup --create` don't mint from a root.
|
|
219
|
+
- `oats aweb connect <server>`, and `setup --join` with an invite issued by a root on
|
|
220
|
+
another machine, mint a new remote root away from the issuing root.
|
|
221
|
+
- The rule (aweb, at `d8d0bfa1e7`, tested against aw 1.36.58 and the 1.36.59 candidate):
|
|
222
|
+
- A new unattended remote root can't join through an invite from a self-custodial chained
|
|
223
|
+
inviter, whether that inviter reads `nearest_human` or `no_human`, on either aw version.
|
|
224
|
+
That holds before adoption as well as after. aw stops it as signature pending (§3).
|
|
225
|
+
- Only a genuinely chainless inviter (`unknown` / `legacy_no_chain`) gives an invite a new
|
|
226
|
+
remote root can join directly, and that root can be adopted on its own later.
|
|
227
|
+
- With a chained inviter, the supported route is aw's cross-machine file exchange. The
|
|
228
|
+
inviting root agent signs the remote root as its child, with an operator moving the files
|
|
229
|
+
and no person signature. The remote root then belongs to that lineage and can't be
|
|
230
|
+
adopted separately.
|
|
231
|
+
- **Connect** has the inviting root on this host. It reads that root with P5 before
|
|
232
|
+
minting the invite, and refuses a chained inviter unless the operator chose the file
|
|
233
|
+
exchange. An `unavailable` read falls back to C3's record, or with none proceeds with a
|
|
234
|
+
warning.
|
|
235
|
+
- **`setup --join`** with only a token can't read the inviter. aw enforces the rule at
|
|
236
|
+
accept, and OATS keeps the pending home (§4 "Signature pending").
|
|
237
|
+
- Out of scope for this rule: an identity that already has a chain joining a team, and an
|
|
238
|
+
issuer in host-managed custody.
|
|
239
|
+
|
|
240
|
+
## 5. Gates
|
|
241
|
+
|
|
242
|
+
- **G1, aw.** Nothing merges until aw 1.36.59 final is published and PR a's real-binary
|
|
243
|
+
tests pass against the final binary at the cut SHA. Those tests run P3 and same-machine P4
|
|
244
|
+
with their actual argv. They assert that the child's installed leaf binds the retained
|
|
245
|
+
child key and the exact parent, that it verifies to the person, and that P4 without
|
|
246
|
+
`--parent` from a chainless root still joins.
|
|
247
|
+
- Development and CI may use `1.36.59-rc.3`, pinned by integrity.
|
|
248
|
+
- `tested` never points at an RC.
|
|
249
|
+
- **G2, the run.** aweb's Cloud journey case (`cloud-journey-case-acxy7-v1`; original
|
|
250
|
+
case-text hash `85196827b2b0`) runs on a scratch hosted team with a test person, never on
|
|
251
|
+
a live team or a real person's identities.
|
|
252
|
+
- Its first green run is the evidence, recorded with the actual Cloud head, the aw cut SHA
|
|
253
|
+
and a verdict per step. The agreed record (v3) is written from it.
|
|
254
|
+
- Its eight steps:
|
|
255
|
+
1. Before adoption, R mints an early child E.
|
|
256
|
+
2. The person adopts R through the dashboard's invitation, upload and approval, and
|
|
257
|
+
download, with P1 and P2 run in R. R then reads `nearest_human`.
|
|
258
|
+
3. R mints a child C unattended. C verifies to the person, and its chain ends in R then
|
|
259
|
+
C.
|
|
260
|
+
4. A grandchild G is minted unattended. Its chain ends in R then G.
|
|
261
|
+
5. E is unchanged: same ID, key and membership certificate, still `unknown`.
|
|
262
|
+
6. A control child K, minted from an unadopted root R0, matches C in alias, address,
|
|
263
|
+
roster and workspace form. Verified mail and chat flow both ways between C and K.
|
|
264
|
+
7. Revocation, as changed with both sides' agreement from the original "a team admin
|
|
265
|
+
removes R's membership in the dashboard", which the released Cloud lacks (§6):
|
|
266
|
+
- P6 runs against the scratch hosted team and R's exact team certificate.
|
|
267
|
+
- A surviving child reads fresh registry membership and confirms R is absent.
|
|
268
|
+
- The signed-in person reloads Agents and sees the surviving child and R's absence.
|
|
269
|
+
- R's next `aw init --join-from` exits nonzero with `error.code`
|
|
270
|
+
`invite_not_created`, `http_status` 401 and `reason` `certificate_revoked`
|
|
271
|
+
(aw init.go:434-442).
|
|
272
|
+
- The surviving members' certificates, mail and chat history are unchanged.
|
|
273
|
+
- The paired runtime evidence includes P6 run with a fresh dashboard-issued,
|
|
274
|
+
same-team owner or admin setup key, once Cloud's restoration is composed (§6).
|
|
275
|
+
8. Clean-up: scratch memberships removed, scratch identities revoked, receipts checked.
|
|
276
|
+
- **G3, Cloud.** Production Cloud (0.8.80, `15591632`, read from its health endpoint on
|
|
277
|
+
2026-11-21) already has the person's three adoption steps. Adoption on hosted teams still
|
|
278
|
+
waits for aweb's release decision on the Cloud release it pairs with aw 1.36.59, made on
|
|
279
|
+
G2's browser evidence. aweb names that version.
|
|
280
|
+
|
|
281
|
+
## 6. Revocation
|
|
282
|
+
|
|
283
|
+
- There is no per-root undo of an adoption.
|
|
284
|
+
- The control is removing the root's team membership. The way on is a new root with a new
|
|
285
|
+
key.
|
|
286
|
+
- Removing the membership leaves the other members' memberships, mail and history
|
|
287
|
+
unchanged.
|
|
288
|
+
- The person can revoke their whole ID, which ends everything under them. OATS neither does
|
|
289
|
+
nor tests that.
|
|
290
|
+
|
|
291
|
+
**How the membership is removed on a hosted team** (decided by aweb's product owner,
|
|
292
|
+
2026-11-21, relayed by aweb's maintainers in their mail `c05ca697`):
|
|
293
|
+
- The paired Cloud release keeps the existing hosted CLI route, P6. The person who runs it
|
|
294
|
+
is the team's current owner or team admin, using their team's unexpired dashboard setup
|
|
295
|
+
key, with the existing team and person checks.
|
|
296
|
+
- This restores the setup key's authority on that route, which production (`15591632`)
|
|
297
|
+
already gives. Until aweb's maintainers name the restoring SHA and the user-path evidence
|
|
298
|
+
exists, this is a release commitment, not shipped behaviour.
|
|
299
|
+
- There is no dashboard membership-only Remove for a team-only root. Archive and Replace
|
|
300
|
+
remain for permanent agents.
|
|
301
|
+
- The principle: no user path is harder than production, and extra human-assurance security
|
|
302
|
+
is opt-in.
|
|
303
|
+
- Removing the membership affects that team and the root's ability to mint there. The
|
|
304
|
+
signed adoption and identity ancestry stay in place. This is not an undo of adoption.
|
|
305
|
+
|
|
306
|
+
**Current behaviour: the person runs P6.** No agent holds or uses the person's owner or
|
|
307
|
+
admin key (principle 2). The ruling above restores a credential's server authority; it
|
|
308
|
+
grants no exception to principle 2.
|
|
309
|
+
- For the OATS deployment owner's deployments, the person-run P6 step is pending their word,
|
|
310
|
+
because their recorded rule is that agents run every command. PR b's revocation text waits
|
|
311
|
+
on it.
|
|
312
|
+
|
|
313
|
+
**OPEN R: whether to allow delegation later.** An agent running P6 with an owner key the
|
|
314
|
+
person delegates would need a separate ruling.
|
|
315
|
+
|
|
316
|
+
Principle 2 forbids the second unless both OATS owners, aweb's product owner and the OATS
|
|
317
|
+
deployment owner, rule otherwise. Principle 2 binds every OATS deployment, so neither side
|
|
318
|
+
changes it alone.
|
|
319
|
+
|
|
320
|
+
Once that word is in, PR b documents the person-run P6 with the setup key, and no session
|
|
321
|
+
plumbing.
|
|
322
|
+
|
|
323
|
+
## 7. Ownership
|
|
324
|
+
|
|
325
|
+
| Area | Owner | Approves changes |
|
|
326
|
+
|---|---|---|
|
|
327
|
+
| aw primitives P1 to P6, codes, the cut SHA | aweb's maintainers | aweb's maintainers |
|
|
328
|
+
| Cloud's person steps and the paired Cloud release | aweb's Cloud maintainers | aweb's maintainers |
|
|
329
|
+
| The journey case and its verdicts (G2) | aweb's Cloud maintainers | both sides; any change to the case's text comes to OATS first |
|
|
330
|
+
| C1 to C3, the mint flows, the floor (oats-aweb PR a) | the OATS deployment owner's side builds it | the OATS deployment owner's side, then the OATS maintainers at the exact head |
|
|
331
|
+
| Docs and release notes (PR b) | the OATS deployment owner's side | both |
|
|
332
|
+
| This record | the OATS maintainers | both sides, on its PR |
|
|
333
|
+
|
|
334
|
+
## 8. Open items
|
|
335
|
+
|
|
336
|
+
- **A, B: answered** by aweb at `d8d0bfa1e7`, with B tested against aw 1.36.58 and the
|
|
337
|
+
1.36.59 candidate (§2 P4, §3, §4 "Where OATS mints").
|
|
338
|
+
- **C.** `native_agent_signature_pending` is implemented on aweb `802f1674` (exit 1, recovery
|
|
339
|
+
state kept, no membership). Its inclusion is pending verification of the published final
|
|
340
|
+
binary at the cut SHA.
|
|
341
|
+
- **R.** Whether an agent may ever run P6 with a delegated owner key (§6). Today only the
|
|
342
|
+
person runs it. (both OATS owners: aweb's product owner and the OATS deployment owner)
|
package/docs/design/README.md
CHANGED
|
@@ -37,6 +37,8 @@ successor, with a link to its full text.
|
|
|
37
37
|
built): boundaries declared in the workspace's `sandboxes:`, each listing the souls
|
|
38
38
|
it may run, started by `oats sync` on the machines that list them. Placement no
|
|
39
39
|
longer follows a team (r5).
|
|
40
|
+
- [Human IDs contract](2026-11-21-human-ids-contract.md): the aweb human-ID
|
|
41
|
+
primitives OATS relies on, how it calls them, who owns what, and the gates.
|
|
40
42
|
|
|
41
43
|
The Desktop's design brief for designers is in
|
|
42
44
|
[packages/desktop/docs](../../packages/desktop/docs/design-brief.md).
|
package/docs/desktop-cli-api.md
CHANGED
|
@@ -2820,10 +2820,38 @@ oats spawn <soul> [the flags of a real spawn] --preview [--max-age <s>] --json
|
|
|
2820
2820
|
```
|
|
2821
2821
|
|
|
2822
2822
|
Feature `spawn-preview-2`, `spawnPreviewApi: 2`. The preview runs every
|
|
2823
|
-
preflight a spawn runs and writes nothing
|
|
2823
|
+
preflight a spawn runs and writes nothing of the deployment's state, on
|
|
2824
|
+
success or refusal (one cache may be filled: a session provider's package
|
|
2825
|
+
tree, below). It reads the
|
|
2824
2826
|
soul from the per-commit cache (`agents/<soul>/souls/<commit12>/`) or fetches
|
|
2825
2827
|
it to a temporary copy (`soulFetched: true`).
|
|
2826
2828
|
|
|
2829
|
+
**A preview on a session provider asks the provider** what the spawn will ask
|
|
2830
|
+
it before any hook runs: its readiness `check`, with the launch that is
|
|
2831
|
+
planned ([check](capabilities.md#check-optional)). No key changes meaning:
|
|
2832
|
+
|
|
2833
|
+
- A launch the provider would refuse **fails the preview** with the code the
|
|
2834
|
+
spawn would be refused with (`E_BACKEND_SANDBOXED_MODE` for a provider that
|
|
2835
|
+
launches only in full mode, `E_BACKEND_NOT_READY` for one that cannot be
|
|
2836
|
+
asked or answers outside the rules), exit 1, as every other refusal of a
|
|
2837
|
+
backend fails it. Nothing is created: not the home, nor the kernel's
|
|
2838
|
+
directory beside it.
|
|
2839
|
+
- The check runs within the preview's one preflight budget. A provider that
|
|
2840
|
+
does not answer in what is left of it leaves `preflight.status: "timeout"`.
|
|
2841
|
+
It is never given longer than a spawn gives its check (20 s). That limit
|
|
2842
|
+
is also the preview's whole budget, so today a check that does not answer
|
|
2843
|
+
in time always reads as `timeout`; were the budget longer than the limit,
|
|
2844
|
+
a check that reached the limit would fail the preview
|
|
2845
|
+
`E_BACKEND_NOT_READY`, as it fails the spawn.
|
|
2846
|
+
- The provider's script runs from its package's tree in the deployment's
|
|
2847
|
+
module store, which the preview fetches there, verified, when it is absent:
|
|
2848
|
+
the one thing a preview may write, a cache `oats readiness --soul` fills the
|
|
2849
|
+
same way. A provider in a **member module** runs only from a spawned home,
|
|
2850
|
+
so it is not asked, and `warnings` carries one line that says so; the spawn
|
|
2851
|
+
still asks it.
|
|
2852
|
+
- A provider that declares no `check`, a tmux launch and a `--no-launch`
|
|
2853
|
+
spawn ask nothing.
|
|
2854
|
+
|
|
2827
2855
|
```json
|
|
2828
2856
|
{"modules":[
|
|
2829
2857
|
{"name":"nw-tools","from":{"kind":"member","repoKey":"github.com/nw/agents","commit":"66566512…"},"layer":null,"private":false,"declares":[],
|
|
@@ -7458,6 +7486,8 @@ before anything is created (a preview answers them too):
|
|
|
7458
7486
|
| `E_BACKEND_AMBIGUOUS` | `{backend, capabilities}`; also from a start or a restart |
|
|
7459
7487
|
| `E_BACKEND_HARNESS` | `{backend, capability, harness, harnesses}` |
|
|
7460
7488
|
| `E_BACKEND_LAUNCH_ARG` | `{backend, launchConfig, field: "executable"}` |
|
|
7489
|
+
| `E_BACKEND_WIRE` | `{backend, capability, wire: {provider, kernel}}`: the provider's declared wire version (null: none) and this kernel's. Also from a start, a restart, a `--resume`, a stop (an operator's and the host's) and an input, before anything is read or stopped |
|
|
7490
|
+
| `E_BACKEND_SANDBOX_HOST` | `{capability, setting, host, team?, path?}`: a capability's `sandboxDomains` line that may not add a host; `setting` and `host` are null where there is none to name. With `path` (and `capability: null`): a path the kernel itself would allow the session to write that is reached through a symbolic link, or is no directory. Also from a start or a restart, before anything is stopped |
|
|
7461
7491
|
| `E_BACKEND_NOT_READY`, any other `E_BACKEND_*` | the provider's readiness, or its own refusal of the launch: `{backend, capability}`; the spawn is rolled back |
|
|
7462
7492
|
|
|
7463
7493
|
A launch that fails otherwise is `E_SESSION_START_FAILED`.
|
|
@@ -7518,7 +7548,9 @@ spawn's and a start's). `E_SESSION_NOT_RUNNING` for a home OATS
|
|
|
7518
7548
|
stopped (nothing was sent, the provider was not called), and for a lost
|
|
7519
7549
|
session at its resume cap or with a process of its last run still in the
|
|
7520
7550
|
home; `E_SESSION_PROMPT_OPEN` and `E_SESSION_INPUT_QUEUED` from the provider
|
|
7521
|
-
(nothing was sent); `
|
|
7551
|
+
(nothing was sent); `E_BACKEND_WIRE` for a home whose provider speaks
|
|
7552
|
+
another wire than this kernel (nothing was sent, the provider was not
|
|
7553
|
+
called); `E_SESSION_INPUT_FAILED` for anything else. A stop or a
|
|
7522
7554
|
restart that lands while an input is being sent wins, whatever the provider
|
|
7523
7555
|
answered to it: `E_SESSION_NOT_RUNNING`, the input not delivered. A delivery
|
|
7524
7556
|
is accepted only on `ok: true` with `submitted: true`.
|
|
@@ -7556,7 +7588,10 @@ launched before is left stopped. The row of a never-launched home reads
|
|
|
7556
7588
|
|
|
7557
7589
|
**Stop and retire.** The stop's row is `{ok: true, stopped, alreadyIdle,
|
|
7558
7590
|
state: "stopped"}`; `E_SESSION_STOP_FAILED` when the provider does not confirm
|
|
7559
|
-
(the home stays recorded as stopped; a second stop asks the provider again)
|
|
7591
|
+
(the home stays recorded as stopped; a second stop asks the provider again);
|
|
7592
|
+
`E_BACKEND_WIRE` for a home whose provider speaks another wire than this
|
|
7593
|
+
kernel (nothing is recorded or stopped; a retire of it goes on by the rule
|
|
7594
|
+
below, with its warning). A retire goes on
|
|
7560
7595
|
only when no process works in the home after the provider's stop, confirmed
|
|
7561
7596
|
or not: otherwise `E_RUNTIME_QUIESCE_FAILED`, naming the processes. When the
|
|
7562
7597
|
provider could not confirm the stop, the retire's answer carries a warning.
|
|
@@ -7576,6 +7611,72 @@ warnings}` relayed as given, or `result: null` with `problems` when the
|
|
|
7576
7611
|
provider could not be asked. Required for a home on that backend; not
|
|
7577
7612
|
required for a soul.
|
|
7578
7613
|
|
|
7614
|
+
**Sandbox allowances.** What a session provider may widen its harness's
|
|
7615
|
+
sandbox by for an instance ([capabilities.md](capabilities.md#sandbox-allowances-sandboxdomains-the-launch-inputs-sandbox)),
|
|
7616
|
+
as the kernel computes it from the deployment's configuration. One key,
|
|
7617
|
+
`sandbox`, only where the launch is a provider's (never for tmux):
|
|
7618
|
+
|
|
7619
|
+
- a spawn preview (`oats spawn … --backend <name> --preview --json`):
|
|
7620
|
+
`sandbox: {domains: [{host, capability, setting, team?}], write: [{path, reason}],
|
|
7621
|
+
missing: [{capability, setting, team, defaultTeam, optional?}], unread?: [{capability,
|
|
7622
|
+
setting, reason}]}`. `domains`: each host with the capability and the
|
|
7623
|
+
setting that asked for it, and `team` (a team id) on a host taken from a
|
|
7624
|
+
map: a team the instance may join, not one it is known to have joined. `write`: each path with its reason (the
|
|
7625
|
+
kernel's own). `missing`: what a capability's line names and the
|
|
7626
|
+
deployment does not hold (`team`: a team id, or null for a setting with no
|
|
7627
|
+
value; `defaultTeam`: true for the soul's default team's row and for a row
|
|
7628
|
+
with no team; `optional: true` only on a row of an optional line). `unread`, only
|
|
7629
|
+
when there is one: a `settingFile` line's file that gave no host, or
|
|
7630
|
+
values in it that were skipped.
|
|
7631
|
+
- a start's and a restart's answer: the same object, with `skipped?:
|
|
7632
|
+
[{capability, reason}]` (a slot's provider of the deployment that is not
|
|
7633
|
+
one of the home's modules: it added no host), or `sandbox: {unavailable:
|
|
7634
|
+
"<why>"}` when the deployment's configuration could not be resolved for
|
|
7635
|
+
the home's soul (a repository this host's cache does not hold, a soul the
|
|
7636
|
+
workspace no longer offers, or two souls that share the home's agent
|
|
7637
|
+
directory). That resolution reaches no remote: it reads the
|
|
7638
|
+
workspace as this host last read it and `oats-local.yaml` as it is now, so
|
|
7639
|
+
a repository this host's cache does not hold is such a cause, by name. Each `skipped` row is also a `warnings` line.
|
|
7640
|
+
- `oats readiness --home <abs> --json` of a provider home: the same, as a
|
|
7641
|
+
start would compute it now, or `sandbox: {refused: {code:
|
|
7642
|
+
"E_BACKEND_SANDBOX_HOST", message, details}}` when a start would be
|
|
7643
|
+
refused for it.
|
|
7644
|
+
|
|
7645
|
+
- **`moduleCopy`**, on a status row, a remote roster row and a start's or a
|
|
7646
|
+
restart's answer, of a provider home only (never for tmux), a top-level
|
|
7647
|
+
key beside `modules`:
|
|
7648
|
+
`moduleCopy: {runs: "kernel-copy", homeCopy: "same" | "differs", differs: [<module id>]}`.
|
|
7649
|
+
`runs` says which copy of the home's modules the kernel runs: its own,
|
|
7650
|
+
kept outside the home
|
|
7651
|
+
([capabilities.md](capabilities.md#what-the-kernel-trusts-in-a-provider-home)).
|
|
7652
|
+
**`homeCopy` covers records only**: it compares the home's own record of
|
|
7653
|
+
each module (`instance.json`, its source and commit) with the kernel's
|
|
7654
|
+
record of the copy it runs, and reads no file of either copy. `differs`
|
|
7655
|
+
names the modules whose records disagree (capability ids only, at most
|
|
7656
|
+
200; a name in the home's record that is no capability id counts in
|
|
7657
|
+
`homeCopy` and is not named), `[]` when `homeCopy` is `same`.
|
|
7658
|
+
It says `differs` after an upgrade that was interrupted between moving
|
|
7659
|
+
the home's copies and the kernel's, and when the home's record was
|
|
7660
|
+
rewritten. Whether the FILES of a home copy are the kernel's is reported
|
|
7661
|
+
by `oats readiness --home`, in `kernelCopies` (next). The key is new and
|
|
7662
|
+
optional; `modules` is unchanged, an array of drift rows on a provider
|
|
7663
|
+
home as on any other, with no key added to a row.
|
|
7664
|
+
- `oats readiness --home <abs> --json` of a provider home also carries
|
|
7665
|
+
`kernelCopies: {store, differing: [{capability, differs}]}`, an optional
|
|
7666
|
+
key that no other answer has and that changes the meaning of none: `store`
|
|
7667
|
+
is the name of the store that holds the kernel's own copies of the home's
|
|
7668
|
+
modules, and `differing` lists each module whose copy in the home is not
|
|
7669
|
+
the one the kernel runs (`differs: true`), or could not be compared
|
|
7670
|
+
(`differs: null`); `[]` when every home copy is the kernel's. It is
|
|
7671
|
+
information: the kernel runs its own copy either way
|
|
7672
|
+
([capabilities.md](capabilities.md#what-the-kernel-trusts-in-a-provider-home)).
|
|
7673
|
+
It is computed for this answer only (the files are compared), never for
|
|
7674
|
+
a status row.
|
|
7675
|
+
|
|
7676
|
+
`oats capabilities show <name> --json` carries `sandboxDomains` (the
|
|
7677
|
+
manifest's key, exactly as declared) and, only when there is one,
|
|
7678
|
+
`sandboxDomainProblems: [<message>]`.
|
|
7679
|
+
|
|
7579
7680
|
**The sweep.** A row of `oats session resume` for a provider home carries
|
|
7580
7681
|
`backend`. Its outcomes: `resumed` (a lost session: the notice was sent),
|
|
7581
7682
|
`already-running` (a session is there), `refused` with `keeps-getting-lost`
|
|
@@ -7593,7 +7694,13 @@ hold the listing up. A client has no use for it.
|
|
|
7593
7694
|
**Launch preview.** `oats launch-config preview --home <abs> --json` of a
|
|
7594
7695
|
provider home answers `command: null`, `argv: null` and `executable.path:
|
|
7595
7696
|
null` (its launch is handed to the provider as data), `environment` by name,
|
|
7596
|
-
and a `backend` item in `preflight`.
|
|
7697
|
+
and a `backend` item in `preflight`. The preview asks the provider's `check`
|
|
7698
|
+
with the launch that is planned, as the start will before it stops anything:
|
|
7699
|
+
a launch the provider would refuse is a failed `backend` item (`code`: the
|
|
7700
|
+
start's refusal, `E_BACKEND_*`), and `ok` is false. So is an allowance's path
|
|
7701
|
+
the start would refuse to make (`E_BACKEND_SANDBOX_HOST`); `warnings` carries
|
|
7702
|
+
the start's `sandbox allowances: …` lines. Nothing is stopped, started or
|
|
7703
|
+
created.
|
|
7597
7704
|
|
|
7598
7705
|
### Input
|
|
7599
7706
|
|
|
@@ -691,7 +691,8 @@ operation, a retire or a trigger is given (`OATS_CAPABILITY`, `OATS_LAYER`,
|
|
|
691
691
|
`OATS_OPERATION`, `OATS_REPO`, `OATS_BRANCH`, `OATS_WORK`, `OATS_KIND`,
|
|
692
692
|
`OATS_TASK`, `OATS_HARNESS`, `OATS_HARNESS_EXECUTABLE`,
|
|
693
693
|
`OATS_PREVIOUS_HARNESS`, `OATS_RUNTIME`,
|
|
694
|
-
`OATS_PREVIOUS_RUNTIME`, `
|
|
694
|
+
`OATS_PREVIOUS_RUNTIME`, `OATS_BACKEND`, `OATS_PREVIOUS_BACKEND`,
|
|
695
|
+
`OATS_LAUNCH_PREVIEW`, `OATS_RETIRE_INTENT`,
|
|
695
696
|
`OATS_TRIGGER_EVENT_FILE`, `OATS_TEST_LOGIN_SHELL` (a test seam that replaces
|
|
696
697
|
the login shell, honoured only for a process whose `HOME` is not your home
|
|
697
698
|
directory; a launch configuration cannot set it),
|
|
@@ -950,7 +951,9 @@ anything is created, and shown by a spawn preview:
|
|
|
950
951
|
| `E_BACKEND_AMBIGUOUS` | two capabilities of the instance declare the name (a spawn, and a start or restart of a home whose modules now do) |
|
|
951
952
|
| `E_BACKEND_HARNESS` | the provider does not run the launch's harness |
|
|
952
953
|
| `E_BACKEND_LAUNCH_ARG` | the launch configuration declares an `executable`: a provider runs the harness itself |
|
|
954
|
+
| `E_BACKEND_WIRE` | the provider speaks another version of the session-provider wire than this kernel (its manifest's `wire`), or declares none: use the release of its capability that goes with this OATS |
|
|
953
955
|
| `E_BACKEND_NOT_READY` | the provider's own readiness check, asked right before the launch, says it cannot take it |
|
|
956
|
+
| `E_BACKEND_SANDBOX_HOST` | a capability asks to add a host to the session's sandbox that it may not ask for: it declares `sandboxDomains` and fills none of the instance's messaging, knowledge or tasks slots, its line is malformed, its setting's value gives no plain host, its file is not the deployment's own, its setting was given to this one spawn (`--provider <capability> <setting>=…`: a launch's own argument is never a host source), or the directory the sandbox may write (the deployment's events directory) is reached through a symbolic link or is no directory ([Sandbox allowances](capabilities.md#sandbox-allowances-sandboxdomains-the-launch-inputs-sandbox)) |
|
|
954
957
|
|
|
955
958
|
A provider can also refuse the launch with its own `E_BACKEND_*` code (a
|
|
956
959
|
launch environment entry or an argument it cannot carry), which OATS relays;
|
|
@@ -977,6 +980,26 @@ stoppedAt}`. The two must agree as for tmux: `E_RUNTIME_AUTHORITY_MISMATCH`
|
|
|
977
980
|
otherwise, whose `details.fields` are `backend`, `session.provider` and
|
|
978
981
|
`session.endpoint`.
|
|
979
982
|
|
|
983
|
+
The receipt of a provider home also records its **composition**:
|
|
984
|
+
`composition: { version: 1, store: "<name>", modules: { "<capability>": {
|
|
985
|
+
from, commit } }, capabilityRuntime: [ <row> ], previous?: { store, modules,
|
|
986
|
+
capabilityRuntime } }`: which store holds the
|
|
987
|
+
kernel's own copies of the home's modules
|
|
988
|
+
(`<instances>/.oats-retirement/modules/<hash of the home>/<store>/`), which
|
|
989
|
+
modules the home has and where each came from, and the capability rows the
|
|
990
|
+
spawn resolved; `previous`, after an upgrade, is the pair that upgrade
|
|
991
|
+
replaced, which an undo names again. For such a home the kernel runs its own copy of a module,
|
|
992
|
+
never the home's, and reads a capability's settings and hook commands from
|
|
993
|
+
this record alone
|
|
994
|
+
([What the kernel trusts in a provider home](capabilities.md#what-the-kernel-trusts-in-a-provider-home)).
|
|
995
|
+
A tmux home's receipt has no such key, and the kernel keeps no copy of its
|
|
996
|
+
modules. A kernel from before it ignores the key: one from before session
|
|
997
|
+
providers still refuses every session verb on a provider home, and one that
|
|
998
|
+
knows providers and not this record runs the home's own copies, as it
|
|
999
|
+
always did. A provider home whose receipt has no `composition` (a kernel
|
|
1000
|
+
from before it spawned the home) runs nothing on this kernel: retire it and
|
|
1001
|
+
spawn it again.
|
|
1002
|
+
|
|
980
1003
|
**The lifecycle of a provider home is one state machine**, set out in
|
|
981
1004
|
[its design record](design/2026-11-20-provider-home-lifecycle.md): the
|
|
982
1005
|
states its records spell, what each verb does in each, in what order it
|
package/docs/implementation.md
CHANGED
|
@@ -132,7 +132,8 @@ and the rules its tests pin.
|
|
|
132
132
|
| `session-end.mjs`, `session-resume.mjs`, `session-resume-contract.mjs`, `session-seen.mjs`, `start-env.mjs` | session resume (#1559): what every local listing saw of each home and the pure rule that decides which losses the sweep resumes (`session-seen.mjs`: local listings and the sweep recording homes it started; never in the way of the listing); the contract's names (`sessionEnd`, the start's `resume` object, the sweep's outcomes and reasons, the feature) in one dependency-free module that every producer, test and doc reads (awebai/oats#1567 settles them); how a launched home's last session ended (`sessionEnd`, from the kernel-private exit marker and stop record, both forms of the marker), and the machine sweep `oats session resume` with its lock (a claim taken through `dir-lock.mjs` `acquireDirLock`, its record naming the boot too; `E_RESUME_LOCK_STUCK` for a lock that needs a person, which `oats doctor` reports as `resume-lock-stuck`) and its per-boot note (refusals, and the count behind the bound of 3 sweep starts per home per boot); a resume holds the home's lifecycle claim (`claim.mjs` below), as every start does, the sweep's status-row read of a retire or a claim holder is only its filter, and every stop OATS does writes the stop record through `core.mjs` `recordStop`, a retire's before its window kill; the record of each start's `fromEnv` and `fromFile` values (`start-env.mjs`: a keyed digest per source, never a value) and the one check a resume and `--plan` share, so a resume never starts under a changed value; the conversation a resume continues is `packages/record/lib/last-conversation.mjs` |
|
|
133
133
|
| `stable-node.mjs` | the one rule for a node path written into anything that outlives the process: the host timer's unit and `OATS_NODE_BIN` ([capabilities](capabilities.md#the-node-a-hook-writes-down)). It imports nothing of the kernel |
|
|
134
134
|
| `trigger-sources.mjs` | a capability's `triggerSources`: the use-time validator (per source, never from the manifest contract or discovery) and the source wire's answer and event rules; `triggers.mjs` runs a source with `instance-inspect.mjs`'s `runModuleCommand`, the provider-check runner |
|
|
135
|
-
| `session-providers.mjs` | a capability's `sessionProviders` (feature `session-providers`): the use-time validator (per provider, never from the manifest contract or discovery), `--backend`'s selection among an instance's capabilities, the wire (one call of the
|
|
135
|
+
| `session-providers.mjs` | a capability's `sessionProviders` (feature `session-providers`): the use-time validator (per provider, never from the manifest contract or discovery), `--backend`'s selection among an instance's capabilities, the wire (one call per verb of the kernel's own copy of the home's module, with the hook environment) and the rules of each verb's answer, the receipt's `runtime` for a provider home. A leaf: `session-inspect.mjs` and `instance-listing.mjs` call a provider on the hot reads; `core.mjs` holds the launch, stop, start and retire of a provider home. |
|
|
136
|
+
| `home-integrity.mjs` | what the kernel runs of a provider home ([capabilities](capabilities.md#what-the-kernel-trusts-in-a-provider-home)): its own copies of the home's modules, kept beside the receipt (`session-receipt.mjs`, the receipt's own primitives), the receipt's `composition`, and the capability rows read from it. A leaf: the hot reads load it. |
|
|
136
137
|
| `hook-env.mjs` | the environment a capability's code runs with in an instance home (`lifecycleHookEnv`, `teamEnv`, `stableSoulId`, `instanceSoulDir`, `kernelBin`): every lifecycle hook's and a session provider's commands'. A leaf, re-exported by `core.mjs`. |
|
|
137
138
|
| `provider-resume.mjs` | the resume cap of a home on a session provider: at most `RESUME_LIMIT` resumes of one home in `RESUME_WINDOW_MS`, in one boot, counted before the provider's input is called (the sweep's notice, `session start --resume`, any input to a lost session). One kernel-private file per home under `OATS_HOME_DIR`. A leaf. |
|
|
138
139
|
| `refused-text.mjs` | the one set of characters the kernel never stores or prints in text it did not write (`REFUSED_TEXT`), and `safeText`, which replaces them |
|
|
@@ -561,7 +562,12 @@ differs), `package-manifests` (a package's manifests), `list` (a skill
|
|
|
561
562
|
listing) and `tree-oids` (the tree ids of a set of directories). An entry is only ever a pure function of those bytes and this kernel's
|
|
562
563
|
code, never local state and never a transient error; it is written
|
|
563
564
|
atomically, a corrupt one is a miss, and `pruneStores` bounds the store
|
|
564
|
-
(`PARSED_LIMITS`, least recently used first).
|
|
565
|
+
(`PARSED_LIMITS`, least recently used first). A read session made with
|
|
566
|
+
`offline: true` never reaches a remote: a head is the one this host last
|
|
567
|
+
observed (its record, of any age), a commit and a file are read only when the
|
|
568
|
+
cache holds them, and anything else is `E_REMOTE_UNREADABLE` with reason
|
|
569
|
+
`not-cached`. The sandbox allowances of a session provider's start are
|
|
570
|
+
resolved in one (`lib/instance-resolution.mjs` `homeSandboxSource`). `--max-age` adds the observation
|
|
565
571
|
store `<cache>/.observed/` ([Observation reuse](desktop-cli-api.md#observation-reuse-feature-observe-max-age-oats-0311)):
|
|
566
572
|
one record per (repo key, ref args, url digest), so two spellings of one repo
|
|
567
573
|
keep a record each; the url itself is never written. Beside it,
|
|
@@ -971,7 +977,24 @@ inherits it (awebai/oats#816):
|
|
|
971
977
|
names on the real one and gives the saved one back with
|
|
972
978
|
`setProcessEnvironment` when it ends; everything else goes through
|
|
973
979
|
`fx.inEnv`. `test/fixture-real-environment.test.mjs` refuses an assignment
|
|
974
|
-
to `process.env` in any test script.
|
|
980
|
+
to `process.env` in any test script. **A test writes an executable only
|
|
981
|
+
inside its fixture** (#2042): a harness stand-in, or a home's recorded
|
|
982
|
+
`launch.executable`, is written with
|
|
983
|
+
`writeFixtureExecutable(fx.base, path, content)`, which refuses a path
|
|
984
|
+
outside the fixture's base, one reached through a link, and a symbolic or
|
|
985
|
+
hard link at the path, with nothing written. `fx.inEnv` keeps the PATH of
|
|
986
|
+
the process that runs the tests, where a machine with the harness
|
|
987
|
+
installed has the person's own binary. **An in-process spawn (`fx.spawn`)
|
|
988
|
+
looks for the harness on the fixture's PATH** (#2044): the fixture's inert
|
|
989
|
+
`pi`, `claude` and `codex` are put before the host's directories
|
|
990
|
+
(`fixtureSpawnPath`), after anything the test put in front itself, so a
|
|
991
|
+
test's own fake harness is still the one found and the `launch.executable`
|
|
992
|
+
such a spawn records is inside the fixture. (That is the lookup on this
|
|
993
|
+
process's PATH: a spawn that launches looks on the PATH of the fixture's
|
|
994
|
+
tmux server, and a spawn made without `fx.spawn` keeps the PATH it has.) A test that needs the harness
|
|
995
|
+
of the machine it runs on says so: `fx.spawn(soul, { hostHarness: true })`.
|
|
996
|
+
A spawn whose recorded executable a test will rewrite also asserts
|
|
997
|
+
`insideFixture(fx.base, launch.executable)`. The fixture's
|
|
975
998
|
environment sets `HOME` and the XDG base directories under the base, and
|
|
976
999
|
`GIT_CONFIG_NOSYSTEM=1`, `GIT_CONFIG_GLOBAL=/dev/null` and
|
|
977
1000
|
`GIT_TERMINAL_PROMPT=0`, so no host git
|