@awebai/oats 0.70.0 → 0.70.2

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 CHANGED
@@ -1153,7 +1153,7 @@ function launchConfigContext(bail) {
1153
1153
  * a soul) would run under a selection, resolved against the current scoped
1154
1154
  * configuration, preflighted, read-only; environment values withheld and
1155
1155
  * the prompt named, never the TASK body. */
1156
- function launchPreview(bail) {
1156
+ async function launchPreview(bail) {
1157
1157
  for (const k of ["launch-config", "harness", "runtime", "model"]) if (flag(k) === true) bail("E_BAD_ARGS", `--${k} needs a value`);
1158
1158
  const sel = { launchConfig: flag("launch-config"), harness: harnessFlag(), model: flag("model"), yolo: yoloFlag() };
1159
1159
  if (sel.harness !== undefined && !LAUNCH_HARNESSES.includes(sel.harness)) bail("E_BAD_ARGS", `--harness must be one of ${LAUNCH_HARNESSES.join(", ")}`);
@@ -1190,8 +1190,11 @@ function launchPreview(bail) {
1190
1190
  // The same planner a start uses, in preview mode: failed checks are listed, nothing is touched.
1191
1191
  // Its checks read the pane a launch would run in, as a command that only reads can know it (a
1192
1192
  // home's recorded session, a soul's session default; with no server running, not established).
1193
+ // A home on a session provider: its provider is asked what a start will ask it (its check, with
1194
+ // the launch that is planned), from the deployment's configuration as it is now, as a start reads it.
1195
+ const providerCheck = meta ? await homeSandboxSourceOf(home) : null;
1193
1196
  let plan;
1194
- try { plan = planLaunch({ home, instance, meta, contextDir: context, agentLike, selection: sel, resolvedCfg: r, preview: true, pane: () => previewPaneEnvironment(meta ? { home, meta } : { deployment: context }) }); } catch (e) { bail(e.code || "E_BAD_ARGS", e.message); }
1197
+ try { plan = planLaunch({ home, instance, meta, contextDir: context, agentLike, selection: sel, resolvedCfg: r, preview: true, pane: () => previewPaneEnvironment(meta ? { home, meta } : { deployment: context }), providerCheck }); } catch (e) { bail(e.code || "E_BAD_ARGS", e.message); }
1195
1198
  const { recipe } = plan;
1196
1199
  // A home on a session provider has no command line: its launch is handed to the provider as data
1197
1200
  // (`command` and `argv` null, the executable's path null); its environment is listed by name.
@@ -1206,7 +1209,7 @@ async function launchConfigCmd() {
1206
1209
  dropAmbientRoot();
1207
1210
  const sub = args[1];
1208
1211
  const usage = "usage: oats launch-config list [--dir <scope> | --home <abs> | --soul <name> [--dir <scope>] [--agents-root <abs>]] [--json] | set <name> --file <json> [--keep-env] [--dir <scope>] [--json] | remove <name> [--dir <scope>] [--json] | preview (--home <abs> | --soul <name> [--dir <scope>]) [--launch-config <name>|none] [--harness r] [--model m] [--yolo|--no-yolo] --json";
1209
- if (sub === "preview") { launchPreview(bail); return; }
1212
+ if (sub === "preview") { await launchPreview(bail); return; }
1210
1213
  if (!["list", "set", "remove"].includes(sub)) bail("E_USAGE", usage);
1211
1214
  const { context: dir, selected } = sub === "list" ? launchConfigContext(bail) : { context: dirFlag(), selected: null };
1212
1215
  // Lead decision 2: launch configurations are a HOST choice, declared in the
@@ -1340,6 +1340,64 @@ or at a session boundary.
1340
1340
  - **Codex:** not reported. A provider error fires neither its `Stop` hook nor
1341
1341
  `notify` (Codex 0.160.0), so nothing can observe the turn from outside it.
1342
1342
 
1343
+ **A pi dialog** (from `@awebai/oats-pi` 0.70.2). pi has no question dialog of
1344
+ its own: each blocking one is an extension's (`ctx.ui.select`, `confirm`,
1345
+ `input`, `editor` or `custom`; a question tool's, say). The bridge holds a claim
1346
+ of producer `oats.pi`, reason `question`, from pi's `ui_prompt_start` to its
1347
+ `ui_prompt_end` (pi 0.84.4 and later), in pi's terminal UI and in RPC mode alike,
1348
+ so the same holds for every pi home: a pi in a tmux pane and one a session
1349
+ provider runs. The
1350
+ message is the dialog's title, made one line and cut to fit as the Claude
1351
+ emitter's is; a dialog with no title sets the claim with no text. pi reports
1352
+ nested and overlapping dialogs as one span, with the first one's title. The
1353
+ claim clears when the dialog closes, however it closes, and when the session
1354
+ ends with it open: the bridge waits for that write before pi exits. A producer
1355
+ holds one claim, so an open dialog is shown over a failed turn's `attention`,
1356
+ which shows again once the dialog closes if no run has started since. Outside an
1357
+ OATS instance the bridge reports nothing. What it does not see: a screen of pi's
1358
+ own (its project trust prompt, a picker a person opened), which fires neither
1359
+ event; a question a host asks outside pi (a session provider's own question
1360
+ tool); and anything on a pi before 0.84.4.
1361
+
1362
+ **Whose claim it is.** More than one bridge can run in a home (a nested pi and
1363
+ a subagent's session carry the home's `OATS_INSTANCE_HOME` too), and a pi can
1364
+ die with its dialog open. So the bridge that sets the claim, a dialog's or a
1365
+ failed turn's, records a mark while the claim stands: `<home>/.pi/oats-pi-claim.json`,
1366
+ `{pid, start, token, reason}`, the holder's process (its pid and its start
1367
+ time, so a reused pid is not taken for it), the bridge that wrote it, and the
1368
+ claim's reason. A bridge tells its own claim by that mark, never by the claim's
1369
+ reason, and clears only its own. A holder that is alive keeps its claim: a
1370
+ second pi's first run does not clear it, and another pi's `attention` never
1371
+ replaces its `question`; only a `question` replaces another live pi's
1372
+ `attention`. A pi whose claim a live holder blocks looks again every second, so
1373
+ a second pi's open dialog is claimed once the first pi's has closed. A claim
1374
+ nobody alive holds is cleared by the home's next pi: a
1375
+ `question` whose holder is gone (a pi killed with its dialog open) when that pi
1376
+ starts, and a failed turn's, or a claim with no mark (a bridge from before the
1377
+ mark left it), at its first run; a pi that starts and ends with no run clears
1378
+ no failed turn. A pi that lives on clears a second pi's `question` whose holder
1379
+ is gone when its run ends, or at its next one. A session that ends on a failed turn leaves
1380
+ the claim and removes its mark. A clear the kernel does not take keeps the mark
1381
+ and is tried again at the bridge's next step, and a question's by itself too, a
1382
+ second later and then at growing waits up to a minute. Three limits: bridges are not fenced against each
1383
+ other, so one pi's clear that lands just after another pi's set leaves that
1384
+ pi's dialog with no claim until it closes; a failed turn that another pi's
1385
+ question replaced is not shown again when that dialog closes; and a dialog that
1386
+ opens before a pi's first run takes a failed turn an earlier session left with
1387
+ it. The mark is in the agent's own home and decides
1388
+ only claims the agent could set or clear itself, so it needs no protection from
1389
+ the agent, in a sandboxed home either. Every write is producer `oats.pi`'s: no
1390
+ other producer's claim is touched.
1391
+
1392
+ **A pi claim that outlives its dialog.** With no pi left running or starting in
1393
+ the home, a dead pi's `question` stays, and it holds every scheduled wake: the hold reads
1394
+ claims, not whether the session runs. For a home on a session provider that
1395
+ lasts until the claim is cleared, because a wake never starts such a home; a
1396
+ tmux home's next start voids it, as a session boundary voids every claim. A
1397
+ hold that runs long is a reason to look: run `oats instance waiting clear
1398
+ --producer oats.pi --home <home>` from anywhere. A mark left behind is removed
1399
+ by the home's next pi.
1400
+
1343
1401
  **Whether a home is covered** (oats.core 2.11.0). Spawn and launch hooks answer
1344
1402
  [`dialogClaims: "reported"`](#commands-and-hooks), so the home reads `wakeHold:
1345
1403
  "on-claims"`, only when they wrote these settings and the Claude Code this launch
@@ -1349,8 +1407,9 @@ reads `unknown`: an older Claude Code, no executable handed, a failed or
1349
1407
  unreadable `--version`, a settings file oats.core left alone, or a launch that
1350
1408
  runs another program than the hooks were handed. An earlier
1351
1409
  `reported` doesn't survive that, and a preview answers nothing. Every other
1352
- harness answers nothing too. A pi home reads `unknown`: an extension can open its
1353
- own dialog, and the kernel can't see which load. `reported` doesn't mean every
1410
+ harness answers nothing too. A pi home reads `unknown`: the bridge's claims hold
1411
+ a wake while one of its dialogs is open (above), but the kernel can't see
1412
+ whether that bridge is loaded, on which pi, or which screens fire no event. `reported` doesn't mean every
1354
1413
  dialog: [What a hold leaves open](schedules.md#what-a-hold-leaves-open) names what
1355
1414
  it can't see, the Claude dialogs that fire no hook among them.
1356
1415
 
@@ -2288,6 +2347,24 @@ from, never print it.
2288
2347
  problems. A refused spawn runs no hook and leaves no home; a refused
2289
2348
  start or restart runs no hook and stops nothing. A check that fails or
2290
2349
  answers outside these words is not ready.
2350
+ - **A preview asks it too, with the same planned launch**, so that a launch
2351
+ you would refuse does not read clean in its preview. `check` must only
2352
+ read, and must answer for a home that is not there:
2353
+ - A spawn's preview (`oats spawn --preview`) hands you the home's
2354
+ **planned path, which does not exist yet**, `trees` with its one planned
2355
+ tree and `protected` by name, none of them made. Treat an absent home
2356
+ and absent files as absent, not as an error. Your environment is the
2357
+ spawn's too; `OATS_SOUL` and `OATS_LEVEL` may name directories that are
2358
+ not there yet. Your script then runs from
2359
+ your package's tree in the deployment's module store, as it does for
2360
+ `oats readiness --soul`, not from a home's copy. A refusal fails the
2361
+ preview with the code the spawn would be refused with, and nothing is
2362
+ created. You are given what is left of the preview's budget, and never
2363
+ more than the spawn gives its check. A provider that lives in a member module, which runs only from
2364
+ a spawned home, is not asked: the preview says so in its `warnings`.
2365
+ - A launch's preview (`oats launch-config preview --home`) hands you the
2366
+ home as a start would. A refusal is a failed `backend` item in its
2367
+ `preflight`.
2291
2368
 
2292
2369
  ### What the kernel trusts in a provider home
2293
2370
 
@@ -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":[],
@@ -5147,9 +5175,10 @@ oats instance attention [--message=<text>] [--clear] --json
5147
5175
  on a turn an API error ended, or `question` for an error class that can
5148
5176
  open a menu, cleared when the session moves on). See
5149
5177
  [capabilities.md](capabilities.md), "oats.core: needs input".
5150
- - `oats.pi`: the `@awebai/oats-pi` bridge (`attention` on a turn a provider
5151
- error ended, once pi has stopped retrying, cleared by the next run). See
5152
- the same section, "A failed turn".
5178
+ - `oats.pi`: the `@awebai/oats-pi` bridge (`question` while a dialog an
5179
+ extension opened is open, its title as the message; `attention` on a turn
5180
+ a provider error ended, once pi has stopped retrying, cleared by the next
5181
+ run). See the same section, "A pi dialog" and "A failed turn".
5153
5182
  - `agent`: the instance itself, through `oats instance attention`, and
5154
5183
  only through it: `oats instance waiting --producer agent` is
5155
5184
  `E_BAD_ARGS`. **Agent claims are cleared only by the agent (`--clear`)
@@ -7666,7 +7695,13 @@ hold the listing up. A client has no use for it.
7666
7695
  **Launch preview.** `oats launch-config preview --home <abs> --json` of a
7667
7696
  provider home answers `command: null`, `argv: null` and `executable.path:
7668
7697
  null` (its launch is handed to the provider as data), `environment` by name,
7669
- and a `backend` item in `preflight`.
7698
+ and a `backend` item in `preflight`. The preview asks the provider's `check`
7699
+ with the launch that is planned, as the start will before it stops anything:
7700
+ a launch the provider would refuse is a failed `backend` item (`code`: the
7701
+ start's refusal, `E_BACKEND_*`), and `ok` is false. So is an allowance's path
7702
+ the start would refuse to make (`E_BACKEND_SANDBOX_HOST`); `warnings` carries
7703
+ the start's `sandbox allowances: …` lines. Nothing is stopped, started or
7704
+ created.
7670
7705
 
7671
7706
  ### Input
7672
7707
 
package/docs/desktop.md CHANGED
@@ -911,7 +911,12 @@ on a Soul roster card preselects that soul. Choose the task or message, repeat
911
911
  pattern and time zone; new agent jobs also offer harness, model, permissions
912
912
  and session backend. The list shows the next run, last observed outcome and
913
913
  whether the host scheduler is enabled. Pause, edit, run now and delete operate
914
- on that workspace's saved jobs. Launching an agent is reported separately from
914
+ on that workspace's saved jobs. The session backend is tmux or a session
915
+ provider the chosen soul offers (bb, where the soul has it). bb launches only
916
+ in full mode, so choosing it sets permissions to YOLO; a schedule saved without
917
+ it is marked **Refused at each run** or **Needs YOLO** in the list. A wake to
918
+ an agent on a session provider is sent as its session's input and never
919
+ starts a stopped one: it is delivered once the agent runs again. Launching an agent is reported separately from
915
920
  the end of its run; neither means its task succeeded. While a schedule's last
916
921
  run is **launch failed** or **invalid**, the sidebar's **Automations** shows a
917
922
  red dot, and a screen reader hears "Automations, a run failed"; it clears once
@@ -983,12 +983,18 @@ inherits it (awebai/oats#816):
983
983
  `writeFixtureExecutable(fx.base, path, content)`, which refuses a path
984
984
  outside the fixture's base, one reached through a link, and a symbolic or
985
985
  hard link at the path, with nothing written. `fx.inEnv` keeps the PATH of
986
- the process that runs the tests, so an in-process spawn records the
987
- harness it finds there, which on a machine with the harness installed is
988
- the person's own binary: a spawn whose recorded executable a test will
989
- rewrite runs with the fixture's PATH (`process.env.PATH = fx.env.PATH`,
990
- put back afterwards; its inert `pi`, `claude` and `codex` come first), and
991
- asserts `insideFixture(fx.base, launch.executable)`. The fixture's
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
992
998
  environment sets `HOME` and the XDG base directories under the base, and
993
999
  `GIT_CONFIG_NOSYSTEM=1`, `GIT_CONFIG_GLOBAL=/dev/null` and
994
1000
  `GIT_TERMINAL_PROMPT=0`, so no host git
@@ -41,7 +41,7 @@ arrives from.
41
41
  # oats-workspace.yaml: one default per slot, for every soul
42
42
  packages:
43
43
  oats.okf: v6.3.0
44
- oats.aweb: v1.47.0
44
+ oats.aweb: v1.48.0
45
45
  oats.linear: v1.0.1
46
46
  oats.jira: v1.0.1
47
47
  defaults:
@@ -97,7 +97,7 @@ operations in full.
97
97
  - **`oats.aweb-tasks`** (in the `oats.aweb` package from 1.31.0) fills the
98
98
  tasks slot with aweb tasks, acting as the instance's own `oats.aweb`
99
99
  identity in its default team. **An existing workspace opts in** by pinning
100
- `oats.aweb: v1.47.0` (the feature needs 1.31.0 or later), adding
100
+ `oats.aweb: v1.48.0` (the feature needs 1.31.0 or later), adding
101
101
  `tasks: { oats.aweb-tasks: { from: package } }` to `defaults`, and running
102
102
  `oats sync`. Only new spawns get it. A soul that names its own tasks
103
103
  provider in `capabilities:` (`oats.jira`, `oats.linear`) then holds two and
@@ -29,7 +29,7 @@ an author soul:
29
29
  ```yaml
30
30
  # oats-workspace.yaml
31
31
  packages:
32
- oats.framework: v1.28.0 # provides oats.core, oats.setup, oats.knowledge-theory
32
+ oats.framework: v1.29.0 # provides oats.core, oats.setup, oats.knowledge-theory
33
33
 
34
34
  # souls/<author-soul>/soul.yaml
35
35
  capabilities: