@awebai/oats 0.70.0 → 0.70.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/bin/oats.mjs 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
@@ -2288,6 +2288,24 @@ from, never print it.
2288
2288
  problems. A refused spawn runs no hook and leaves no home; a refused
2289
2289
  start or restart runs no hook and stops nothing. A check that fails or
2290
2290
  answers outside these words is not ready.
2291
+ - **A preview asks it too, with the same planned launch**, so that a launch
2292
+ you would refuse does not read clean in its preview. `check` must only
2293
+ read, and must answer for a home that is not there:
2294
+ - A spawn's preview (`oats spawn --preview`) hands you the home's
2295
+ **planned path, which does not exist yet**, `trees` with its one planned
2296
+ tree and `protected` by name, none of them made. Treat an absent home
2297
+ and absent files as absent, not as an error. Your environment is the
2298
+ spawn's too; `OATS_SOUL` and `OATS_LEVEL` may name directories that are
2299
+ not there yet. Your script then runs from
2300
+ your package's tree in the deployment's module store, as it does for
2301
+ `oats readiness --soul`, not from a home's copy. A refusal fails the
2302
+ preview with the code the spawn would be refused with, and nothing is
2303
+ created. You are given what is left of the preview's budget, and never
2304
+ more than the spawn gives its check. A provider that lives in a member module, which runs only from
2305
+ a spawned home, is not asked: the preview says so in its `warnings`.
2306
+ - A launch's preview (`oats launch-config preview --home`) hands you the
2307
+ home as a start would. A refusal is a failed `backend` item in its
2308
+ `preflight`.
2291
2309
 
2292
2310
  ### What the kernel trusts in a provider home
2293
2311
 
@@ -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":[],
@@ -7666,7 +7694,13 @@ hold the listing up. A client has no use for it.
7666
7694
  **Launch preview.** `oats launch-config preview --home <abs> --json` of a
7667
7695
  provider home answers `command: null`, `argv: null` and `executable.path:
7668
7696
  null` (its launch is handed to the provider as data), `environment` by name,
7669
- 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.
7670
7704
 
7671
7705
  ### Input
7672
7706
 
