@awebai/oats 0.24.2 → 0.24.4

package/bin/oats.mjs

@@ -49,6 +49,10 @@ import { receiveAttachment, uploadAttachment, readStreamBounded, MAX_ATTACHMENT_
 import { capturedSelector } from "../lib/captured-selector.mjs";
 import { inspectCapturedPiOutcome } from "../lib/captured-pi-host.mjs";
 import { readCapturedResolution } from "../lib/captured-resolutions.mjs";
+import { readLock3 } from "../lib/portable-lock.mjs";
+import { oatsError } from "../lib/errors.mjs";
+import { readPortableBytes } from "../lib/portable-files.mjs";
+import { canonicalJson, parseStrictJson } from "../lib/portable-values.mjs";
 import { readPortablePreparationRequest } from "../lib/portable-onboarding-request.mjs";
 import { portableScope } from "../lib/portable-state.mjs";
 import { CAPTURED_OPERATION_TIMEOUT_MS, runCapturedOperationProcess } from "../lib/captured-operation-process.mjs";
@@ -99,15 +103,40 @@ const jsonOk = (result) => { console.log(JSON.stringify({ schemaVersion: 1, ok:
 
 function inspectOnboardingCmd() {
   const fail = (code, message) => JSON_MODE ? jsonFail(code, message) : die(message);
-  let file;
+  const values = new Map();
   for (let index = 1; index < args.length; index++) {
     if (args[index] === "--json") continue;
-    if (args[index] !== "--request" || file !== undefined || !args[index + 1] || args[index + 1].startsWith("--")) fail("E_BAD_ARGS", "source inspection accepts one --request <absolute-json> and --json only");
-    file = args[++index];
+    const key = args[index];
+    if (!["--request", "--emit-prepare-request"].includes(key) || values.has(key) || !args[index + 1] || args[index + 1].startsWith("--")) fail("E_BAD_ARGS", "source inspection accepts one --request <absolute-json>, optional --emit-prepare-request <new-absolute-json>, and --json");
+    values.set(key, args[++index]);
   }
   try {
-    const input = readPortablePreparationRequest({ file });
-    const result = inspectPortableOnboarding(input);
+    const output = values.get("--emit-prepare-request");
+    let parent;
+    const checkOutput = () => {
+      if (!isAbsolute(output) || resolve(output) !== output || output.includes("\0")) throw oatsError("E_BAD_ARGS", "prepare-request output needs a normalized absolute path");
+      let stat;
+      try {
+        stat = lstatSync(dirname(output));
+        if (!stat.isDirectory() || realpathSync(dirname(output)) !== dirname(output)) throw new Error();
+      } catch { throw oatsError("E_BAD_ARGS", "prepare-request output parent must be an existing real directory"); }
+      if (parent && (parent.dev !== stat.dev || parent.ino !== stat.ino)) throw oatsError("selection-changed", "prepare-request output parent changed during inspection");
+      try { lstatSync(output); }
+      catch (error) { if (error.code === "ENOENT") return stat; throw oatsError("E_BAD_ARGS", "prepare-request output could not be checked"); }
+      throw oatsError("E_BAD_ARGS", "prepare-request output already exists; choose a new file (nothing overwritten)");
+    };
+    if (output !== undefined) parent = checkOutput();
+    const input = readPortablePreparationRequest({ file: values.get("--request") });
+    const { prepareRequest, ...view } = inspectPortableOnboarding(input, { includePrepareRequest: output !== undefined });
+    let result = view;
+    if (output !== undefined) {
+      checkOutput();
+      try { writeFileSync(output, canonicalJson(prepareRequest) + "\n", { flag: "wx", mode: 0o600 }); }
+      catch { throw oatsError("E_BAD_ARGS", "prepare-request output could not be created exclusively; no existing file was overwritten"); }
+      const deployment = view.deployment.deployment.path;
+      result = { ...view, prepareRequestFile: output, effects: { ...view.effects, requestFileWrite: true,
+        deploymentWrites: output === deployment || output.startsWith(deployment + sep) } };
+    }
     if (JSON_MODE) jsonOk(result); else console.log(JSON.stringify(result, null, 2));
   } catch (error) { fail(error.code || "E_INSPECT_FAILED", error.message); }
 }
@@ -142,7 +171,12 @@ function prepareCmd() {
     // Pass the whole request to the one public validator/resolver. Unknown
     // fields are refused there, never filtered or filled from ambient state.
     const result = prepareCapturedComposition(input);
-    if (!result.resolution) fail("needs-configuration", "preparation is incomplete; no executable resolution was published", result);
+    if (!result.resolution) {
+      const summary = "preparation is incomplete; no executable resolution was published";
+      const reasons = (result.problems ?? []).filter(p => p.key !== undefined || (p.slot && p.capability))
+        .map(p => `[${p.slot && p.capability ? `${p.capability}/${p.slot}` : p.code}] ${p.key === undefined ? "" : `${JSON.stringify(p.key)}: `}${p.message}`);
+      fail("needs-configuration", JSON_MODE ? summary : [summary, ...reasons].join("\n"), result);
+    }
     if (JSON_MODE) jsonOk(result); else console.log(JSON.stringify(result, null, 2));
   } catch (error) { fail(error.code || "E_PREPARE_FAILED", error.message); }
 }
@@ -2446,6 +2480,28 @@ function trust() {
   if (!id || id.startsWith("--")) { cmdFail("E_USAGE", "usage: oats trust <capability> [--dir <dir>] | oats trust <package> --all-capabilities [--dir <dir>]"); return; }
   const dir = dirFlag();
   const all = args.includes("--all-capabilities");
+  // A v3 deployment needs an EXPLICIT immutable artifact-set selection. Never
+  // guess one or reinterpret its lock through the classic approval engine.
+  try {
+    for (const scope of lockLevelsUp(dir).reverse()) {
+      // Discriminate with the shared bounded decoder only. Classic readers
+      // retain all v1/v2 validation, including implicit (versionless) v1 locks.
+      let version;
+      try { version = parseStrictJson(readPortableBytes(join(scope, OATS_LOCK_FILE)))?.lockfileVersion; }
+      catch { continue; } // Let the existing classic reader diagnose its input.
+      if (version !== 3) continue;
+      const portable = readLock3(scope).lock;
+      if (!portable) throw oatsError("selection-changed", "selection lock disappeared; repeat explicit trust selection");
+      const sets = [...new Set(Object.values(portable.selections).map(row => row.available).filter(key => key && Object.hasOwn(portable.artifactSets[key].capabilities, id)))].sort();
+      const commands = sets.map(artifactSet => ({ artifactSet,
+        command: `oats trust ${shellQuote(id)} --deployment ${shellQuote(scope)} --artifact-set ${shellQuote(artifactSet)}` }));
+      const message = commands.length && !all
+        ? `lock v3 requires exact artifact-set approval; run ${commands.map(item => item.command).join(" or ")}`
+        : `lock v3 approvals are per capability; use prepare's selections[].artifactSet for each capability in approvalRequired[]: oats trust <capability> --deployment ${shellQuote(scope)} --artifact-set <sha256-artifact-set>`;
+      if (JSON_MODE) jsonFail("needs-configuration", message, { deployment: scope, commands });
+      die(message);
+    }
+  } catch (error) { cmdFail(error.code || "invalid-lock", error.message); return; }
   // Package-backed approval path (per-capability, or explicit bulk on a package id).
   let pkgs, locks;
   try { pkgs = listInstalledPackages(dir); locks = readPackageLocks(dir); } catch (e) { cmdFail(e.code || "invalid-lock", e.message || e); return; }
@@ -5361,8 +5417,10 @@ The turn record (core — every conversation captured, searchable, replicated):
                                             packages/experimental/README.md
 
   oats inspect --request <absolute-json-file> [--json]
-                                            read-only fresh source/workspace/member metadata;
-                                            no current config, provider execution or preparation authority
+      [--emit-prepare-request <new-absolute-json-file>]
+                                            fresh source/workspace/member metadata; optional private
+                                            request export uses the existing fresh-request builder;
+                                            no provider execution or preparation authority
   oats prepare --request <absolute-json-file> [--json]
                                             complete public preparation input; no mixed flags,
                                             inherited binding, implicit setup or launch authority
@@ -5374,6 +5432,10 @@ The turn record (core — every conversation captured, searchable, replicated):
                                             same preparation through workspace imports
   oats inspect --deployment <abs> --resolution <id> [--composition] [--json]
       [--helper <exact-map-key>]             inspect retained source/helper inputs, not today's configuration
+  oats trust <capability> --deployment <abs> --artifact-set <sha256-…> [--json]
+                                            approve one exact prepared artifact; use each
+                                            selections[].artifactSet for capability ids
+                                            in prepare's approvalRequired[] at that selection
   oats trust <capability> --deployment <abs> --resolution <id> [--json]
                                             explicitly approve that exact captured artifact
   oats <namespace> <command> --deployment <abs> --resolution <id> -- [args…]

package/docs/capability-manifest.schema.json

@@ -178,7 +178,21 @@
         "version": { "const": 1 },
         "normalize": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
         "bind": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
-        "check": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" }
+        "check": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+        "reasons": {
+          "description": "Fixed nonsecret diagnostic strings allowed across the binding wire by exact match only. 1-64 unique printable ASCII strings of 1-200 characters, no braces/interpolation, operator values or paths. Omission uses the kernel's per-capability compatibility list when available; an invalid declaration never falls back.",
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 64,
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 1, "maxLength": 200, "not": { "pattern": "[{}]|[^\\x20-\\x7e]" } }
+        },
+        "keys": {
+          "description": "Owned operator-key declarations: exact names or trailing-dot namespaces, no other pattern syntax. Kernel 0.24.4 validates shape only; filtering, overlap checks and ownership attribution are deferred to 0.25. Providers must ignore foreign keys themselves.",
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]*\\.?$(?![\\s\\S])" }
+        }
       }
     },
     "operations": {

package/docs/design/2026-09-16-provider-binding-wire.md

@@ -36,7 +36,34 @@ result. All structured responses exit 0: transport completed, while `ok` is the
 semantic outcome. Nonzero exit/signal/timeout is transport failure. Allowed error/problem codes are needs-configuration, requirement-conflict,
 invalid-binding, authorization-required, host-requirement-missing,
 provider-unavailable and provider-not-qualified. Optional provider error/problem
-`message` is permitted but never forwarded by the kernel.
+`message` is permitted. The 0.24.4 follow-up retains it ONLY when it exactly
+matches a fixed nonsecret reason in the VERIFIED selected capability manifest's
+optional `binding.reasons` array: **1–64 unique strings**, each **1–200 printable
+ASCII characters**, with no braces/interpolation markers. If the field is absent,
+the kernel's reviewed per-capability compatibility list applies; a present invalid
+or empty declaration refuses, never falls back. No trimming, Unicode normalization,
+interpolation, prefix matching, operator values, paths, or unlisted provider output
+cross this boundary. Code-only replies
+and unknown/unlisted messages keep the existing kernel template fallback.
+
+The allowlist is out-of-band kernel input, never declared by a provider response.
+Exact artifact approval is still required BEFORE invoking the codec. The broker
+preserves the vetted message and preparation rechecks it against the same selected
+manifest, retaining slot/capability/origins. JSON and human CLI diagnostics surface
+the reason; human output also shows an existing choice `key` when provided. This
+changes no readiness status, launch authority, credential contract or wire version.
+Older kernels reject the new optional manifest fields; providers declaring them
+must floor on the reasons-capable **0.24.4** kernel. The compatibility list serves
+older manifests, not a way around declaration validation. It includes the complete
+30-message aweb1.11.0 codec vocabulary (including non-ready check reasons) and the
+seven OKF2.1.2 setting messages; it invents none for code-only OKF2.1.1.
+
+`binding.keys` is also accepted with **shape validation only** in0.24.4: a unique
+array of exact names or trailing-dot namespaces (`wider`, `stores.`), each matching
+`^[A-Za-z][A-Za-z0-9_-]*\\.?$` over the WHOLE string (no trailing newline). There
+is no filtering, overlapping-ownership check or owned/unowned-key attribution yet;
+those are deferred to0.25. Providers still receive the complete map and MUST ignore
+foreign keys themselves. Declaring keys does not authorize diagnostic text.
 
 Knowledge providers and harvesters follow the same separation: the
 [knowledge capability boundary](2026-09-16-knowledge-capability-contract.md) keeps

package/docs/design/2026-09-20-redesign-program-board.md

@@ -2,7 +2,7 @@
 
 **Purpose:** the one accurate view of every work stream in the redesign, what is on main, what is in flight, who owns it, and what blocks it. Lead: `oats-expert` (redesign lead). Updated whenever anything merges, is returned, or reality changes. Older per-lane boards are superseded by this file.
 
-**Last update:** 2026-09-21 04:10Z · main `feef2a2f`+ · **OATS v0.24.2 tagged (CI)** · OKF v2.1.1 · oats-framework/v1.1.1 · aweb v1.11.0 · oats-knowledge 8d67eab4
+**Last update:** 2026-09-21 15:15Z · main `ef211d3e`+ · OATS v0.24.4 cutting (PR41 merged) · OKF v2.1.1 · oats-framework/v1.1.1 · aweb v1.11.0 · oats-knowledge 8d67eab4
 
 Legend: ✅ on main/published · 🔄 in flight (PR/branch) · 🟡 preserved, not adopted · ⬜ not started · ⛔ blocked
 
@@ -11,7 +11,7 @@ Legend: ✅ on main/published · 🔄 in flight (PR/branch) · 🟡 preserved, n
 | # | Stream | State | Owner | Next action |
 |---|---|---|---|---|
 | S1 | Knowledge capability contract rework (kernel↔provider boundary, OKF 2.x) | ✅ OATS 0.24.1 / OKF 2.1.1 published | P | done for this phase |
-| S2 | Workspace/Portable Souls adoption of the OATS repos | ✅ workspace + seven indexes + **six imports** (five experts @caa341f3, setup expert @0aad753c) · ✅ second-operator gate run · 🔄 five seams → L, target 0.24.3 | lead, L, Antares | seams PR; Antares re-run on 0.24.2 (aweb 1.11.0) |
+| S2 | Workspace/Portable Souls adoption of the OATS repos | ✅ 0.24.3 gate run: knowledge slot resolves via the workspace route; seams 1–4 fixed, 5 attributed · ✅ **messaging source defect found and fixed (906b1558: per-human policy + soul teams)**, imports repinned f3ee31e0 · 🔄 final re-run for a published resolution + OKF check probe | lead, Antares | re-run; then S2 closed |
 | S3 | Messaging capability readiness on the new infrastructure (aweb) | ✅ aweb 1.11.0 released · ✅ **catalog + six editions pin v1.11.0 (0.24.2)** · ⬜ second-operator re-run | P, lead | Antares re-run |
 | S4 | Official capabilities `oats.core` / `oats.setup` + explicit default + onboarding `oats-setup-expert` | ✅ D1, D2, **D3 merged (PR35)**: `oats onboard` verified live (acquire 1.1.1 → setup expert with both caps → scaffold composes the five capability skills, no legacy) · `oats.framework` 1.1.1 tagged | P, L | done; Desktop surfaces → S8 |
 | S5 | Official marketplace = reviewed list in oats repo | ✅ D4 merged · ✅ `oats.framework` 1.1.1 listed (`oats.core`, `oats.setup`, `oats.knowledge-theory` aliases) | M | Desktop view → S8 |
@@ -33,12 +33,31 @@ Legend: ✅ on main/published · 🔄 in flight (PR/branch) · 🟡 preserved, n
 - ⬜ Fresh local deployment from the shared definition (P1.5) — the real acceptance gate.
 
 ## S2 — second-operator gate report (Antares, Juan's machine, 2026-09-20)
-Fresh dir, local `@awebai/oats@0.24.1`, no prior state. `inspect --request` → ready-for-preparation, membership eligible, source `souls/oats-kernel-expert@caa341f3`. `prepare` resolved and materialized `oats-package@caa341f3`, `oats.okf@v2.1.1`, `oats.aweb@v1.10.3`, `oats.core`, `oats.setup`, `oats.knowledge-theory` + soul; artifact-set approvals worked. Terminal: `needs-configuration` + `provider-not-qualified` (aweb 1.10.3 has no binding interface) — expected. Seams (assigned to L, one PR, priority):
+Fresh dir, local `@awebai/oats@0.24.1`, no prior state. `inspect --request` → ready-for-preparation, membership eligible, source `souls/oats-kernel-expert@caa341f3`. `prepare` resolved and materialized `oats-package@caa341f3`, `oats.okf@v2.1.1`, `oats.aweb@v1.10.3`, `oats.core`, `oats.setup`, `oats.knowledge-theory` + soul; artifact-set approvals worked. Terminal: `needs-configuration` + `provider-not-qualified` (aweb 1.10.3 has no binding interface) — expected. Seams — **all fixed in PR36 (913c4f9e), shipped in 0.24.3**:
 1. `inspect --request` requires `workTarget`; `prepare --request` refuses it (`buildFreshPreparationRequest` exists but the CLI never uses it).
 2. `prepare` on the absent deployment inspect blessed → raw `ENOENT` + host path through the JSON envelope.
 3. `prepare` writes lock v3; `oats trust <cap> --dir` rejects it (`unsupported lockfileVersion 3`) → dead end from `--help`.
 4. The working `trust --deployment --artifact-set <sha256>` route is absent from `--help`.
-5. Problems carry `origins: []` and no slot/capability; aweb's missing interface masks OKF diagnostics — a valid and a bogus `stores.oats` binding produce byte-identical output. **Fix first.**
+5. Problems carry `origins: []` and no slot/capability, so with more than one unresolved slot the operator cannot tell which slot a `needs-configuration` refers to (Antares needed three runs and an ablation table). **Root cause of the original identical pair (L's trace, confirmed by P and by Antares' settings-aware run):** both OKF `normalize` calls refused because the request had no OKF runtime settings (`bindings-file`, `state-dir`); the identical pair is correct output for that input. With settings, OKF normalize diagnostics DO reach the operator (a malformed `acceptedBranch` yields a distinct `invalid-binding`); a structurally valid locator to a nonexistent repo is correctly not distinguished until OKF `check`. Fix (0.24.3, PR36) = attribution by slot/capability/phase/origins + kernel-fixed messages. Precision: the kernel names the missing item only where it knows it (missing binding interface: id/version/slot); for a provider `needs-configuration` it cannot name `bindings-file`/`state-dir` because OKF 2.1.1's wire is code-only — OKF 2.1.2 (assigned to P) adds the fixed safe message naming the setting. Antares' earlier "no signal at all" framing is withdrawn by its author.
+
+## S2 — second-operator re-run on 0.24.2 (Antares, Juan's machine, 2026-09-21)
+- Found the five expert imports still pinned at `caa341f3` (aweb 1.10.3) while the setup expert was at `0aad753c` — the one repinned soul was the one that never exercises aweb. Fixed: all six imports at v0.24.3 `3156e4de` (638206b9); new layout guard fails when a pin's provider requirements lag the current edition (3ce40aaa, verified to catch the miss).
+- **aweb 1.11.0 qualifies**: via the direct source route on current main, `provider-not-qualified` disappeared → `approval-required` → after approval both slots on the settings hold. Confirms L's root cause.
+- `oats onboard --workspace git:github.com/awebai/oats` from a fresh dir: clean (acquired 1.1.1, both caps, spawn printed not run); scaffold composed exactly the five capability skills, both trusted, no hooks.
+- Seams 1–5 reproduced identically on 0.24.2 (baseline); fixed in 0.24.3. Gate decisions given: `harvest-model` arbitrary for the gate; aweb slot `delivery: session` without a private-team binding → expected typed `needs-configuration` naming the binding (Juan's team identity is never guessed).
+
+## S2 — settings-aware run (Antares, direct source route on main, aweb 1.11.0, 2026-09-21)
+- With `bindings-file`/`state-dir`/`harvest-runtime: pi` and the public `oats-knowledge` bound as base `oats`: **the knowledge slot binds** (OKF problem gone). `harvest-model` is optional per manifest; aweb 1.11.0 declares exactly one setting (`delivery`).
+- **aweb 1.11.0 is the only remaining hold** (`needs-configuration`, identical for `delivery: session` and `channel` on 0.24.2's unattributed output). No resolution publishes → OKF `check` probe not reachable yet. 0.24.3 run will show the attributed aweb message (expected: private-team binding / Pi session-input).
+
+## S2 — 0.24.3 gate run (Antares, Juan's machine, 2026-09-21) — verdict
+- Seams 1, 3, 4 **fixed**; seam 2 fixed as typed (message does not echo the path — deliberate, consistent with no host diagnostics; expectation corrected); seam 5 **half**: attribution (slot/capability/full origins) fixed; naming the missing item only where the kernel knows it. The specificity half is provider-side: OKF 2.1.2 (assigned) and an aweb follow-up.
+- Six imports resolve at the repinned revision; workspace route selects aweb 1.11.0; **the knowledge slot fully resolves through the workspace route** with `bindings-file`/`state-dir`/`harvest-runtime` (`harvest-model` confirmed optional).
+- **Messaging was a SOURCE defect, not an operator gap**: aweb 1.11.0 normalize requires the workspace to declare `teams: {private: per-human}` and the soul a messaging declaration; neither was published, so the slot was unreachable by any input. Fixed on main **906b1558** (workspace policy + `teams: []` on the five messaging editions; verified against aweb v1.11.0 normalize) and imports repinned **f3ee31e0**. Remaining operator inputs after the fix: `responsibleHuman` (required) and `wider` (required, may be empty) — the private team is a later `check` outcome.
+- **S2 exit-gate verdict (amended per the operator):** knowledge — an outside operator on 0.24.3 discovers, resolves, approves and binds from public sources, remaining item attributed: **PASS**. Messaging — on 0.24.3 as published the operator hit a source defect wearing a configuration error; fixed on main 906b1558 and to be re-proven on the repinned imports before it is written as PASS.
+- **Re-run on 906b1558 (operator, b875669f):** messaging normalize passes; remaining problem is `responsibleHuman`, attributed. But end-to-end is **deadlocked**: `wider: []` (messaging requires) makes OKF 2.1.1 return `invalid-binding` on knowledge (it validates every `operator.bindings` key as a store locator); without it messaging needs `wider`. Operator's wording adopted for S2: *a second operator reaches a published, resolvable configuration boundary for knowledge; messaging is blocked by a kernel-level binding-namespace collision, not by operator input or identity.* Not Juan's to unblock; no identity requested. [Decision](https://github.com/awebai/oats/blob/main/agents/oats-expert/soul/knowledge/decisions/operator-bindings-ownership.md): flat map with declared ownership (`binding.keys`); providers ignore foreign keys (OKF 2.1.2, aweb 1.11.1); kernel attributes/refuses stray keys by name — **deferred to 0.25 by L's scope call (accepted): overlap refusal, filtered forwarding, owned/unowned attribution and the undeclared-provider path need their own regression matrix; the provider ignore rule is the floor and ships in 0.24.4's provider releases.**
+- ✅ **PR41 merged `ef211d3e`** (L): inspect accepts prepare's superset (`ignored`), provider reasons cross the wire by exact match (manifest `binding.reasons` / bundled lists), `binding.keys` shape-only, CLI renders `key`. Full gate 1657/1653/0/4 twice (L + maintainer). → **v0.24.4**, kernel-first; OKF 2.1.2 / aweb 1.11.1 floor `>=0.24.4` (closed validator on ≤0.24.3 rejects the fields — P's finding).
+- Two further kernel findings from the repeat (assigned to L, 0.24.4): (a) seam 1 converged one way only — `inspect --request` still refuses prepare's `operator`/`launch`; (b) **the kernel discards the adapter's reason** at the wire (`provider-binding-wire.mjs:23`) and templates it; aweb already sends whitelisted safe reasons. New [decision](https://github.com/awebai/oats/blob/main/agents/oats-expert/soul/knowledge/decisions/provider-problem-reasons-cross-the-wire.md): whitelisted fixed reasons cross the wire (`binding.reasons`), free text still refused.
 
 ## S3 — Messaging (aweb) on the new infrastructure
 - ✅ **aweb PR3 merged → v1.11.0 (93f8ab96)**: `binding {normalize,bind,check}` on the existing wire; `check` = HOME-route operational custody only (explicit private team, `delivery: session`, kernel ≥0.24.2 via caller-owned `OATS_CLI_BIN`, retained `launchSelection` must be input-capable Claude/Codex; strict-Pi print → `needs-configuration`, never downgraded). Native adapter over existing `aw` commands with physical identity-dir custody and redacted tokens. Standalone 30/0; coupling 14/0 vs kernel b92f0d07. PR33 (launchSelection projection, OATS_CLI_BIN in codec env) merged b92f0d07.

package/docs/design/2026-09-20-workspace-onboarding-public.md

@@ -9,9 +9,18 @@ owned; production capability/profile readiness is not established by the fixture
 
 ```sh
 oats inspect --request /absolute/inspection.json --json
+# Optional explicit request export (new private file; never overwrite):
+oats inspect --request /absolute/inspection.json --emit-prepare-request /absolute/preparation.json --json
 ```
 
-This mode accepts only one request file and `--json`. Explicit captured selectors
+This mode accepts one request file, optional `--emit-prepare-request`, and `--json`.
+The 0.24.4 follow-up also accepts the complete preparation request's `operator`,
+`launch`, `helperLaunches`, `mode`, and `allowLocalPaths` fields. Inspection ignores
+their semantics: it does not validate provider payloads, select a runtime/model,
+execute a codec, or authorize local acquisition. `ignored: [...]` lists only the
+present field NAMES in a stable order; values stay out of the metadata view and
+`omitted.*` remains true. Preparation still validates those fields normally.
+Unknown fields remain errors. Explicit captured selectors
 or current-context flags conflict before file reads; inherited captured environment
 is not new-work input. Other existing inspect modes are unchanged. The shared
 bounded strict JSON request reader feeds the existing inspection validator intact:
@@ -66,21 +75,53 @@ have not been classified by their owner and are omitted. Import summaries expose
 `payloadOmitted`. Top-level `omitted:{providerPayloads:true,adoptionValues:true}`
 states that this is a metadata view, not a lossless request or a safe-payload claim.
 It is not an issued `buildFreshPreparationRequest` witness, even in the same
-process. Keep the original authored input for an explicit preparation request.
+process. The opt-in `--emit-prepare-request` route calls that existing builder
+on the real in-process inspection before dropping the private witness. It writes
+only `.preparation` to a new mode-0600 file at an explicit normalized absolute
+path with an existing real parent; existing files/symlinks are refused, never
+overwritten. JSON output names `prepareRequestFile` and records the explicit
+request-file write in `effects`; it does not echo the request contents. The
+export can carry unclassified adoption declarations and must remain private;
+requests must contain nonsecret values or credential references, never secrets.
+A held inspection cannot emit a fresh preparation request. Core callers can
+explicitly request this data via `{includePrepareRequest:true}`; the default
+metadata projection and its omissions are unchanged.
+
+The explicit export preserves authored prepare-only fields privately through the
+existing builder, without interpreting them; it must not silently drop operator
+bindings or launch/helper choices. They remain unvalidated until preparation.
+This does not expose their values in normal metadata or turn ignored values into
+inspection authority.
+
+The file is reusable new-work input, NOT a stored resolution, approval, admission,
+or serialized ready-inspection permission. Preparation performs fresh validation
+and observations, including re-resolving any mutable source selectors. Provider
+configuration still requires explicit operator choices; conversion invents none.
 
 Existing managed deployment state is preserved and reported, not repaired or
 migrated. An absent selected path requires explicit operator provisioning and
-reinspection. The serialized inspection does not lock the filesystem or authorize
+reinspection. Prepare refuses it with typed `needs-configuration` and provisioning
+guidance before fetching or writing managed state, not a raw ENOENT. Inspection's
+`ready` means the path is eligible for fresh setup, not already provisioned.
+The serialized inspection does not lock the filesystem or authorize
 later mutation; preparation retains its own existing validation/custody rules.
 The inspected work target does not become source identity or an implied placement
 choice. Supported captured directory scaffolds own their separate H/work.
 
 ## Existing preparation and retained execution
 
-`oats prepare --request` already accepts deployment/source/origin, workspace/member
-OR standalone context, operator policy/bindings, mode/local-input authorization,
-launch and helperLaunches. Do not pass the inspection result or workTarget/catalog
-wrapper. Exact executable approval is separate. A required provider whose binding
+`oats prepare --request` accepts deployment/source/origin, optional `workTarget`,
+workspace/member OR standalone context, operator policy/bindings,
+mode/local-input authorization, launch and helperLaunches. The original minimal
+inspection request (without inspection-only `catalogIndexes`) is also accepted;
+use the converter rather than stripping fields from a metadata/result wrapper.
+Explicit `workTarget` is validated with the same physical existing-directory
+validator as inspection and returned as work-context metadata. It takes precedence
+over any caller assumption about cwd: no cwd/config fallback selects its value.
+Omitting it preserves prior preparation behavior without inventing a placement.
+It does not change source identity, `operator.localBase`, work mode, or captured
+H/work placement. Do not pass an inspection result/catalog wrapper or private
+scratch `directory` to preparation. Exact executable approval is separate. A required provider whose binding
 code is unapproved may return `needs-configuration` with an `approval-required`
 problem and exact artifact-set/capability requests, before any record exists:
 
@@ -92,6 +133,48 @@ oats spawn <subject> --deployment <D> --resolution <R> --home <new-H> --no-launc
 oats session start --deployment <D> --resolution <R> --home <H> --request /absolute/native.json --json
 ```
 
+Each `selections[]` row carries an `artifactSet` id and an `approvalRequired[]`
+array of **capability ids**. Pair them: pass the capability to `trust` and that
+row's artifact-set id to `--artifact-set`. These are not interchangeable ids.
+`trust <capability> --dir <D>` against a v3 deployment now refuses with typed
+`needs-configuration` and exact available-set commands; it never picks or approves
+a set automatically. Classic v1/v2 trust remains the classic route.
+
+Provider preparation problems carry `slot` and `capability`, plus original
+provenance where available. A no-interface provider is identified with kernel-known
+manifest/version facts. Other supported slots still normalize, resolve through
+the same choice engine, and bind if their own choices are resolved; any required
+slot problem still prevents publication. Provider free text is not passed through.
+The 0.24.4 follow-up preserves only exact fixed reasons declared by the selected
+manifest (or its reviewed kernel compatibility list when absent); see the
+[binding wire](2026-09-16-provider-binding-wire.md). Human CLI output also shows a
+problem's existing choice key, without inventing new key/provider semantics.
+Different opaque inputs need not produce different public errors if both fail the
+same provider prerequisite. In particular, missing OKF host runtime settings can
+hold both syntactically valid Git locators; preparation does not test whether a
+remote repository exists. Required readiness checks remain later, with the provider.
+
+### Operator input
+
+When present, `operator` requires both `policy` (object; `{}` is valid) and
+`document` (`{ "kind": "operator", "id": "setup-attempt" }`). Its ONLY optional
+fields are `localBase`, `allowLocalPaths`, `sourceContext`, and `bindings`:
+
+- `policy`: explicit provider/additive selections with their selected sources and
+  settings, using the existing policy grammar. It cannot erase soul requirements.
+- `localBase`: explicit absolute base for relative local policy sources. Work
+  context/cwd is not a substitute.
+- `allowLocalPaths`: explicit boolean authorization for those local policy sources.
+  Top-level local acquisition authorization remains a separate input.
+- `sourceContext`: existing qualified repository anchor for `repo:` policy sources;
+  not a new repository inferred from workTarget.
+- `bindings`: provider-owned map. Kernel preserves it and its document pointers;
+  it does not interpret store names, Git destinations, credentials or private teams.
+
+Selecting an inherited store does not replace required provider runtime settings.
+Use the selected provider's instructions for those settings; kernel must not guess
+host-owned durable paths or copy native authentication.
+
 Repreparation after explicit approval is ordinary continuation in the selected,
 now-managed deployment; do not delete its state to make fresh preflight pass.
 Required hooks still run under their admitted custody with `--no-launch`; a parsed

package/docs/first-team.md

@@ -44,14 +44,13 @@ create/spawn/retire. A team roster does not select a work repository for spawn.
 
 ## Onboarding with the setup expert
 
-For a kernel build that includes `oats onboard` (check `oats onboard --help`),
-start in an explicit empty deployment:
+On **OATS 0.24.2 or later**, start in an explicit empty deployment:
 
 ```bash
 oats onboard --dir /absolute/new-deployment --json
 ```
 
-This command is **not present in the published 0.24.0/0.24.1 kernels**. It is a
+`oats onboard` ships from 0.24.2 (earlier kernels refuse it). It is a
 classic local bootstrap, not captured preparation or workspace enrollment. It
 acquires `oats.framework` from the official catalog, exact-locks its artifacts,
 selects only `oats.core` and `oats.setup` for the new local `oats-setup-expert`,

package/docs/release-notes/v0.24.3.md

@@ -0,0 +1,13 @@
+# OATS v0.24.3 — second-operator `prepare` seams
+
+Kernel/Pi/Desktop **0.24.3**. Fixes the five usability seams an independent second operator hit adopting the shared workspace definition on 0.24.1/0.24.2 (see the [program board](../design/2026-09-20-redesign-program-board.md)). No contract, schema or authority change.
+
+- **Attributed provider problems.** Every preparation problem now carries `slot`, `capability` and its `origins`, with kernel-fixed text (for example `oats.okf knowledge normalize binding could not be prepared` / `oats.aweb@1.10.3 declares no binding interface; messaging cannot be prepared`). The kernel names the missing item where it knows it (a missing binding interface); for a provider's own `needs-configuration` it attributes the slot/capability/phase but cannot name the missing setting unless the provider sends it — OKF 2.1.1 sends code only, so `bindings-file`/`state-dir` are named by the setup guidance and by OKF 2.1.2. One unqualified slot no longer masks another slot's diagnostics: every slot that has a binding interface is normalized, and the single resolver reports each invalid choice under its slot. Provider free text still never crosses the wire.
+- **`oats trust <capability> --dir <deployment>` on a lock v3 deployment** returns a typed problem with the exact working command (`oats trust <cap> --deployment <abs> --artifact-set <sha256-…>`) instead of `unsupported lockfileVersion 3`. No auto-approval.
+- **Help** documents `--artifact-set` and how `prepare`'s `selections[].artifactSet` / `approvalRequired[]` pair with it.
+- **`prepare` on an absent deployment path** returns a typed explicit-provisioning hold, not a raw `ENOENT` with a host path.
+- **One request file for both commands.** `prepare --request` accepts the explicit `workTarget` that `inspect --request` requires (explicit beats cwd; it never implies captured placement or current config), and `oats inspect --request <f> --emit-prepare-request <out>` writes the converted preparation request through the existing builder.
+
+The second operator's recorded requests and results are preserved verbatim as regression fixtures (`test/fixtures/second-operator/`). Their valid-vs-bogus `stores.oats` pair remains identical by design: both refused on missing OKF runtime settings (`bindings-file`, `state-dir`), which the messages now say.
+
+Setup guidance for those settings lands in the next `oats.framework` payload.

package/docs/release-notes/v0.24.4.md

@@ -0,0 +1,10 @@
+# OATS v0.24.4 — provider reasons cross the wire; one request file for both commands
+
+Kernel/Pi/Desktop **0.24.4**. Two findings from the independent second operator's repeat on 0.24.3 (see the [program board](../design/2026-09-20-redesign-program-board.md)), plus the first half of the binding-ownership rule. Kernel-first release: the provider releases that declare the new manifest fields (OKF 2.1.2, aweb 1.11.1) require this version.
+
+- **The kernel no longer discards the provider's reason.** A provider's `error.message` (and a non-ready `check`'s `result.problems[].message`) now crosses the binding wire when it is byte-equal to a fixed reason the provider declares — manifest `binding.reasons`, or the kernel's reviewed compatibility list for aweb 1.11.0 and OKF 2.1.2 — and is surfaced as the problem's `message` beside `slot`, `capability` and `origins`. Anything else is dropped as before and the kernel template is used. No interpolation, no operator values, no paths, ever: the second operator sees `messaging workspace must declare private: per-human` or `setting bindings-file is required (absolute host path)` in one run instead of six. Decision: `agents/oats-expert/soul/knowledge/decisions/provider-problem-reasons-cross-the-wire.md`.
+- **`binding.reasons` and `binding.keys` manifest fields** (optional). `reasons`: 1–64 unique printable-ASCII strings ≤200 chars, no braces; an invalid declaration refuses, it never falls back. `keys`: a provider's owned operator-binding keys, exact names or trailing-dot namespaces (`stores.`) — **shape-validated only in 0.24.4**; forwarding, overlap refusal and stray-key attribution land in 0.25. Providers must still ignore keys they do not own (decision `operator-bindings-ownership.md`). Every earlier kernel rejects manifests carrying these fields, so declaring providers floor on `>=0.24.4`.
+- **`inspect --request` accepts `prepare`'s fields.** `operator`, `launch`, `helperLaunches`, `mode`, `allowLocalPaths` are accepted, not evaluated, and listed under `ignored`; `--emit-prepare-request` carries them through unchanged. The same complete request file is now valid for both commands — the 0.24.3 fix had converged only one way.
+- **CLI renders the problem `key`** (for example `/bindings/messaging/responsibleHuman`) beside its message.
+
+Not in this release: the operator-bindings deadlock between OKF 2.1.1 and aweb 1.11.0 (OKF validated messaging's `wider` as a store locator) is fixed provider-side in OKF 2.1.2, released next with `binding.reasons`/`binding.keys` declared and floor 0.24.4; then aweb 1.11.1 (manifest-only), the `oats.framework` 1.1.2 payload, and the workspace editions re-pinned.

package/docs/workspace-adoption.md

@@ -44,51 +44,75 @@ owner registry belongs in the public workspace. Knowledge publication and accept
 (S7) remain separate; no ready knowledge export is advertised. Preserve the parked
 roster/curation and every old home, lock, source, pending job, history and worktree.
 
-## Planned onboarding: OATS Soul Setup (D3)
-
-**The D3 onboarding flow remains pending.** It will create and instantiate
-`oats-setup-expert`, declaring both `oats.core` and `oats.setup` from the
-[official marketplace](official-marketplace.md). Those capabilities are now
-published in `oats.framework` 1.1.0 and listed; the separate setup-expert edition
-and onboarding entry point do not become available merely by listing the package.
-This flow was not shipped in the 0.24.0 or 0.24.1 kernel releases.
-
-- The setup expert will help the operator adopt repositories, select capabilities
-  and carry out the normal prepare/approve/scaffold/start steps. It bypasses no
-  executable approval, provider readiness, identity or permission boundary.
-- Every soul created by that flow will declare `requires.capabilities.oats.core`
-  and its source explicitly. The operator can remove or replace that dependency
-  by editing the authored definition, not a captured record; the kernel will not
-  silently reinsert an absent one.
-- The CLI/Desktop entry point still requires separate implementation and review.
-  Do not invent a workspace init/adopt command, create a setup soul from this
-  sketch, or treat a listed package as installed. Existing instances and retained
-  resources are not rewritten by the plan.
+## Onboard with OATS Soul Setup (0.24.2+)
+
+With operator approval, [OATS 0.24.2](release-notes/v0.24.2.md) and later provide:
+
+```sh
+oats onboard --dir /absolute/context --json
+```
+
+This is **classic local bootstrap**, not captured preparation or workspace
+enrollment; the command is absent from 0.24.0/0.24.1. Classic root resolution
+selects an enclosing roster, otherwise the enclosing Git root/context. Supplying
+`--dir` does **not** promise that a literal nested subdirectory becomes a new
+physical deployment; choose an independent context when that is intended.
+
+Onboarding acquires the catalog's official `oats.framework` package through the
+ordinary acquisition/lock engine and creates a local `oats-setup-expert`, selecting
+only `oats.core` and `oats.setup` for it. Both local capability requirements name
+the **actually acquired immutable commit**, not orphan `repo:` paths in the new
+deployment. Knowledge, messaging and tasks default to none, with no knowledge
+owner or payload. Unexpected executable surfaces refuse rather than gaining trust
+from catalog membership. Review the resolved deployment and returned
+`result.next.command`: it uses the same kernel for the next spawn, and onboarding
+**never executes it or launches a model**.
+
+Optional `--workspace git:host/org/repository[@revision]` selects the workspace's
+pinned setup-expert import, or that explicit repository's advertised setup edition
+at its observed revision. Its source-package bytes must match the official
+acquisition. Failed explicit inputs never fall back to the packaged default, and
+workspace policy, teams and provider adoption values are not silently adopted.
+
+An **existing roster** requires `--force-existing` (the guard is the agent list,
+not merely any existing configuration). The flag cannot replace an existing or
+incomplete setup soul or disable providers/additives for other souls; exclusions
+apply only to the new setup expert. Failures report partial acquisition/creation,
+not atomic captured preparation. Preserve that evidence before retrying.
+**`oats setup` remains record capture setup**, unchanged. Native authentication
+and permission boundaries remain.
+
+The expert can then guide deliberate configuration and the normal retained
+prepare/approve/scaffold/start stages. A created soul or printed spawn command is
+not a running session, provider qualification or accepted learning. Desktop
+onboarding and legacy roster/knowledge cutover remain separate.
 
 ## Stage two: published experts and pinned imports
 
 - `oats-workspace.yaml` explicitly admits `oats` and the six intended capability
   repositories: `oats-dev`, `oats-okf`, `oats-aweb`, `oats-authoring`, `oats-jira`
   and `oats-linear`. It activates no additional capability; tasks default to none.
-- `oats.yaml` exports all five `souls/<name>` editions above and the actual package
-  roots `oats-package` (`oats.framework`) and `capabilities/oats-authoring`, not
+- `oats.yaml` exports the five knowledge-owning editions above plus the separate
+  `souls/oats-setup-expert` bootstrap edition, and the actual package roots
+  `oats-package` (`oats.framework`) and `capabilities/oats-authoring`, not
   the npm root as a fictitious OATS distribution. Its workspace backlink names
   the same framework repository.
 - The editions are parallel to, not replacements for, the live `agents/` roster.
   Each contains canonical instructions, `CLAUDE.md -> AGENTS.md`, and its reviewed
   private procedures where applicable. No durable KB is copied into them; legacy
-  roster cutover remains deferred until S7 knowledge publication.
-- Each edition preserves its knowledge owner, owned node and four cross-reads.
+  roster/knowledge cutover remains deferred until the fresh-reader proof against
+  the accepted public knowledge base.
+- Each of the five expertise editions preserves its owner, node and four cross-reads.
   Store `oats` requires the explicit `stores.oats` binding; no publisher writer,
   production store or grants are supplied. An acceptance fixture is parent-owned
   and cannot be counted as production knowledge adoption.
-- Knowledge **oats.okf@2.1.1** and messaging **oats.aweb@1.11.0** are explicit hard
-  requirements, not optional defaults. They are published starting revisions,
-  **not proof that their combined bindings/runtime profile is ready**. The provider
+- Current authored expert editions require knowledge **oats.okf@2.1.1** and
+  messaging **oats.aweb@1.11.0**, not optional defaults. These published revisions
+  are **not proof that their combined bindings/runtime profile is ready**. The provider
   owner supplies that evidence and any subsequently reviewed compatible revision.
   Do not replace either requirement with none or erase a read edge to launch.
 
-At these starting pins, the provider boundary is concrete:
+At those authored revisions, the provider boundary is concrete:
 
 - Published OKF2.1.1 supports `inherit: stores.oats`, normalized to
   `/bindings/knowledge/stores/oats`. The explicit `destination: oats` preserves
@@ -112,19 +136,27 @@ select reviewed compatible provider revisions and update the source pin delibera
 before claiming an operational pilot; metadata-only repository indexes change none
 of these runtime facts.
 
-Stage one used an empty imports list until source publication. Stage two is now
-committed: all five imports pin **`caa341f34009e37006567419a983d5a743037a79`**, the
-published edition revision containing explicit core requirements and the package.
-The later workspace commit `375b9f42` added those imports. Live source inspection
-against published main resolved all five as `ready-for-preparation`; this is
-metadata readiness, not provider binding, approval, enrollment or a running pilot.
+Stage one used an empty imports list until source publication. All six imports
+now pin **`906b1558633766cf489451f9b68016216acaa63b`** (after
+[OATS v0.24.3](release-notes/v0.24.3.md)), the reviewed revision at which the
+workspace declares the per-human private team policy (`teams: {private: per-human}`)
+and every messaging edition carries its `teams: []` declaration — without them the
+aweb provider cannot normalize in workspace context, as the second operator found.
+Workspace update `f3ee31e0`. The five knowledge-owning experts therefore select
+OKF2.1.1 and aweb1.11.0 with explicit core; setup remains provider-independent,
+requiring core/setup and defaulting all three fundamental layers to none. It is
+not a sixth knowledge owner. This deliberate repin, not a catalog/kernel upgrade
+alone, advances the selected source requirements. Successful source inspection,
+including `ready-for-preparation`, is still metadata readiness—not binding,
+approval, enrollment or a running pilot.
 
 ## Preserve source-before-import publication order
 
-1. Publish complete, reviewed source editions before pinning them. The current
-   source is `caa341f34009e37006567419a983d5a743037a79`; future revisions must likewise
-   exist before their workspace import update. Never use an invented SHA, a mutable
-   branch or an unreviewed local candidate as the accepted source.
+1. Publish complete, reviewed source editions before pinning them. All six imports
+   use `906b1558633766cf489451f9b68016216acaa63b`. Future revisions must
+   likewise exist before their import update.
+   Never use an invented SHA, a mutable branch or an unreviewed local candidate
+   as the accepted source.
 2. In each of the six repositories, review a root `oats.yaml` against its actual
    source head and actual `oats-package/oats-package.json`. The declaration is:
 
@@ -149,13 +181,13 @@ metadata readiness, not provider binding, approval, enrollment or a running pilo
    imports:
      - source: git:github.com/awebai/oats
        soul: souls/oats-expert
-       revision: caa341f34009e37006567419a983d5a743037a79
+       revision: 906b1558633766cf489451f9b68016216acaa63b
        alias: oats-expert
    ```
 
-   The [actual workspace](../oats-workspace.yaml) contains all five imports at that
-   same revision; this excerpt is not a replacement for the full list. The layout
-   test now checks stage-two imports and source-document declarations. Do not
+   The [actual workspace](../oats-workspace.yaml) contains all six imports at that
+   same revision; this excerpt is not the full list.
+   The layout test checks all six imports and source-document declarations. Do not
    change stable export paths or owners merely because the workspace advances.
 4. Qualify reciprocal admission at the now-published observations. A missing
    backlink, a fork's copied file or a stale workspace observation is not membership.

package/lib/core.mjs

@@ -62,7 +62,7 @@ import { validateCapturedLaunchRequest } from "./captured-launch-request.mjs";
 import { validateCapabilityInputDeclarations } from "./capability-inputs.mjs";
 import { validateCapturedSessionBackend, validateCapturedSessionTarget, assertCapturedSessionPlacement } from "./captured-session-backend.mjs";
 import { createRepositoryTransaction } from "./repository-observation.mjs";
-import { inspectPortableOnboarding as inspectOnboarding, describePortableOnboarding } from "./portable-onboarding.mjs";
+import { inspectPortableOnboarding as inspectOnboarding, describePortableOnboarding, buildFreshPreparationRequest, inspectWorkTarget } from "./portable-onboarding.mjs";
 import { readLock3 } from "./portable-lock.mjs";
 import { portableScope, portableStateDirectory } from "./portable-state.mjs";
 import { objectAt } from "./portable-shape.mjs";
@@ -1211,13 +1211,17 @@ export function approveAvailableCapability(deployment, artifactSet, capability,
 /** Public read-only source/workspace inspection through the existing facade.
  * Owns only transient repository scratch, never deployment state, provisioning,
  * provider code, approvals or a serialized mutation witness. */
-export function inspectPortableOnboarding(input, { repositoryOptions = {} } = {}) {
+export function inspectPortableOnboarding(input, { repositoryOptions = {}, includePrepareRequest = false } = {}) {
   canonicalJson(input);
+  if (typeof includePrepareRequest !== "boolean") throw oatsError("invalid-declaration", "request conversion requires an explicit boolean option");
   const directory = mkdtempSync(join(realpathSync(tmpdir()), "oats-source-inspection-")), owned = lstatSync(directory);
   let repositories, primary;
   try {
     repositories = createRepositoryTransaction({ ...repositoryOptions, directory, accessContextKey: repositoryOptions.accessContextKey ?? "native" });
-    return describePortableOnboarding(inspectOnboarding(input, { repositories }));
+    const inspection = inspectOnboarding(input, { repositories }), result = describePortableOnboarding(inspection);
+    // Opt-in data export, not a serialized custody witness or executable grant.
+    // Default metadata continues to omit unclassified adoption/provider values.
+    return includePrepareRequest ? { ...result, prepareRequest: buildFreshPreparationRequest(inspection).preparation } : result;
   } catch (error) { primary = error; throw error; }
   finally {
     try {
@@ -1239,21 +1243,28 @@ export function inspectPortableOnboarding(input, { repositoryOptions = {} } = {}
  * a fabricated complete record. No lifecycle side effects run here. */
 export function prepareCapturedComposition(input, { repositoryOptions = {} } = {}) {
   canonicalJson(input);
-  objectAt(input, ["deployment", "source", "origin", "workspace", "member", "operator", "mode", "allowLocalPaths", "standaloneContextKey", "launch", "helperLaunches"], ["deployment", "source"]);
+  objectAt(input, ["deployment", "workTarget", "source", "origin", "workspace", "member", "operator", "mode", "allowLocalPaths", "standaloneContextKey", "launch", "helperLaunches"], ["deployment", "source"]);
   if (input.launch !== undefined) validateCapturedLaunchRequest(input.launch, validateLaunchConfig);
   if (input.helperLaunches !== undefined) {
     objectAt(input.helperLaunches, null, []);
     for (const request of Object.values(input.helperLaunches)) validateCapturedLaunchRequest(request, validateLaunchConfig);
   }
   if (input.mode !== undefined && !WORK_MODES.includes(input.mode)) throw oatsError("invalid-declaration", "invalid preparation work mode");
-  const deployment = portableScope(input.deployment);
+  const { workTarget, ...preparationInput } = input;
+  const target = Object.hasOwn(input, "workTarget") ? inspectWorkTarget(workTarget) : null;
+  let deployment;
+  try { deployment = portableScope(input.deployment); }
+  catch (error) {
+    if (error.code === "ENOENT") throw oatsError("needs-configuration", "deployment directory is absent; provision the explicitly selected directory and inspect again before preparation");
+    throw error;
+  }
   const previous = readLock3(deployment); // Old state refuses before scratch/fetch.
   const directory = mkdtempSync(join(portableStateDirectory(deployment, true), ".prepare-")), owned = lstatSync(directory);
   const origin = input.origin ?? { kind: "operator", document: { kind: "operator", id: "oats-prepare" }, pointer: "/source" };
   let repositories, primary, catalog;
   try {
     repositories = createRepositoryTransaction({ ...repositoryOptions, directory, accessContextKey: repositoryOptions.accessContextKey ?? "native" });
-    return prepareComposition({ ...input, deployment, origin, directory }, { repositories, previous, kernel: {
+    const result = prepareComposition({ ...preparationInput, deployment, origin, directory }, { repositories, previous, kernel: {
       loadPackageManifestAt, capabilityCompatibility, assertPlatformInvariantLocks, materializeCapability,
       manifest: loadRetainedManifest,
       binding: runCapturedProviderBinding,
@@ -1266,6 +1277,8 @@ export function prepareCapturedComposition(input, { repositoryOptions = {} } = {
         settings: assertCapabilitySettingValues, skills: skillEntriesIn, hooks: manifestHookDeclarations,
         validateLaunchConfig, runtimeRequirements: applicableRequirements }),
     } });
+    // Explicit work context never selects source/config, cwd, or H/work placement.
+    return target ? { ...result, workTarget: target } : result;
   } catch (error) { primary = error; throw error; }
   finally {
     try {

package/lib/portable-onboarding.mjs

@@ -13,6 +13,7 @@ import { validateOrigin } from "./resolution-shape.mjs";
 import { oatsError } from "./errors.mjs";
 
 export const PORTABLE_ONBOARDING_VERSION = 1;
+const PREPARATION_ONLY_FIELDS = Object.freeze(["operator", "launch", "helperLaunches", "mode", "allowLocalPaths"]);
 const issued = new WeakMap();
 const preflightWitnesses = new WeakMap();
 const MANAGED_PATHS = Object.freeze([
@@ -108,7 +109,7 @@ export function preflightFreshDeployment({ deployment, maxEntries = 4096 }) {
   return result;
 }
 
-function workTarget(path) {
+export function inspectWorkTarget(path) {
   const canonical = canonicalExistingDirectory(path, "work target"), marker = present(join(canonical, ".git"));
   return { path: canonical, state: "existing", git: marker ? { present: true, kind: marker.isDirectory() ? "directory" : marker.isFile() ? "file" : "other" } : { present: false, kind: null } };
 }
@@ -140,14 +141,18 @@ function catalogSelection(value, count) {
  * The caller owns the repository transaction lifetime. */
 export function inspectPortableOnboarding(input, { repositories } = {}) {
   canonicalJson(input);
-  exact(input, ["deployment", "workTarget", "source", "origin", "workspace", "member", "catalogIndexes", "standaloneContextKey"],
+  exact(input, ["deployment", "workTarget", "source", "origin", "workspace", "member", "catalogIndexes", "standaloneContextKey", ...PREPARATION_ONLY_FIELDS],
     ["deployment", "workTarget", "source", "origin"], "portable onboarding inspection");
   if (!repositories || typeof repositories !== "object") throw oatsError("invalid-source", "portable onboarding needs an explicit repository transaction");
   validateOrigin(input.origin);
   const standalone = explicitContext(input);
   const deployment = preflightFreshDeployment({ deployment: input.deployment });
-  const target = workTarget(input.workTarget), discovery = createWorkspaceDiscovery(repositories);
-  const witness = { deployment: preflightWitnesses.get(deployment), work: directoryIdentity(target.path) };
+  const target = inspectWorkTarget(input.workTarget), discovery = createWorkspaceDiscovery(repositories);
+  const ignored = PREPARATION_ONLY_FIELDS.filter(field => Object.hasOwn(input, field));
+  // Retain authored data privately for explicit request export ONLY. Inspection
+  // neither validates provider/launch semantics nor exposes these values.
+  const witness = { deployment: preflightWitnesses.get(deployment), work: directoryIdentity(target.path),
+    preparationFields: Object.fromEntries(ignored.map(field => [field, structuredClone(input[field])])) };
   const workspace = Object.hasOwn(input, "workspace") ? discovery.readWorkspace(input.workspace) : null;
   const selected = typeof input.source === "string" ? sourceOrigin(workspace, input.source) : { reference: input.source, origin: input.origin };
   const imported = discovery.importSoul(selected.reference, { origin: selected.origin });
@@ -171,7 +176,7 @@ export function inspectPortableOnboarding(input, { repositories } = {}) {
   const declaredTeams = workspace?.parsed.declaration.teams ?? {};
   const status = deployment.status !== "ready" ? deployment.status
     : input.member && membership.status !== "eligible" ? "needs-configuration" : "ready-for-preparation";
-  const result = freezeJson({ schemaVersion: PORTABLE_ONBOARDING_VERSION, status, deployment, workTarget: target,
+  const result = freezeJson({ schemaVersion: PORTABLE_ONBOARDING_VERSION, status, deployment, workTarget: target, ignored,
     source: { location: imported.reference.source, reference: imported.reference, identity: imported.identity,
       revision: imported.observation.source, alias: imported.reference.alias, exportPath: imported.reference.soul,
       definition: imported.definition, roots: imported.roots, exports: exports.exports, provenance: imported.provenance },
@@ -236,12 +241,14 @@ export function buildFreshPreparationRequest(inspection, options = {}) {
   const { operator, mode, allowLocalPaths = false } = options;
   if (typeof allowLocalPaths !== "boolean") throw oatsError("invalid-declaration", "allowLocalPaths must be boolean");
   if (mode !== undefined && (typeof mode !== "string" || !mode.trim())) throw oatsError("invalid-declaration", "preparation mode must be non-empty text");
-  const input = { deployment: inspection.deployment.deployment.path,
+  const input = { deployment: inspection.deployment.deployment.path, workTarget: inspection.workTarget.path,
     source: inspection.source.reference,
     origin: inspection.source.revision.provenance[0], allowLocalPaths,
     ...(inspection.workspace ? { workspace: inspection.workspace.request } : { standaloneContextKey: inspection.context.key }),
     ...(inspection.repositoryMembership.request ? { member: inspection.repositoryMembership.request } : {}),
-    ...(operator === undefined ? {} : { operator }), ...(mode === undefined ? {} : { mode }) };
+    ...issued.get(inspection).preparationFields,
+    ...(operator === undefined ? {} : { operator }), ...(mode === undefined ? {} : { mode }),
+    ...(Object.hasOwn(options, "allowLocalPaths") ? { allowLocalPaths } : {}) };
   canonicalJson(input);
   return freezeJson({ schemaVersion: PORTABLE_ONBOARDING_VERSION, operation: "prepare", persisted: false,
     preparation: input, workTarget: inspection.workTarget,

package/lib/prepared-bindings.mjs

@@ -6,6 +6,7 @@ import { validateOrigin } from './resolution-shape.mjs';
 import { pointerKey } from './portable-shape.mjs';
 import { bindingField, bindingOriginWitnessed } from './provider-binding-wire.mjs';
 import { oatsError } from './errors.mjs';
+import { providerReasons, safeProviderReason } from './provider-reasons.mjs';
 
 /** Remap dictionary keys for an adoption subtree, but retain original document
  * pointers/spans inside each witness. No file/config is read here. */
@@ -37,24 +38,34 @@ export function prepareProviderBindings({seed,plan,manifests,declarations},invok
   const normalized=new Map(),problems=[],requirements=[...plan.requirements],candidates=[...plan.candidates];
   const settingsFor=id=>Object.fromEntries(Object.entries(plan.settings[id] ?? {}).map(([name,key])=>[name,plan.choices[key].value]));
   const run=(id,phase,input)=>invoke({artifacts:seed.artifacts,capability:id,phase,settings:settingsFor(id),input});
-  const refuse=error=>({code:safeCodes.has(error?.code)?error.code:'provider-not-qualified',message:'provider binding could not be prepared',origins:[]});
+  const originsFor=id=>[...new Map((plan.capabilities[id]?.choiceKeys ?? []).flatMap(key=>{
+    const choice=plan.choices[key];return choice?.selectedBy?[choice.selectedBy]:[];
+  }).map(origin=>[canonicalJson(origin),origin])).values()];
+  const problem=(slot,id,code,message,origins=originsFor(id))=>({code,message,origins,slot,capability:id});
+  const refuse=(slot,id,phase,error)=>problem(slot,id,safeCodes.has(error?.code)?error.code:'provider-not-qualified',
+    safeProviderReason(error?.message,providerReasons(manifests.get(id))) ?? `${id} ${slot} ${phase} binding could not be prepared`); // Recheck fixed text; never arbitrary exceptions.
   for (const [id,manifest] of manifests) {
     if (!Object.hasOwn(seed.artifacts.capabilities,id) || !manifest.layer) continue;
-    if (plan.providers[manifest.layer] !== id) problems.push({code:'needs-configuration',message:'fundamental capability must be selected in its own layer',origins:[]});
+    if (plan.providers[manifest.layer] !== id) problems.push(problem(manifest.layer,id,'needs-configuration','fundamental capability must be selected in its own layer'));
   }
-  if (problems.length) return {plan,seed,problems};
   for (const [slot,id] of Object.entries(plan.providers)) {
     if (id === null) continue;
     const manifest=manifests.get(id);
-    if (manifest?.layer !== slot || !manifest.binding) { problems.push({code:'provider-not-qualified',message:'selected provider has no matching binding interface',origins:[]});continue; }
+    if (manifest?.layer !== slot) { problems.push(problem(slot,id,'provider-not-qualified',`${id} does not declare the selected ${slot} layer`));continue; }
+    if (!manifest.binding) { problems.push(problem(slot,id,'provider-not-qualified',`${id}@${manifest.version} declares no binding interface; ${slot} cannot be prepared`));continue; }
     try {
       const value=run(id,'normalize',{declarations,context:seed.context});
       normalized.set(slot,{id,value}); requirements.push(...value.requirements);candidates.push(...value.candidates);
-    } catch(error) { problems.push(refuse(error)); }
+    } catch(error) { problems.push(refuse(slot,id,'normalize',error)); }
   }
-  if (problems.length) return {plan,seed,problems};
+  // One unsupported slot must not mask another slot's normalized requirements
+  // or invalid choices. The same resolver still decides every value.
   const resolved=resolveChoices({requirements,candidates});
-  if (resolved.status !== 'resolved') return {plan:{...plan,...resolved},seed,problems:resolved.problems};
+  for (const item of resolved.problems) {
+    const slot=Object.keys(plan.providers).find(slot=>bindingField(item.key,slot));
+    if (!slot) throw oatsError('invalid-binding-output','provider choice problem has no owned binding slot');
+    problems.push({...item,slot,capability:plan.providers[slot]});
+  }
   const nextPlan={...plan,...resolved,requirements,candidates},bindings=Object.create(null);
   let messagingChoice={schemaVersion:1,enabled:false};
   const known=[];
@@ -64,6 +75,7 @@ export function prepareProviderBindings({seed,plan,manifests,declarations},invok
   }
   const witnessed=origin=>bindingOriginWitnessed(origin,declarations) || known.some(candidate=>same(candidate,origin));
   for (const [slot,{id,value}] of normalized) {
+    if (resolved.problems.some(item=>bindingField(item.key,slot))) continue;
     try {
       const choices=Object.fromEntries(Object.entries(resolved.choices).filter(([key])=>bindingField(key,slot)));
       const bound=run(id,'bind',{model:value.model,choices,context:seed.context});
@@ -72,7 +84,9 @@ export function prepareProviderBindings({seed,plan,manifests,declarations},invok
       }
       bindings[slot]=bound.binding;
       if (slot === 'messaging') messagingChoice=bound.messagingChoice;
-    } catch(error) { problems.push(refuse(error)); }
+    } catch(error) { problems.push(refuse(slot,id,'bind',error)); }
   }
+  nextPlan.problems=problems;
+  nextPlan.status=problems.some(item=>item.code==='requirement-conflict')?'conflict':problems.length?'needs-configuration':'resolved';
   return {plan:nextPlan,seed:{...seed,choices:resolved.choices,bindings,messagingChoice},problems};
 }

package/lib/provider-binding-broker.mjs

@@ -13,6 +13,7 @@ import { readApprovalLedger, evaluateCapturedApprovals } from './artifact-approv
 import { validateBindingInterface } from './provider-binding.mjs';
 import { BINDING_LIMITS, validateBindingRequest, decodeBindingResponse } from './provider-binding-wire.mjs';
 import { oatsError } from './errors.mjs';
+import { providerReasons } from './provider-reasons.mjs';
 
 // Same kernel-owned CLI locator as lifecycle hooks; never caller env or PATH.
 const CLI_BIN=fileURLToPath(new URL('../bin/oats.mjs',import.meta.url));
@@ -58,7 +59,7 @@ export function invokeProviderBinding(options,codecs) {
       timeout:timeoutMs,killSignal:'SIGKILL',maxBuffer:BINDING_LIMITS.maxBytes,stdio:['pipe','pipe','pipe'],shell:false});
   } catch { throw oatsError('provider-unavailable','provider codec could not execute'); }
   if (result.error || result.signal || result.status !== 0) throw oatsError('provider-unavailable','provider codec did not complete successfully');
-  const response=decodeBindingResponse(result.stdout,request);
-  if (!response.ok) throw oatsError(response.error.code,'provider binding phase refused');
+  const response=decodeBindingResponse(result.stdout,request,{reasons:providerReasons(manifest)});
+  if (!response.ok) throw oatsError(response.error.code,response.error.message ?? 'provider binding phase refused');
   return response.result;
 }

package/lib/provider-binding-wire.mjs

@@ -8,6 +8,7 @@ import { isMaterializedCapabilityId } from './capability-provenance.mjs';
 import { BINDING_PHASES } from './provider-binding.mjs';
 import { resolveChoices } from './portable-choices.mjs';
 import { oatsError } from './errors.mjs';
+import { providerReasons, safeProviderReason, validateBindingReasons } from './provider-reasons.mjs';
 
 export const BINDING_LIMITS = Object.freeze({maxBytes:1024*1024,maxDepth:32,maxEntries:16384});
 export const BINDING_PROBLEMS = Object.freeze(['needs-configuration','requirement-conflict','invalid-binding','authorization-required','host-requirement-missing','provider-unavailable','provider-not-qualified']);
@@ -16,11 +17,12 @@ const same = (a,b) => canonicalJson(a) === canonicalJson(b);
 const roleKinds = {soul:['soul-requirement','soul-default'],workspace:['workspace-default'],adoption:['import-adoption'],operator:['operator']};
 const pointer = key => typeof key === 'string' && /^(?:\/(?:[^~]|~[01])*)+$/.test(key);
 export const bindingField = (key,slot) => pointer(key) && key.startsWith(`/bindings/${slot}/`) && key.length > `/bindings/${slot}/`.length;
-function problem(value) {
+function problem(value,reasons) {
   objectAt(value,['code','message'],['code']);
   if (!BINDING_PROBLEMS.includes(value.code)) fail();
   if (value.message !== undefined) stringAt(value.message,'/message',{empty:true});
-  return {code:value.code}; // Free text never leaves the provider boundary.
+  const message=safeProviderReason(value.message,reasons);
+  return {code:value.code,...(message === undefined ? {} : {message})}; // Only declared fixed text crosses.
 }
 export function validateBindingRequest(request) {
   canonicalJson(request,BINDING_LIMITS);
@@ -67,15 +69,19 @@ function witnessed(origin,declarations) {
       return same(a,b);
     }));
 }
-export function decodeBindingResponse(bytes,request) {
+export function decodeBindingResponse(bytes,request,{reasons}={}) {
   let response;
   try {
     validateBindingRequest(request);
+    // Out-of-band trusted caller input, NEVER a field supplied in the response.
+    // Unknown providers legitimately have no compatibility reasons; an explicit
+    // manifest declaration was already validated with the stricter nonempty bound.
+    reasons=validateBindingReasons(reasons === undefined ? providerReasons({capability:request.capability}) : reasons,{allowEmpty:true});
     response=parseStrictJson(bytes,BINDING_LIMITS);
     objectAt(response,response?.ok === true ? ['schemaVersion','phase','slot','capability','ok','result'] : ['schemaVersion','phase','slot','capability','ok','error'],
       response?.ok === true ? ['schemaVersion','phase','slot','capability','ok','result'] : ['schemaVersion','phase','slot','capability','ok','error']);
     for (const key of ['schemaVersion','phase','slot','capability']) if (response[key] !== request[key]) fail();
-    if (response.ok === false) return {ok:false,error:problem(response.error)};
+    if (response.ok === false) return {ok:false,error:problem(response.error,reasons)};
     if (response.ok !== true) fail();
     const result=response.result;
     if (request.phase === 'normalize') {
@@ -102,7 +108,7 @@ export function decodeBindingResponse(bytes,request) {
     }
     objectAt(result,['status','problems'],['status','problems']);
     if (!['ready','needs-configuration','authorization-required','unavailable'].includes(result.status) || !Array.isArray(result.problems)) fail();
-    const problems=result.problems.map(problem);
+    const problems=result.problems.map(value=>problem(value,reasons));
     if (result.status === 'ready' && problems.length) fail();
     return {ok:true,result:{status:result.status,problems}};
   } catch { fail(); }

package/lib/provider-binding.mjs

@@ -1,16 +1,21 @@
 /** Provider-owned binding protocol. This codec declares no provider model and
  * grants no execution authority; commands remain in the sole manifest table. */
-import { objectAt, stringAt, versionAt } from './portable-shape.mjs';
+import { objectAt, stringAt, stringSetAt, versionAt } from './portable-shape.mjs';
 import { FUNDAMENTAL_SLOTS } from './portable-policy.mjs';
 import { oatsError } from './errors.mjs';
+import { validateBindingReasons } from './provider-reasons.mjs';
 
 export const BINDING_PHASES = Object.freeze(['normalize', 'bind', 'check']);
 export function validateBindingInterface(manifest) {
   if (manifest.binding === undefined) return null;
   if (!FUNDAMENTAL_SLOTS.includes(manifest.layer)) throw oatsError('invalid-binding-interface', 'binding codecs belong to a fundamental provider slot');
   const binding = manifest.binding;
-  objectAt(binding, ['version', ...BINDING_PHASES], ['version', ...BINDING_PHASES], '/binding');
+  objectAt(binding, ['version', ...BINDING_PHASES, 'reasons', 'keys'], ['version', ...BINDING_PHASES], '/binding');
   versionAt(binding.version);
+  if (Object.hasOwn(binding, 'reasons')) validateBindingReasons(binding.reasons);
+  // 0.24.4 validates declarations only; ownership/routing enforcement is 0.25.
+  if (Object.hasOwn(binding, 'keys')) stringSetAt(binding.keys, '/binding/keys', (key, pointer) =>
+    stringAt(key, pointer, { pattern: /^[A-Za-z][A-Za-z0-9_-]*\.?$(?![\s\S])/ }));
   for (const phase of BINDING_PHASES) {
     const name = binding[phase];
     stringAt(name, `/binding/${phase}`, { pattern: /^[a-z0-9][a-z0-9-]*$/ });

package/lib/provider-reasons.mjs

@@ -0,0 +1,77 @@
+/** Fixed provider-declared diagnostics, never a free-text transport. Values
+ * come from the verified selected manifest or reviewed kernel compatibility
+ * data, not from a codec response, operator input or today's configuration. */
+import { invalidShape, stringAt, stringSetAt } from './portable-shape.mjs';
+
+// Compatibility literals for manifests predating binding.reasons. These are
+// data, never provider-name-dependent interpretation of payloads or settings.
+// aweb: awebai/oats-aweb v1.11.0, 862f156c883ab39c69c9e83cdf3bab86be882867.
+// oats-package/capabilities/oats-aweb/lib/{binding-wire,session-readiness}.mjs:
+// complete safeReasons/fallback/overflow/check vocabulary (no hook warnings).
+// OKF: awebai/oats-okf PR5, 0517a70a7158ebdf14ccb6e880b437c3d43cb1db,
+// same capability-relative file, settingMessages (UNRELEASED 2.1.2 at selection).
+// Released OKF 2.1.1 sends code-only; this table invents no reason for it.
+const bundled = Object.freeze({
+  'oats.aweb': Object.freeze([
+    'messaging-enabled standalone preparation needs an explicit context key',
+    'messaging binding needs one soul declaration',
+    'messaging workspace must declare private: per-human',
+    'an explicit responsible-human binding is required',
+    'an explicit wider-membership consent list is required',
+    'a selected wider-team binding is required',
+    'a selected wider alias needs an explicit workspace team mapping',
+    'multiple soul messaging declarations',
+    'adoption team aliases have conflicting mappings',
+    'messaging settings and explicit binding selections are required',
+    'messaging declarations contain incompatible requirements',
+    'messaging input must match the supported binding contract',
+    'explicit native messaging authorization is required',
+    'a required native messaging host resource is unavailable',
+    'the selected messaging provider is unavailable',
+    'the requested messaging configuration is not qualified',
+    'messaging response exceeds the supported wire limits',
+    'an admitted captured instance intent is required for execution',
+    'an explicit private-team binding is required',
+    'selected binding and inline captured invocation are required',
+    'an explicit captured instance home is required',
+    'captured messaging requires explicit delivery: session',
+    'selected wider memberships need their explicitly qualified native setup; they were not omitted',
+    'caller-owned OATS_CLI_BIN and readable kernel version are required',
+    'oats >=0.24.2 is required for captured HOME custody and retained runtime inspection',
+    'the exact retained runtime profile must be readable',
+    'the kernel must report the exact retained resolution',
+    'a retained launchSelection runtime/model observation is required',
+    'Pi strict print does not support session input; retain messaging and configure an input-capable profile',
+    'a supported input-capable ordinary Claude/Codex profile is required',
+  ]),
+  'oats.okf': Object.freeze([
+    'setting bindings-file is required (absolute host path)',
+    'setting bindings-file must be a normalized absolute host path',
+    'setting state-dir is required (absolute host path)',
+    'setting state-dir must be a normalized absolute host path',
+    'setting harvest-runtime is required (pi, claude or codex)',
+    'setting harvest-runtime must be pi, claude or codex',
+    'setting harvest-model must be null or a non-empty string',
+  ]),
+});
+const none = Object.freeze([]);
+
+export function validateBindingReasons(reasons, { allowEmpty = false } = {}) {
+  stringSetAt(reasons, '/binding/reasons', (reason, pointer) => {
+    stringAt(reason, pointer);
+    if (reason.length > 200 || /[{}]|[^\x20-\x7e]/.test(reason)) invalidShape(pointer, 'reason must be printable ASCII of at most 200 characters without braces');
+  });
+  if (reasons.length > 64 || (!allowEmpty && reasons.length === 0)) invalidShape('/binding/reasons', 'expected 1 to 64 fixed reasons');
+  return reasons;
+}
+
+export function providerReasons(manifest) {
+  if (Object.hasOwn(manifest.binding ?? {}, 'reasons')) return validateBindingReasons(manifest.binding.reasons);
+  return Object.hasOwn(bundled, manifest.capability) ? bundled[manifest.capability] : none;
+}
+
+/** Exact Unicode scalar text is exact UTF-8 text; never trim, normalize,
+ * interpolate or accept a prefix/substring. Absence preserves template fallback. */
+export function safeProviderReason(message, reasons) {
+  return typeof message === 'string' && reasons.includes(message) ? message : undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awebai/oats",
-  "version": "0.24.2",
+  "version": "0.24.4",
   "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
   "keywords": [
     "agents",