@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.
Files changed (38) hide show
  1. package/bin/oats.mjs +62 -6
  2. package/docs/capabilities.md +374 -18
  3. package/docs/capability-manifest.schema.json +30 -0
  4. package/docs/design/2026-11-20-provider-home-lifecycle.md +3 -1
  5. package/docs/design/2026-11-21-human-ids-contract.md +342 -0
  6. package/docs/design/README.md +2 -0
  7. package/docs/desktop-cli-api.md +111 -4
  8. package/docs/execution-targets.md +24 -1
  9. package/docs/implementation.md +26 -3
  10. package/docs/release-notes/v0.70.0.md +155 -0
  11. package/docs/release-notes/v0.70.1.md +70 -0
  12. package/docs/schedules.md +42 -3
  13. package/docs/souls-and-instances.md +12 -0
  14. package/docs/trust-model.md +8 -1
  15. package/docs/upgrading.md +16 -5
  16. package/lib/automation-scope.mjs +1 -1
  17. package/lib/capability-show.mjs +10 -1
  18. package/lib/core.mjs +408 -66
  19. package/lib/home-integrity.mjs +329 -0
  20. package/lib/hook-env.mjs +2 -1
  21. package/lib/instance-events.mjs +32 -5
  22. package/lib/instance-git.mjs +9 -0
  23. package/lib/instance-inspect.mjs +64 -10
  24. package/lib/instance-listing.mjs +5 -1
  25. package/lib/instance-resolution.mjs +85 -2
  26. package/lib/instance-upgrade.mjs +170 -14
  27. package/lib/remote.mjs +33 -1
  28. package/lib/retire-admission.mjs +7 -0
  29. package/lib/sandbox-allowances.mjs +329 -0
  30. package/lib/schedule.mjs +6 -4
  31. package/lib/servers.mjs +10 -1
  32. package/lib/session-inspect.mjs +20 -75
  33. package/lib/session-providers.mjs +68 -19
  34. package/lib/session-receipt.mjs +93 -0
  35. package/lib/upgrade-state.mjs +6 -1
  36. package/lib/worktree-hooks.mjs +18 -2
  37. package/lib/worktree.mjs +21 -7
  38. 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)
@@ -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).
@@ -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, on success or refusal. It reads the
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); `E_SESSION_INPUT_FAILED` for anything else. A stop or a
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). A retire goes on
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`, `OATS_LAUNCH_PREVIEW`, `OATS_RETIRE_INTENT`,
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
@@ -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 home's own module copy per verb, 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. |
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). `--max-age` adds the observation
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. The fixture's
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