@@ -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
@@ -0,0 +1,70 @@
1
+ # OATS 0.70.1
2
+
3
+ Unreleased
4
+
5
+ A preview on a session provider now asks the provider's own readiness check,
6
+ so it no longer reads clean for a launch the provider then refuses. A
7
+ schedule's save asks the same, with the job's own `yolo`. tmux homes and their
8
+ previews are unchanged.
9
+
10
+ ## Upgrade
11
+
12
+ - **The Desktop and the CLI** can be upgraded in either order.
13
+ - **A scheduled or triggered spawn on a provider that launches only in full
14
+ mode (bb's)** needs `yolo: true` in its definition, or a launch
15
+ configuration that sets it. A job without it is now refused when saved, where
16
+ it used to fail at each run.
17
+
18
+ ## Changed
19
+
20
+ - **A spawn job on a session provider is checked by the provider when it is
21
+ saved.** A spawn's preview now asks a session provider's `check` with the
22
+ launch that is planned, and `oats schedule add`, `update` and `test` ask
23
+ that preview with the job's own launch selection, its `yolo` included
24
+ ([spawn](../schedules.md#kinds)). On a provider that launches only in full
25
+ mode:
26
+ - a job with `yolo: true` is saved and launches, as one whose launch
27
+ configuration sets yolo does (a build with the preview's new check and
28
+ without this change refused the job's own `yolo: true` on `add` and
29
+ `update`, and `oats schedule test` said its soul did not resolve: the
30
+ schedule's preview did not carry it);
31
+ - a job with no `yolo` is refused when saved (`E_SCHEDULE_INVALID`,
32
+ `details.code: "E_BACKEND_SANDBOXED_MODE"`), and `oats schedule test`
33
+ reports it, where it used to fail only at its run. One the
34
+ save did not ask the provider about (its soul was already spawned in
35
+ the deployment, or the provider comes from a member module, which a
36
+ preview does not ask) fails at each run, `launch-failed` with `errorCode:
37
+ "E_BACKEND_SANDBOXED_MODE"`, and leaves no home.
38
+
39
+ ## Fixed
40
+
41
+ - **A preview on a session provider no longer reads clean for a launch the
42
+ provider will refuse.** `oats spawn --preview` of a spawn on a session
43
+ provider read complete, with no problem and no warning, and the spawn was
44
+ then refused by the provider's readiness check and undone (with a provider
45
+ that launches only in full mode and no full-mode choice:
46
+ `E_BACKEND_SANDBOXED_MODE`). A preview now asks the provider's `check` with
47
+ the launch that is planned, as the spawn does before any hook runs
48
+ ([spawn preview](../desktop-cli-api.md), [check](../capabilities.md#check-optional)):
49
+ - a launch the provider would refuse fails the preview with the spawn's own
50
+ code and creates nothing; a provider that cannot be asked is
51
+ `E_BACKEND_NOT_READY`; one that outlasts the preview's budget leaves
52
+ `preflight.status: "timeout"`;
53
+ - `oats launch-config preview --home` of a provider home asks it too, and
54
+ shows a refusal as a failed `backend` item, with `ok: false`;
55
+ - a provider in a member module, which runs only from a spawned home, is
56
+ not asked: the preview says so in `warnings`.
57
+
58
+ For a provider's author: `check` may now be handed a home that does not
59
+ exist yet (a spawn's preview hands its planned path). It must only read,
60
+ and treat an absent home as absent.
61
+
62
+ ## Documentation
63
+
64
+ - **Schedules and triggers on a session provider**
65
+ ([Kinds](../schedules.md#kinds), [Triggers](../schedules.md#triggers)): a
66
+ scheduled or triggered spawn on a provider that launches only in full mode
67
+ needs `yolo: true` in its definition, or a launch configuration that sets
68
+ it; a wake is the input of a provider home's session, and never starts a
69
+ stopped provider home. Tests now cover a wake, a scheduled spawn and a
70
+ triggered spawn on a session provider.
package/docs/schedules.md CHANGED
@@ -171,11 +171,13 @@ refuses the key on a trigger.
171
171
  package soul the workspace offers, see `oats souls`), whether or not this
172
172
  deployment has spawned it before. `add` and `update` refuse a job whose
173
173
  `oats spawn <agent> --preview`, with the job's `launchConfig`, `harness`,
174
- `model`, `backend` and `repo`, fails (`E_SCHEDULE_INVALID`, field `agent`,
174
+ `model`, `yolo`, `backend` and `repo`, fails (`E_SCHEDULE_INVALID`, field `agent`,
175
175
  with spawn's own message and its code in `details.code`), or whose preview
176
176
  answer cannot be confirmed; a soul this deployment has already spawned is
177
177
  accepted without the preview. `agentsRoot`, when given, must be the deployment's `agents/` root; `repo`
178
- is the work repository, as `--repo`. `backend` is `tmux`; `backend: herdr`
178
+ is the work repository, as `--repo`. `backend` is `tmux`, or the name of a
179
+ [session provider](execution-targets.md#session-providers) of the soul's
180
+ capabilities; `backend: herdr`
179
181
  is refused (`E_HERDR_REMOVED`, naming the file and key: Herdr was removed in
180
182
  0.31.0), and a stored job that names it is reported invalid and never runs.
181
183
  `model` is a model id (a letter or
@@ -189,6 +191,23 @@ refuses the key on a trigger.
189
191
  trailing block naming the job and the minute and ending with `oats retire
190
192
  --self`. `wake` (`{cron, tz, message}`) attaches a wake schedule to each
191
193
  launched instance.
194
+
195
+ **On a session provider** the run's spawn launches through the provider
196
+ `backend` names. A provider that launches only in full mode (bb's does)
197
+ refuses every other launch at its
198
+ [check](capabilities.md#check-optional), `E_BACKEND_SANDBOXED_MODE`. A job
199
+ on such a provider needs `yolo: true` in its definition, or a launch
200
+ configuration that sets it: the job's `launchConfig`, or the deployment's
201
+ [default for the harness](configuration.md#the-harness-default). Without
202
+ it `add` and `update` refuse the job where they ask the preview
203
+ (`E_SCHEDULE_INVALID`, with `details.code: "E_BACKEND_SANDBOXED_MODE"`),
204
+ and `oats schedule test` reports it. A job the save did not ask the
205
+ provider about (its soul was already spawned here, so `add` and `update`
206
+ ask no preview; or the provider comes from a member module, which a
207
+ preview does not ask) fails at each run: the run is recorded
208
+ `launch-failed` with `errorCode: "E_BACKEND_SANDBOXED_MODE"` and the
209
+ provider's message, its spawn is undone and no home is left; the job tries
210
+ again at its next due minute.
192
211
  - **command** `{…, cwd, argv}` — runs an oats-only argv (`argv[0]` is `oats`,
193
212
  no shell; `oats schedule` itself is refused) in `cwd`, an existing directory
194
213
  inside the deployment. The runner tracks any instance the command's
@@ -221,6 +240,21 @@ refuses the key on a trigger.
221
240
  again only at due minutes, so a harness that keeps exiting is not restarted
222
241
  in a loop. Unobservable or still starting: skipped, delivery kept pending.
223
242
  Word wake messages so that receiving one again is harmless.
243
+
244
+ A home on a [session provider](execution-targets.md#session-providers) has
245
+ no terminal: the message is its session's input, sent once through the
246
+ provider, and a live claim holds it the same way. **A wake never starts a
247
+ provider home OATS stopped.** Its input is refused before any provider
248
+ call: the run is `skipped` with `errorCode: "E_SESSION_NOT_RUNNING"`, and
249
+ the delivery stays pending until the home is started (`oats session
250
+ start`). To a session that is lost (gone, and not stopped by OATS) the
251
+ input is a resume, on which the provider restarts the session, counted
252
+ against the home's cap
253
+ ([lost sessions](execution-targets.md#session-providers)). An input the provider itself refuses
254
+ (`E_SESSION_PROMPT_OPEN` while its session shows a prompt,
255
+ `E_SESSION_INPUT_QUEUED`) is `skipped` with that `errorCode`: nothing was
256
+ sent, and the pending delivery is tried again at every tick, then delivered
257
+ once.
224
258
  - **operation** `{…, operation, home}` — runs a provider operation
225
259
  (`<layer>:<name>`, one the capability filling that layer declares) in the
226
260
  instance at `home` through `oats operation run <layer>:<name> --home <home>`. The provider is whatever fills that layer
@@ -299,7 +333,12 @@ when the timer cannot reach it.
299
333
  request's title and body are untrusted and never reach the task. `teams` (optional) becomes the messaging capability's `join=`
300
334
  setting (`E_TRIGGER_TEAMS` when the soul has no messaging capability).
301
335
  `launchConfig`, `harness`, `model`, `yolo` and `backend` are as for
302
- schedules.
336
+ schedules. On a session provider that launches only in full mode (bb's
337
+ does) the spawn needs `yolo: true`, or a launch configuration that sets
338
+ it, as [a schedule's spawn](#kinds) does. Without it each event's spawn
339
+ fails (`spawn-failed`, `E_BACKEND_SANDBOXED_MODE`, kept as the trigger's
340
+ `lastError`), no home is created, and the event stays pending and is tried
341
+ again at each poll.
303
342
  - **The instance name** is spawn's own: `<stem>-<purpose>`, where the stem is
304
343
  the slug of the soul's agent name (a package soul's is
305
344
  `<package>--<soul>`, so its stem is long), read from one `oats spawn <soul>
package/docs/upgrading.md CHANGED
@@ -6,12 +6,12 @@ host that comes from it.
6
6
 
7
7
  ## Upgrading to the latest version
8
8
 
9
- The latest version is **OATS 0.70.0** ([release notes](release-notes/v0.70.0.md)).
10
- The 0.70.0 Desktop accepts OATS CLIs `>=0.26.0`, tested through 0.70: the
9
+ The latest version is **OATS 0.70.1** ([release notes](release-notes/v0.70.1.md)).
10
+ The 0.70.1 Desktop accepts OATS CLIs `>=0.26.0`, tested through 0.70: the
11
11
  Desktop and the CLI can be upgraded [in either order](#either-order-works).
12
12
 
13
13
  **First, read the `## Upgrade` section of every release after yours, up to
14
- 0.70.0,** in the [release notes](release-notes/): it says what to do before
14
+ 0.70.1,** in the [release notes](release-notes/): it says what to do before
15
15
  the CLI changes, and what else must change with it (the Desktop, another
16
16
  tool, a package pin). [Coming from an older version](#coming-from-an-older-version)
17
17
  names the releases that ask for more than the steps below. `oats version`
@@ -20,8 +20,8 @@ prints the version you have.
20
20
  Then, on each host:
21
21
 
22
22
  ```sh
23
- # 0. where the Desktop is installed: Desktop 0.70.0, in either order
24
- npm install -g @awebai/oats@0.70.0 # 1. the CLI
23
+ # 0. where the Desktop is installed: Desktop 0.70.1, in either order
24
+ npm install -g @awebai/oats@0.70.1 # 1. the CLI
25
25
  oats update # 2. in each deployment: the plan, then it asks before it runs
26
26
  oats doctor # 3. in the same deployment
27
27
  ```
@@ -217,6 +217,10 @@ of the Desktop and the CLI, and an optional package pin. A change a script
217
217
  must follow is in its release's Upgrade section whether or not it is listed
218
218
  here.
219
219
 
220
+ - **[0.70.1](release-notes/v0.70.1.md#upgrade):** a scheduled or triggered
221
+ spawn on a provider that launches only in full mode (bb's) needs `yolo:
222
+ true`, or a launch configuration that sets it; a job without it is now
223
+ refused when saved.
220
224
  - **[0.70.0](release-notes/v0.70.0.md#upgrade):** upgrade the Desktop with
221
225
  the CLI: a Desktop of 0.69.18 to 0.69.24 runs the 0.70.0 CLI in its
222
226
  reduced, above-tested mode until Desktop 0.70.0 is installed; a Desktop of
package/lib/core.mjs CHANGED
@@ -66,10 +66,43 @@ import { assertNoPartialUpgrade, packageRespawnWarning, packageUpgradeDrift, upg
66
66
  import { refuseHomeOfAnotherUser } from "./home-owner.mjs";
67
67
  import { oatsError, afterEndedSteps, afterFirstEffect, asKernelError, BEFORE_EFFECT_CODES, checkHolderByHand, errorCause, ifItDoesNotEnd, isAnswerCode, isDefect, isKernelCode, kernelCode, lifecycleBusy, nothingAfter, reportDefect, OWN_NAME_FAILURES, OWN_START_REMEDY, herdrInstanceBusy, herdrInstanceRemoved, herdrSettingRemoved, HERDR_REMOVED } from "./errors.mjs";
68
68
  import { envRows, recordedTeams } from "./teams.mjs";
69
+ import { safeText } from "./refused-text.mjs";
69
70
  import { PANE_PATH_FIX, harnessNotOnPanePath, harnessUnavailable, launchConfigAmbiguous, launchConfigUnknown, launchConfigUnknownFix, launchLayers, launchPreferenceUnmatched, launchPreferenceUnmatchedProblem, launchReport, selectionFrom } from "./launch-preference.mjs";
70
71
  import { shq, shellWord } from "./shell-word.mjs";
71
72
  import { CONFIG_DIR_VAR, HARNESS_FOLDER_VAR, claudeTrusts, codexTrustsRoot, harnessConfigFile, harnessTrustWarning, launchConfigFolder } from "./harness-trust.mjs";
72
73
  async function materializePreparedDefault(prepared, home) { const m = await import("./instance-resolution.mjs"); return m.materializePrepared(prepared, home); }
74
+ /** What a home's record says of the workspace and the teams, from the prepared resolution: the
75
+ * final record's, the spawn-in-progress marker's, and a preview's question to a session provider. */
76
+ const workspaceRecordOf = (prepared) => (prepared ? {
77
+ workspace: { key: prepared.discovery?.key ?? null, name: prepared.discovery?.workspace?.name ?? null, deployment: prepared.deployment ?? null, commit: prepared.discovery?.commit ?? null, resolution: prepared.resolution.revision, standalone: prepared.discovery?.standalone === true, soul: { id: preparedSoulIdOf(prepared.soulEntry), repoKey: prepared.soulEntry.repoKey, commit: prepared.soulEntry.commit, ...(typeof prepared.soulEntry.package === "string" ? { name: prepared.soulEntry.name, qualifiedName: prepared.soulEntry.qualifiedName, package: { id: prepared.soulEntry.package, version: prepared.soulEntry.version, commit: prepared.soulEntry.commit, digest: prepared.soulEntry.digest, path: prepared.soulEntry.path } } : {}) }, layers: layerRows(prepared.resolution) },
78
+ teams: envRows(prepared.resolution.teams ?? []),
79
+ defaultTeam: structuredClone(prepared.resolution.defaultTeam ?? null),
80
+ } : {});
81
+ /** The soul directory a home records and its hooks and provider calls are handed (OATS_SOUL): for
82
+ * a workspace soul its commit's directory in the per-commit cache, by real path, never the
83
+ * swappable `agents/<name>/soul` pointer; else what that pointer shows now; else `soulDir`.
84
+ * `planned` (a spawn's preview, which may have read the soul from a temporary copy): the
85
+ * per-commit directory the apply will record, though it is not fetched there yet. */
86
+ function homeSoulTargetOf(agent, prepared, soulDir, { planned = false } = {}) {
87
+ if (prepared?.soulEntry?.commit) {
88
+ const perCommit = join(agent._dir, "souls", String(prepared.soulEntry.commit).slice(0, 12));
89
+ if (existsSync(join(perCommit, "soul.yaml"))) return realpathSync(perCommit);
90
+ if (planned) return realPathOrNearest(perCommit);
91
+ }
92
+ // Not prepared (or the cache entry is absent): still never link a swappable pointer —
93
+ // when agents/<name>/soul is the kernel's pointer into souls/, link what it shows now.
94
+ try {
95
+ if (lstatSync(soulDir).isSymbolicLink()) {
96
+ const real = realpathSync(soulDir), soulsReal = realpathSync(join(dirname(soulDir), "souls"));
97
+ const rel = relative(soulsReal, real);
98
+ if (rel && !rel.startsWith("..") && !isAbsolute(rel) && !rel.includes(sep)) return real;
99
+ }
100
+ } catch { /* absent souls/ or unreadable link: record the soul dir itself */ }
101
+ return soulDir;
102
+ }
103
+ /** The verified tree of a package module in the deployment's module store (lib/operator-dispatch.mjs
104
+ * ensureModuleTree), for a spawn preview's question to a session provider: no home holds it yet. */
105
+ async function providerTreeDefault(prepared, module) { const m = await import("./operator-dispatch.mjs"); return m.ensureModuleTree(prepared.deployment, module, prepared.lock, { remoteOptions: prepared.remoteOptions }); }
73
106
  async function plannedSkillsDefault(prepared) { const m = await import("./instance-resolution.mjs"); return m.plannedPreparedSkills(prepared); }
74
107
  // Capability rows for a PREPARED spawn (workspace model): the one function that
75
108
  // turns a Resolution's modules into the row shape hooks/environment/requirements/
@@ -3140,9 +3173,11 @@ function requirementsWithArgsMessage(harness, providers, config, backend = "tmux
3140
3173
  * expected to have (paneEnvironment's shape, or a function giving it, called only when a check
3141
3174
  * needs a name the launch itself does not set); every check here reads it through the one answer
3142
3175
  * (launchEnvironment), and says so when it is not established. */
3143
- export function planLaunch({ home, instance, meta, contextDir, agentLike, selection = {}, launchConfigs, resolvedCfg, env = process.env, preview = false, noHooks = false, assertRoots, reselect = null, pane }) {
3176
+ export function planLaunch({ home, instance, meta, contextDir, agentLike, selection = {}, launchConfigs, resolvedCfg, env = process.env, preview = false, noHooks = false, assertRoots, reselect = null, pane, providerCheck = null }) {
3144
3177
  assertRoots?.();
3145
3178
  const problems = [];
3179
+ // (The home's session provider as it is bound below, for the preview's question to it.)
3180
+ let providerBound = null;
3146
3181
  const fail = (check, code, detail) => { if (!preview) throw oatsError(code, detail); problems.push({ check, ok: false, detail, code }); };
3147
3182
  // A recorded recipe is validated before anything is observed. A home without
3148
3183
  // one predates recipes: there is nothing this kernel plans from.
@@ -3186,7 +3221,7 @@ export function planLaunch({ home, instance, meta, contextDir, agentLike, select
3186
3221
  // The provider's own rules for this launch: the harness is one it runs, and no executable is named.
3187
3222
  // The home's modules as they are now, under the spawn's own selection: one name has one
3188
3223
  // meaning (E_BACKEND_AMBIGUOUS), and the harness is one the provider runs (E_BACKEND_HARNESS).
3189
- const bound = homeSessionProvider(home, meta, sessionProvider.capability, sessionProvider.backend);
3224
+ const bound = providerBound = homeSessionProvider(home, meta, sessionProvider.capability, sessionProvider.backend);
3190
3225
  let refusal = null;
3191
3226
  if (!bound.problem) { try { selectSessionBackend(sessionProvider.backend, Object.values(capabilityManifests(home)).map((m) => ({ id: m.capability, manifest: m })), harness, "nothing was stopped or started"); } catch (e) { if (!isKernelCode(e?.code)) throw e; refusal = e; } }
3192
3227
  if (bound.problem) fail("backend", "E_SESSION_START_FAILED", `${meta?.instance || instance || basename(home)} cannot be launched on session backend ${sessionProvider.backend}: ${bound.problem}; nothing was stopped or started`);
@@ -3293,9 +3328,35 @@ export function planLaunch({ home, instance, meta, contextDir, agentLike, select
3293
3328
  const { trustHome } = sessionProvider ? { trustHome: false } : launchFolderTrust({ harness, home, meta, yolo: recipe.yolo, launch: trustLaunch, env, configEnv, launchConfig: config?.name });
3294
3329
  const command = sessionProvider ? undefined : renderLaunchRecipe(recipe, { home, instance: instance || meta?.instance || basename(home), trustHome });
3295
3330
  const selectionSource = frozen ? (config?.frozen || (!config && !selection.launchConfig && !selection.harness) ? "frozen" : "config") : "config";
3331
+ // A preview of a launch on a session provider asks the provider what the start will ask it
3332
+ // (startProviderSession's askCheck): its `check`, with the launch that is planned, so a launch the
3333
+ // provider would refuse reads refused here and not ready. `check` only reads. `providerCheck`:
3334
+ // `{ sandboxSource }`, the caller's reading of the deployment's configuration (as a start's), from
3335
+ // the command that previews a launch; never from the start's own preview pass, which asks once
3336
+ // itself. Nothing is created: the allowances' paths are not made, nor the kernel's directory.
3337
+ const providerWarnings = [];
3338
+ if (preview && providerCheck && sessionProvider && providerBound?.binding && problems.every((c) => c.ok)) {
3339
+ try {
3340
+ const source = providerCheck.sandboxSource;
3341
+ let sandbox = { unavailable: source?.unavailable ?? "this preview did not resolve the deployment's configuration" };
3342
+ if (source && !source.unavailable) {
3343
+ const allowed = homeSandboxAllowances({ source, home: canonicalHomePath(home), moduleNames: Object.keys(isPlainObject(meta?.modules) ? meta.modules : {}) });
3344
+ for (const { capability, reason } of allowed.skipped ?? []) providerWarnings.push(`sandbox allowances: ${capability} adds no host: ${reason}`);
3345
+ sandbox = sandboxLaunchInput(allowed);
3346
+ // What the start refuses of the paths it would make (E_BACKEND_SANDBOX_HOST): refused here, with nothing made.
3347
+ const refused = sandboxWritePathsRefusal(sandbox.write);
3348
+ if (refused) throw refused;
3349
+ }
3350
+ const notReady = launchReadinessRefusal(providerBound.binding, { launch: plannedLaunch({ home: canonicalHomePath(home), harness, yolo: recipe.yolo, args: recipe.args, sandbox, preview: true }) });
3351
+ if (notReady) problems.push({ check: "backend", ok: false, detail: notReady.message, code: notReady.code });
3352
+ } catch (e) {
3353
+ if (!isKernelCode(e?.code)) throw e;
3354
+ problems.push({ check: "backend", ok: false, detail: e.message, code: e.code });
3355
+ }
3356
+ }
3296
3357
  // A preview states what the start will do; the start states it in its own output.
3297
3358
  const previewNotices = preview && !sessionProvider ? launchStartNotices(dirname(dirname(dirname(dirname(home)))), harness, command) : [];
3298
- return { recipe, command, trustHome, declaredEnv, removedEnv, harness, model: model || undefined, modelSource, yolo, config, executable, executablePaneSide, preflight: problems, ok: problems.every((c) => c.ok), selectionSource, frozen, launchChoice, warnings: [...(hooks.warnings || []), ...previewNotices], previewedHooks: hooks.previewed || [], volatileEnv: hooks.volatileEnv || [], ...(hooks.meta ? { hookMeta: hooks.meta } : {}), ...(hooks.dialogClaims ? { hookDialogClaims: hooks.dialogClaims } : {}) };
3359
+ return { recipe, command, trustHome, declaredEnv, removedEnv, harness, model: model || undefined, modelSource, yolo, config, executable, executablePaneSide, preflight: problems, ok: problems.every((c) => c.ok), selectionSource, frozen, launchChoice, warnings: [...(hooks.warnings || []), ...previewNotices, ...providerWarnings], previewedHooks: hooks.previewed || [], volatileEnv: hooks.volatileEnv || [], ...(hooks.meta ? { hookMeta: hooks.meta } : {}), ...(hooks.dialogClaims ? { hookDialogClaims: hooks.dialogClaims } : {}) };
3299
3360
  }
3300
3361
  /** The names a package probe of `harness` depends on: where its program is found and runs, the
3301
3362
  * home directory, and that harness's own selector. */
@@ -3408,10 +3469,11 @@ function homeTrees(home) {
3408
3469
  * home's modules (lib/home-integrity.mjs: what the kernel runs, and where the home's hooks point
3409
3470
  * the harness), the receipts, the claims and the provider calls in flight. Each is made here
3410
3471
  * when it is missing (a deployment's first home), so that a provider that refuses a launch for
3411
- * a missing one refuses a fault and never a first launch. Never derived from the home's record. */
3412
- function homeProtected(home) {
3472
+ * a missing one refuses a fault and never a first launch. Never derived from the home's record.
3473
+ * `create: false`: a preview's, which names the same directory and makes nothing. */
3474
+ function homeProtected(home, { create = true } = {}) {
3413
3475
  const paths = [instancesRetirementRoot(dirname(canonicalHomePath(home)))];
3414
- for (const path of paths) mkdirSync(path, { recursive: true, mode: 0o700 });
3476
+ if (create) for (const path of paths) mkdirSync(path, { recursive: true, mode: 0o700 });
3415
3477
  return paths;
3416
3478
  }
3417
3479
  function providerLaunchInput({ home, instance, recipe, env: hostEnv, removed = [], previous = null, sandbox }) {
@@ -3462,8 +3524,12 @@ const capabilityRuntimeRows = (resolvedCfg) => resolvedCfg.capabilities.map((cap
3462
3524
  * `{ harness, yolo, args, sandbox, trees, protected }`. `args` are the launch configuration's own: the
3463
3525
  * arguments a capability's hooks contribute are not known yet, and reach the launch input only.
3464
3526
  * `trees` and `protected` are the launch input's (homeTrees, homeProtected): a provider that
3465
- * would refuse a launch for either refuses it here, before a restart stops anything. */
3466
- const plannedLaunch = ({ home, harness, yolo, args, sandbox }) => ({ harness, yolo: yolo ?? null, args: [...(args || [])], ...(sandbox ? { sandbox } : {}), trees: homeTrees(home), protected: homeProtected(home) });
3527
+ * would refuse a launch for either refuses it here, before a restart stops anything.
3528
+ * `preview`: asked by a command that creates nothing (a spawn's preview, whose home does not
3529
+ * exist yet; a launch's): the same paths, with nothing made, and for a home that is not there
3530
+ * the one tree every home has. */
3531
+ const plannedLaunch = ({ home, harness, yolo, args, sandbox, preview = false }) => ({ harness, yolo: yolo ?? null, args: [...(args || [])], ...(sandbox ? { sandbox } : {}),
3532
+ trees: preview && !existsSync(home) ? [join(home, "work")] : homeTrees(home), protected: homeProtected(home, { create: !preview }) });
3467
3533
  /** A home's independent session receipt, read to be written again with another `runtime` → `{ path,
3468
3534
  * baseline }`. Refused as every writer of it refuses: E_RUNTIME_ENDPOINT_UNKNOWN for a receipt that
3469
3535
  * is missing, unreadable, of another home, or that authorises nothing. */
@@ -3774,7 +3840,7 @@ export async function spawnInstanceAsync(root, agent, o = {}) {
3774
3840
  const it = spawnBody(root, agent, o);
3775
3841
  let step = it.next();
3776
3842
  while (!step.done) {
3777
- // The single yield hands back a promise-producing thunk; await it and feed the
3843
+ // Each yield hands back a promise-producing thunk; await it and feed the
3778
3844
  // result (or throw the failure) back into the body.
3779
3845
  try { const value = await step.value(); step = it.next(value); }
3780
3846
  catch (e) { step = it.throw(e); }
@@ -4354,6 +4420,44 @@ function* spawnBody(root, agent, o = {}) {
4354
4420
  if (suggesting) paneCwd = home;
4355
4421
 
4356
4422
  if (existsSync(directoryRollbackPath(homeReal))) throw oatsError("E_WORK_INSPECTION_FAILED", `directory cleanup is still owed for ${home}; restore and retire the retained home before reusing its name`);
4423
+ // A preview of a spawn on a session provider asks the provider what the apply will ask it before
4424
+ // any hook runs (below, `refusedBeforeHooks`): its `check`, with the launch that is planned. A
4425
+ // launch the provider would refuse fails the preview with the apply's own code, as every other
4426
+ // refusal of a backend does; nothing is created. `check` only reads.
4427
+ // - The home does not exist yet: the check is handed its planned path, and the kernel's
4428
+ // directory (`protected`) by name, not made.
4429
+ // - The provider's script runs from its package's verified tree in the deployment's module
4430
+ // store (as `oats readiness --soul` runs it), fetched there when it is absent. A provider in
4431
+ // a member module runs only from a spawned home: the preview says it was not asked.
4432
+ // - It runs within what is left of the preview's one budget; a provider that does not answer
4433
+ // in it leaves the preflight a `timeout`.
4434
+ // A provider that declares no check has nothing to be asked, here as at the apply.
4435
+ let previewCheckWarning = null;
4436
+ if (o.preview === true && launch && provider && provider.provider?.commands?.check) {
4437
+ const said = `${provider.capability}'s session provider ${backend}`, notAsked = (why) => `${said} was not asked whether it can take this launch (${why}): the spawn asks it before any hook runs, and refuses what it refuses`;
4438
+ const module = (o.prepared.resolution?.modules || []).find((m) => m.name === provider.capability);
4439
+ let dir = null, unread = null;
4440
+ if (module?.from?.kind === "package") { try { dir = yield () => (o.providerTree ?? providerTreeDefault)(o.prepared, module); } catch (e) { unread = safeText(e?.message ?? e, 300); } }
4441
+ const left = preflightStarted + preflightBudgetMs - Date.now();
4442
+ if (module?.from?.kind !== "package") previewCheckWarning = notAsked("a provider in a member module runs only from a spawned home");
4443
+ else if (!dir) previewCheckWarning = notAsked(`its package's tree could not be read${unread ? `: ${unread}` : ""}`);
4444
+ else if (left <= 0) preflight.status = "timeout";
4445
+ else {
4446
+ const rows = capabilityRuntimeRows(resolvedCfg), row = rows.find((c) => c.id === provider.capability);
4447
+ // The provider's environment is the apply's: the soul directory the home will record (not a
4448
+ // preview's temporary copy of the soul), and the capability's level, which is the home.
4449
+ const planned = { agent: agent.name, instance, home, soulDir: homeSoulTargetOf(agent, o.prepared, soulDir, { planned: true }), harness, capabilityRuntime: rows, ...workspaceRecordOf(o.prepared) };
4450
+ const binding = { home, meta: planned, capability: provider.capability, name: backend, provider: provider.provider, moduleDir: dir, digest: null, soulId: preparedSoulIdOf(o.prepared.soulEntry),
4451
+ cap: { id: provider.capability, layer: row?.layer ?? "", level: row?.level ?? home, settings: isPlainObject(row?.settings) ? row.settings : {}, settingsOrigins: isPlainObject(row?.settingsOrigins) ? row.settingsOrigins : {} } };
4452
+ // (Never longer than the apply gives it: a check slower than its own limit is refused there.)
4453
+ const own = sessionProviderTimeout("check");
4454
+ const notReady = launchReadinessRefusal(binding, { timeoutMs: Math.min(left, own), launch: plannedLaunch({ home, harness, yolo, args: launchConfig?.args, sandbox: sandboxLaunchInput(sandbox), preview: true }) });
4455
+ // Ended by the budget: the preflight did not finish. Ended by its own limit: the apply's refusal.
4456
+ if (notReady?.timedOut && left <= own) preflight.status = "timeout";
4457
+ else if (notReady) throw Object.assign(oatsError(notReady.code, `${instance} would not be launched: ${notReady.message}; nothing was created`), { details: { backend, capability: provider.capability } });
4458
+ }
4459
+ preflight.elapsedMs = Date.now() - preflightStarted;
4460
+ }
4357
4461
  // K6: everything a spawn decides is decided by here — and nothing has been
4358
4462
  // touched. Branch/base for a worktree are named now (not after mkdir) so the
4359
4463
  // preview and the apply agree on them; `o.baseRef` selects the start point.
@@ -4425,7 +4529,7 @@ function* spawnBody(root, agent, o = {}) {
4425
4529
  const preparedSettingsOrigins = Object.fromEntries(o.prepared.resolution.modules.map((m) => [m.name, structuredClone(o.prepared.resolution.payloadOrigins?.[m.name] ?? {})]));
4426
4530
  // The preview's warnings are strings: the launchPromptAnswers notice, then what a module declares and this kernel ignores.
4427
4531
  // The development-channel statement is the apply's: no launch hook runs here, so the argv is unknown.
4428
- const previewWarnings = [...(launchPromptNotice ? [launchPromptNotice] : []), ...contractWarningMessages(resolutionContractWarnings(o.prepared.resolution)), ...[previewReadWarning()].filter(Boolean)];
4532
+ const previewWarnings = [...(launchPromptNotice ? [launchPromptNotice] : []), ...contractWarningMessages(resolutionContractWarnings(o.prepared.resolution)), ...[previewReadWarning(), previewCheckWarning].filter(Boolean)];
4429
4533
  const preparedSettings = Object.fromEntries(o.prepared.resolution.modules.map((m) => [m.name, structuredClone(o.prepared.resolution.payloads?.[m.name] && typeof o.prepared.resolution.payloads[m.name] === "object" ? o.prepared.resolution.payloads[m.name] : {})]));
4430
4534
  return deliver({
4431
4535
  // Team model v2: the soul's teams here (unmapped rows included) and its default — the choice a
@@ -4606,22 +4710,7 @@ function* spawnBody(root, agent, o = {}) {
4606
4710
  // including a preview's). The record names ITS commit's directory by realpath — never
4607
4711
  // the pointer — so a later fetch can move "current" without changing what a running
4608
4712
  // instance's hooks see (decision 7); the OKF hook's owner pin stays valid.
4609
- let homeSoulTarget = soulDir;
4610
- if (o.prepared?.soulEntry?.commit) {
4611
- const perCommit = join(agent._dir, "souls", String(o.prepared.soulEntry.commit).slice(0, 12));
4612
- if (existsSync(join(perCommit, "soul.yaml"))) homeSoulTarget = realpathSync(perCommit);
4613
- }
4614
- if (homeSoulTarget === soulDir) {
4615
- // Not prepared (or the cache entry is absent): still never link a swappable pointer —
4616
- // when agents/<name>/soul is the kernel's pointer into souls/, link what it shows now.
4617
- try {
4618
- if (lstatSync(soulDir).isSymbolicLink()) {
4619
- const real = realpathSync(soulDir), soulsReal = realpathSync(join(dirname(soulDir), "souls"));
4620
- const rel = relative(soulsReal, real);
4621
- if (rel && !rel.startsWith("..") && !isAbsolute(rel) && !rel.includes(sep)) homeSoulTarget = real;
4622
- }
4623
- } catch { /* absent souls/ or unreadable link: record the soul dir itself */ }
4624
- }
4713
+ const homeSoulTarget = homeSoulTargetOf(agent, o.prepared, soulDir);
4625
4714
  if (!existsSync(join(home, "CLAUDE.md"))) symlinkSync("AGENTS.md", join(home, "CLAUDE.md"));
4626
4715
 
4627
4716
  // Skills: module skills were copied WHOLE and FLAT into <home>/.agents/skills/<skill>/
@@ -4837,11 +4926,7 @@ function* spawnBody(root, agent, o = {}) {
4837
4926
  // rows only) and the default, recorded as EVIDENCE beside `providers` (never inside that
4838
4927
  // capability-keyed map). A home's hooks and operations get the LIVE set (liveTeams); this is
4839
4928
  // what they fall back to when the workspace cannot answer.
4840
- const workspaceRecord = o.prepared ? {
4841
- workspace: { key: o.prepared.discovery?.key ?? null, name: o.prepared.discovery?.workspace?.name ?? null, deployment: o.prepared.deployment ?? null, commit: o.prepared.discovery?.commit ?? null, resolution: o.prepared.resolution.revision, standalone: o.prepared.discovery?.standalone === true, soul: { id: preparedSoulIdOf(o.prepared.soulEntry), repoKey: o.prepared.soulEntry.repoKey, commit: o.prepared.soulEntry.commit, ...(typeof o.prepared.soulEntry.package === "string" ? { name: o.prepared.soulEntry.name, qualifiedName: o.prepared.soulEntry.qualifiedName, package: { id: o.prepared.soulEntry.package, version: o.prepared.soulEntry.version, commit: o.prepared.soulEntry.commit, digest: o.prepared.soulEntry.digest, path: o.prepared.soulEntry.path } } : {}) }, layers: layerRows(o.prepared.resolution) },
4842
- teams: envRows(o.prepared.resolution.teams ?? []),
4843
- defaultTeam: structuredClone(o.prepared.resolution.defaultTeam ?? null),
4844
- } : {};
4929
+ const workspaceRecord = workspaceRecordOf(o.prepared);
4845
4930
  // #796: the `worktree` hooks this spawn fires (work: worktree only), their run, and the
4846
4931
  // in-progress marker that covers a parent killed while its spawn or worktree hooks run.
4847
4932
  const treeHooks = work === "worktree" ? worktreeHooksOf(resolvedCfg.capabilities) : [];
package/lib/schedule.mjs CHANGED
@@ -610,8 +610,8 @@ export function resolveScheduledAgent(ws, def) {
610
610
  /** The save-time check of a local spawn job's soul (`add`, `update`): refuse what `oats spawn`
611
611
  * would refuse. A soul already under the agents root is accepted without a child, so offline
612
612
  * adds and stale cached souls stay accepted; any other name goes through spawn's own preview,
613
- * with the job's selectors (a selector the run needs, such as its repo, would otherwise fail
614
- * the preview's checks). */
613
+ * with the job's selectors (a selector the run needs, such as its repo or its yolo, would
614
+ * otherwise fail the preview's checks). */
615
615
  function confirmScheduledSoul(ws, def, io) {
616
616
  const { root, discover } = resolveScheduledAgent(ws, def);
617
617
  if (findAgent(root, def.agent)) return;
@@ -704,7 +704,9 @@ export function workspaceSpawnContext(ws) {
704
704
  catch (e) { return { kind: "local", local: null, dir: ws, error: { code: e.code || "E_WORKSPACE_SCHEMA", message: e.message } }; }
705
705
  }
706
706
  /** The `oats spawn` selectors a spawn job's run passes (beside its purpose, task and launch
707
- * flags), so a preview checks what the run will: one builder for the run and its previews.
707
+ * flag), its yolo among them, so a preview checks what the run will: one builder for the run
708
+ * and its previews. (The yolo is the run's own: a session provider's check is asked with the
709
+ * launch that is planned, and one that launches only in full mode refuses a job by it.)
708
710
  * Every value travels as ONE `--flag=value` token. */
709
711
  function spawnSelectorArgs(opts) {
710
712
  const argv = [];
@@ -713,6 +715,7 @@ function spawnSelectorArgs(opts) {
713
715
  if (opts.model) argv.push(`--model=${opts.model}`);
714
716
  if (opts.backend) argv.push(`--backend=${opts.backend}`);
715
717
  if (opts.repo) argv.push(`--repo=${opts.repo}`);
718
+ if (opts.yolo === true) argv.push("--yolo"); else if (opts.yolo === false) argv.push("--no-yolo");
716
719
  return argv;
717
720
  }
718
721
  /** The kernel's own `oats spawn <agent> --preview --json` in the deployment, with the job's
@@ -751,7 +754,6 @@ function spawnViaCli(ws, root, agent, opts, context, io) {
751
754
  // the soul is the one positional, and an option-shaped one is refused.
752
755
  if (String(agent.name).startsWith("-")) throw scheduleError("E_SCHEDULE_INVALID", `agent: ${JSON.stringify(agent.name)} is not a soul name`, { field: "agent" });
753
756
  const argv = ["spawn", agent.name, `--dir=${context.dir}`, ...(opts.discover ? [] : [`--agents-root=${root}`]), `--purpose=${opts.purpose}`, "--json", ...spawnSelectorArgs(opts)];
754
- if (opts.yolo === true) argv.push("--yolo"); else if (opts.yolo === false) argv.push("--no-yolo");
755
757
  if (opts.launch === false) argv.push("--no-launch");
756
758
  // The task is multi-line text of arbitrary size: it travels as a private file, never in argv.
757
759
  mkdirSync(join(stateDir(ws), "tasks"), { recursive: true });
@@ -502,7 +502,8 @@ const codeMessages = (list) => Array.isArray(list) && list.every((x) => exactKey
502
502
  export function checkProviderSession(binding, input, { io, timeoutMs = sessionProviderTimeout("check") } = {}) {
503
503
  if (!binding.provider.commands.check) return null;
504
504
  const answer = callSessionProvider(binding, "check", input, { io, timeoutMs });
505
- if (!answer.ok) return { unavailable: providerSaid(answer) };
505
+ // (`timedOut`: it did not answer in the time it was given, which a preview counts against its budget.)
506
+ if (!answer.ok) return { unavailable: providerSaid(answer), ...(answer.timedOut ? { timedOut: true } : {}) };
506
507
  const r = answer.result;
507
508
  const sound = exactKeys(r, ["status", "problems"], ["warnings"]) && CHECK_STATUSES.includes(r.status) && codeMessages(r.problems) && (r.warnings === undefined || codeMessages(r.warnings)) && !(r.status === "ready" && r.problems.length);
508
509
  if (!sound) return { unavailable: `${binding.capability}'s session provider ${binding.name} answered check with a result that is not { status, problems, warnings? } in the readiness words` };
@@ -517,12 +518,13 @@ export function checkProviderSession(binding, input, { io, timeoutMs = sessionPr
517
518
  * is planned, `{ harness, yolo, args, sandbox }` as its launch input will carry them, so a provider
518
519
  * can refuse HERE what it would refuse at the launch (a session it would sandbox whose allowances
519
520
  * are `unavailable` or have `missing` entries: only it knows its mode), before a restart stops
520
- * anything. */
521
- export function launchReadinessRefusal(binding, { io, launch } = {}) {
522
- const checked = checkProviderSession(binding, { home: binding.home, soul: null, settings: binding.cap.settings, ...(launch ? { launch } : {}) }, { io });
521
+ * anything. `timeoutMs`: a preview's, what is left of its budget; the refusal of a provider that
522
+ * did not answer in time carries `timedOut`. */
523
+ export function launchReadinessRefusal(binding, { io, launch, timeoutMs } = {}) {
524
+ const checked = checkProviderSession(binding, { home: binding.home, soul: null, settings: binding.cap.settings, ...(launch ? { launch } : {}) }, { io, ...(timeoutMs === undefined ? {} : { timeoutMs }) });
523
525
  if (checked === null || checked.result?.status === "ready") return null;
524
526
  const said = `${binding.capability}'s session provider ${binding.name}`;
525
- if (checked.unavailable) return { code: "E_BACKEND_NOT_READY", message: `${said} is not ready: its readiness could not be read (${checked.unavailable})` };
527
+ if (checked.unavailable) return { code: "E_BACKEND_NOT_READY", message: `${said} is not ready: its readiness could not be read (${checked.unavailable})`, ...(checked.timedOut ? { timedOut: true } : {}) };
526
528
  const own = checked.result.problems.find((x) => /^E_BACKEND_[A-Z0-9_]{1,50}$/.test(x.code));
527
529
  return { code: own?.code ?? "E_BACKEND_NOT_READY", message: `${said} is not ready (${checked.result.status})${checked.result.problems.length ? `: ${checked.result.problems.map((x) => `${x.code}: ${x.message}`).join("; ")}` : ""}` };
528
530
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@awebai/oats",
3
- "version": "0.70.0",
3
+ "version": "0.70.1",
4
4
  "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
5
5
  "keywords": [
6
6
  "agents",