@awebai/oats 0.24.3 → 0.24.5

package/docs/packages.md

@@ -402,7 +402,7 @@ sources; installing a kernel does not advance existing package locks:
 {
   "packages": {
     "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v2.0.0", "path": "oats-package" },
-    "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.1.1", "path": "oats-package" },
+    "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.1.3", "path": "oats-package" },
     "oats.dev": { "url": "https://github.com/awebai/oats-dev.git", "ref": "v1.0.0", "path": "oats-package" }
   },
   "capabilities": { "oats.review": "oats.dev" }
@@ -429,7 +429,7 @@ integrity checks. Git transport preserves the canonical source alias.
 
 The `oats.framework` distribution package is a separate Git payload in this
 repository's `oats-package/`, excluded from the kernel npm tarball. The catalog
-entry selects the published `oats-framework/v1.1.1` tag, which exports three
+entry selects the published `oats-framework/v1.1.3` tag, which exports three
 capabilities: `oats.core` (day-to-day operation: `oats-operate`, `oats-souls`
 and the "you run on OATS" briefing — declared explicitly on every soul by
 default at creation and removable), `oats.setup` (OATS Soul Setup: `oats-config`,

package/docs/release-notes/oats-framework-v1.1.3.md

@@ -0,0 +1,11 @@
+# oats.framework 1.1.3 · aweb 1.11.2 — helper composition for every edition
+
+Packaging fix found by the independent second operator on the 0.24.4 wave: behind the operator's `responsibleHuman` requirement, preparation refused with `needs-configuration: new helper injection requires an explicit capability policy`. `oats.okf` had adopted the helper-injection contract (`omit`); its siblings **`oats.core`** and **`oats.aweb`** shipped an `inject` without a `helperInjection` policy, so no edition's OKF harvest helper could compose and **no edition could publish a resolution**. Both remaining blockers were packaging, not operator input.
+
+- **`oats.core` 1.0.1** (in oats.framework 1.1.3): `helperInjection: {version: 1, mode: inherit}` — a helper is still an OATS instance and keeps the "you run on OATS" briefing.
+- **aweb 1.11.2**: `helperInjection: {version: 1, mode: omit}` — a harvest helper has no messaging identity. Manifest-only; code identical to 1.11.0.
+- **Release check**: `test/release-packaging.test.mjs` now asserts every framework-shipped capability with an `inject` declares a `helperInjection` policy; the theory-package check pins core's `inherit`. The framework's own packages must pass the contracts the kernel imposes.
+- Catalog: `oats.aweb` → `v1.11.2`, `oats.framework` → `oats-framework/v1.1.3`; six editions and workspace imports repinned.
+- Still open (kernel, 0.25 unless a 0.24.5 is cut): this early refusal is a bare top-level error with no `details`/attribution — it must route through the same problem shape as every other preparation problem. Also noted: `responsibleHuman` is a captured accountability claim the code validates only by shape.
+
+Decision: `agents/oats-expert/soul/knowledge/decisions/helper-injection-policy-on-every-injecting-capability.md`.

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

@@ -2,7 +2,7 @@
 
 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 that names the missing item (for example `oats.okf knowledge normalize binding could not be prepared` / `oats.aweb@1.10.3 declares no binding interface; messaging cannot be prepared`). 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.
+- **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.

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/release-notes/v0.24.5.md

@@ -0,0 +1,12 @@
+# OATS v0.24.5 — four small fixes from the second-operator wave
+
+Kernel/Pi/Desktop **0.24.5**. No contract, schema or authority change. Every item was found while an independent operator (and then the lead) drove the published 0.24.4 wave to its first end-to-end resolution.
+
+- **Retirement recovers a worktree on the branch it actually has.** `oats retire` derived the recovery clone's branch from `instance.json` (the spawn-time branch); a worktree that had legitimately switched branches during its task could never pass recovery verification and became unretirable by the normal path, even with nothing unpreserved. Recovery now derives the branch from the worktree while it exists (detached HEADs recover at their exact commit), falls back to the recorded branch only when the worktree is gone, and records the drift in `recovery.json` (`branchDrift`). Fail-closed behaviour is unchanged; the source of truth moved to the object.
+- **Captured launch: `ifInstalled` runtime rows are not hard blocks, and refusals are attributed.** A provider's `requires` row marked `ifInstalled: true` (a version floor for an ambient package, if present) was treated as a hard requirement, so a Pi launch with aweb `delivery: session` could never publish a resolution — the same request without a `launch` block published fine. Such rows are now satisfied by absence in captured preparation. Remaining hard rows refuse through the ordinary preparation problem shape (`slot`, `capability`, `runtime`, `package`, the manifest's own `install` text) instead of one bare `needs-configuration`.
+- **Helper-injection refusal is attributed.** A capability that ships an `inject` without a `helperInjection` policy now yields a preparation problem naming that capability (with `origins`), so the operator learns *which* sibling has not adopted the contract rather than only that one has.
+- **`oats onboard --workspace` acquires the framework the workspace's catalog names.** The kernel tarball ships `package-catalog.json` as a snapshot at the kernel's tag, so it lags every `oats.framework` release cut afterwards; onboarding a current workspace edition against it refused as `integrity-drift` — correct, but a fresh machine has no reviewed list to point `OATS_PACKAGE_CATALOG` at. Onboarding now reads the workspace repository's `package-catalog.json` at the observed revision and uses its `oats.framework` entry; the bundled entry is the fallback, `OATS_PACKAGE_CATALOG` still overrides. The result reports `catalog.origin`, and a drift refusal names the lag and both integrities.
+
+Rule going forward (recorded in the maintainer's knowledge): **`prepare` never ends in a bare `needs-configuration` after selection** — every refusal is a problem with a slot/capability, or it is a kernel defect. Remaining bare sites are pre-selection input errors, record-shape guards and the skill-name collision, none reachable from a published edition.
+
+Not in this release: `binding.keys` enforcement and the dotted-exact-key grammar (0.25); OKF `check` per-cause reasons (OKF 2.1.3, deferred with harvest).

package/docs/workspace-adoption.md

@@ -44,64 +44,88 @@ 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.2** and
+  messaging **oats.aweb@1.11.2** (both OATS >=0.24.4), 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
+- Published OKF 2.1.2 supports `inherit: stores.oats`, normalized to
   `/bindings/knowledge/stores/oats`. The explicit `destination: oats` preserves
   routing; omitting it would instead require `write.default`. No new schema,
   owner or production locator is needed for this declaration.
 - aweb 1.10.3 (`24efa6f9`) has no portable binding interface; **aweb 1.11.0**
-  (`v1.11.0`, OATS >=0.24.2) adds it and the five editions now pin it. Its `check`
+  (`v1.11.0`, OATS >=0.24.2) adds it; **1.11.1/1.11.2** (OATS >=0.24.4) are code-identical and declare its fixed reasons, owned operator keys and `helperInjection: omit` (a harvest helper has no messaging identity); the five editions pin 1.11.2. Its `check`
   qualifies only an input-capable Claude/Codex primary with an explicit private team
   and `delivery: session`; strict-Pi print reports `needs-configuration`. Status is on
   the [program board](design/2026-09-20-redesign-program-board.md). Qualification
   is HOME-route operational custody only: not human/native-principal delegation,
   private grants, broker delivery or model consumption.
-- Published OKF2.1.1 accepts retained Claude/Codex helpers with the complete approved
+- Published OKF 2.1.2 accepts retained Claude/Codex helpers with the complete approved
   capability closure and native-default model intent. Strict Pi still requires an
   explicit model and the sole-OKF profile; Pi plus messaging remains unqualified.
   This provider release alone is not combined-profile acceptance. Do not silently
@@ -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
+OKF 2.1.2 and aweb 1.11.2 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/docs/workspaces.md

@@ -71,7 +71,7 @@ name: domain-expert
 requires:
   knowledge:
     capability: oats.okf
-    source: git:github.com/awebai/oats-okf@v2.1.1#oats-package
+    source: git:github.com/awebai/oats-okf@v2.1.2#oats-package
 ```
 
 This illustrates software selection, not complete OKF provisioning: the chosen capability also needs its own valid knowledge declaration, bindings and accepted base.

package/lib/captured-launch-request.mjs

@@ -32,8 +32,28 @@ export function validateCapturedLaunchRequest(value, validateConfig) {
 export function compileCapturedLaunchRequest(request,{artifacts,manifests,settings,resources},kernel) {
   if(request===undefined)return null;
   validateCapturedLaunchRequest(request,kernel.validateLaunchConfig);
-  const required=kernel.runtimeRequirements(request.runtime,[...manifests].filter(([id])=>Object.hasOwn(artifacts.capabilities,id)).map(([id,manifest])=>({id,manifest,settings:settings[id]})));
-  if(required.length)throw oatsError('needs-configuration','runtime package requirements need retained runtime roots and a qualified loader; no ambient package discovery was used');
+  const providers=[...manifests].filter(([id])=>Object.hasOwn(artifacts.capabilities,id)).map(([id,manifest])=>({id,manifest,settings:settings[id]}));
+  // `ifInstalled: true` rows constrain a package that may legitimately be absent (a version floor
+  // for an ambient extension, if any). Captured preparation retains no ambient packages, so such a
+  // row is satisfied by absence — treating it as a hard requirement made a Pi launch with aweb
+  // `delivery: session` unpublishable (second-operator finding, 2026-09-21). Hard rows refuse
+  // through the preparation problem shape, naming the capability and package; the remedy text is
+  // the manifest's own `install` string — declared data, never free text.
+  // Resolve each applicable row back to its declaration, honouring the same `when` predicate the
+  // kernel's requirement selection uses, so two rows for one package (channel vs session) stay distinct.
+  const holds=(provider,row)=>!row.when || Object.entries(row.when).every(([k,v])=>String(provider.settings?.[k] ?? '')===String(v));
+  const declarationOf=(row)=>{const provider=providers.find(p=>p.id===row.capability);
+    return {provider,declared:provider?.manifest?.requires?.find(r=>r && typeof r==='object' && r.runtime===request.runtime && r.package===row.package && holds(provider,r))};};
+  const required=kernel.runtimeRequirements(request.runtime,providers).filter(row=>declarationOf(row).declared?.ifInstalled!==true);
+  if(required.length){
+    const error=oatsError('needs-configuration','runtime package requirements need retained runtime roots and a qualified loader; no ambient package discovery was used');
+    error.problems=required.map(row=>{
+      const {provider,declared}=declarationOf(row);
+      return {code:'needs-configuration',message:`${request.runtime} launch requires runtime package ${row.package}, which captured preparation has not retained`,capability:row.capability,
+        ...(provider?.manifest?.layer?{slot:provider.manifest.layer}:{}),runtime:request.runtime,package:row.package,...(typeof declared?.install==='string'?{install:declared.install}:{})};
+    });
+    throw error;
+  }
   const base={version:1,runtime:request.runtime,args:request.args,env:request.env,model:request.model,yolo:request.yolo,
     hooks:{launch:{},env:{},contributions:[],pending:true},prompt:{kind:'task-file',file:'TASK.md'}};
   if(typeof request.executable==='string')return {...base,executable:request.executable,executableResolvedFrom:'explicit-host'};

package/lib/core.mjs

@@ -7080,6 +7080,15 @@ function fingerprintTree(root, { excludeRoot = new Set(), excludeGitMetadata = f
   return `sha256:${hash.digest("hex")}`;
 }
 
+/** The ref a worktree actually has checked out: `{branch, oid}` with
+ *  `branch === null` when HEAD is detached. Recovery derives truth from the
+ *  object, never from spawn-time metadata. */
+function worktreeRef(work) {
+  const oid = execFileSync("git", ["-C", work, "rev-parse", "HEAD"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER }).trim();
+  let branch = null;
+  try { branch = execFileSync("git", ["-C", work, "symbolic-ref", "--quiet", "--short", "HEAD"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER }).trim() || null; } catch { branch = null; }
+  return { branch, oid };
+}
 function worktreeStatus(repo) {
   try {
     return execFileSync("git", ["-C", repo, "status", "--porcelain=v1", "-z", "--untracked-files=all", "--ignored=matching", "--ignore-submodules=none"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] , maxBuffer: GIT_MAX_BUFFER });
@@ -8304,9 +8313,21 @@ function preserveRetirementWork(observation, meta, instance) {
     if (fingerprintTree(observation.home, { excludeRoot: new Set(["work"]) }) !== fingerprintTree(recoveredHome)) {
       throw new Error("home recovery verification disagreed with the source");
     }
+    let branchDrift;
     if (!homeOnly && meta.work === "worktree" && meta.repo && meta.branch && (existsSync(observation.work) || observation.branchExists)) {
       const recoveredRepo = join(staging, "repo");
-      execFileSync("git", ["clone", "--no-local", "--quiet", "--branch", meta.branch, meta.repo, recoveredRepo], { stdio: ["ignore", "pipe", "pipe"] , maxBuffer: GIT_MAX_BUFFER });
+      // The branch is derived from the worktree while it exists: an instance
+      // that legitimately switched branches during its task must still be
+      // recoverable, and the recorded spawn-time branch is only the fallback
+      // when the worktree is gone. Detached HEADs recover at their exact OID.
+      const ref = existsSync(observation.work) ? worktreeRef(observation.work) : { branch: meta.branch, oid: null };
+      if (ref.branch !== meta.branch) branchDrift = { recordedBranch: meta.branch, worktreeBranch: ref.branch, detachedAt: ref.branch === null ? ref.oid : null };
+      if (ref.branch !== null) execFileSync("git", ["clone", "--no-local", "--quiet", "--branch", ref.branch, meta.repo, recoveredRepo], { stdio: ["ignore", "pipe", "pipe"] , maxBuffer: GIT_MAX_BUFFER });
+      else {
+        execFileSync("git", ["clone", "--no-local", "--quiet", "--no-checkout", meta.repo, recoveredRepo], { stdio: ["ignore", "pipe", "pipe"] , maxBuffer: GIT_MAX_BUFFER });
+        execFileSync("git", ["-C", recoveredRepo, "fetch", "--quiet", observation.work, ref.oid], { stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER });
+        execFileSync("git", ["-C", recoveredRepo, "checkout", "--quiet", "--detach", ref.oid], { stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER });
+      }
       const sourceGitContext = existsSync(observation.work) ? observation.work : meta.repo;
       detachRecoveryClone(sourceGitContext, recoveredRepo);
       if (existsSync(observation.work)) {
@@ -8325,7 +8346,8 @@ function preserveRetirementWork(observation, meta, instance) {
         if (worktreeStatus(observation.work) !== worktreeStatus(recoveredRepo)) throw new Error("recovered Git index/status disagreed with the source");
       }
       const recoveredHead = execFileSync("git", ["-C", recoveredRepo, "rev-parse", "HEAD"], { encoding: "utf8" , maxBuffer: GIT_MAX_BUFFER }).trim();
-      const sourceHead = execFileSync("git", ["-C", meta.repo, "rev-parse", `refs/heads/${meta.branch}`], { encoding: "utf8" , maxBuffer: GIT_MAX_BUFFER }).trim();
+      const sourceHead = ref.branch === null ? ref.oid
+        : execFileSync("git", ["-C", meta.repo, "rev-parse", `refs/heads/${ref.branch}`], { encoding: "utf8" , maxBuffer: GIT_MAX_BUFFER }).trim();
       if (recoveredHead !== sourceHead) throw new Error("recovery clone does not retain the instance branch tip");
     }
     if (observation.directory && observation.directoryFingerprint) {
@@ -8336,7 +8358,7 @@ function preserveRetirementWork(observation, meta, instance) {
       }
     }
     const repoCopy = homeOnly ? { copied: false, reason: "Only instance-home bytes changed; no work state requires a repository copy", source: meta.repo, branch: meta.branch } : undefined;
-    writeFileSync(join(staging, "recovery.json"), JSON.stringify({ version: 1, instance, classes: observation.classes, sourceHome: observation.home, createdAt: new Date().toISOString(), ...(repoCopy ? { repoCopy } : {}) }, null, 2) + "\n", { mode: 0o600 });
+    writeFileSync(join(staging, "recovery.json"), JSON.stringify({ version: 1, instance, classes: observation.classes, sourceHome: observation.home, createdAt: new Date().toISOString(), ...(repoCopy ? { repoCopy } : {}), ...(branchDrift ? { branchDrift } : {}) }, null, 2) + "\n", { mode: 0o600 });
     mkdirSync(dirname(recovery), { recursive: true });
     renameSync(staging, recovery);
     return { path: recovery, classes: observation.classes, ...(repoCopy ? { repoCopy } : {}) };

package/lib/helper-injection-policy.mjs

@@ -35,7 +35,13 @@ export function captureHelperInjectionChoices(plan, definitions) {
     const policy = helperInjectionFact(definition), id = definition.artifact.capability;
     if (policies.has(id)) throw oatsError('invalid-resolution', 'duplicate helper policy owner');
     policies.set(id, policy);
-    if (!policy.fact && policy.manifest.inject) throw oatsError('needs-configuration', 'new helper injection requires an explicit capability policy');
+    if (!policy.fact && policy.manifest.inject) {
+      // Attributed like every other preparation problem: the operator learns WHICH
+      // capability lacks the declaration, not only that one does (second-operator finding).
+      const error = oatsError('needs-configuration', 'new helper injection requires an explicit capability policy');
+      error.problems = [{ code: 'needs-configuration', message: 'capability ships an inject without a helperInjection policy', capability: id, ...(policy.manifest.layer ? { slot: policy.manifest.layer } : {}) }];
+      throw error;
+    }
     if (policy.fact) requirements.push(policy.fact);
   }
   const resolved = resolveChoices({ requirements, candidates: plan.candidates });

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([
@@ -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 = inspectWorkTarget(input.workTarget), discovery = createWorkspaceDiscovery(repositories);
-  const witness = { deployment: preflightWitnesses.get(deployment), work: directoryIdentity(target.path) };
+  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 },
@@ -241,7 +246,9 @@ export function buildFreshPreparationRequest(inspection, options = {}) {
     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/prepare-composition.mjs

@@ -31,6 +31,16 @@ function packageSubset(artifacts, root) {
 
 /** Repositories and kernel callbacks belong to this operation; the caller owns
  * their lifetime/scratch cleanup. No hook, launch, enrollment or approval here. */
+/** Origins of the choices that selected a capability — the same derivation preparation
+ *  bindings use, so completion refusals render beside binding problems. */
+function originsOf(plan, capability) {
+  const seen = new Map();
+  for (const key of plan.capabilities?.[capability]?.choiceKeys ?? []) {
+    const origin = plan.choices?.[key]?.selectedBy;
+    if (origin) seen.set(canonicalJson(origin), origin);
+  }
+  return [...seen.values()];
+}
 export function prepareComposition(input, { repositories, kernel, previous: suppliedPrevious }) {
   canonicalJson(input);
   objectAt(input, ["deployment", "directory", "source", "origin", "workspace", "member", "operator", "mode", "allowLocalPaths", "standaloneContextKey", "launch", "helperLaunches"], ["deployment", "directory", "source", "origin"]);
@@ -114,8 +124,17 @@ export function prepareComposition(input, { repositories, kernel, previous: supp
     if (operator) declarations.push(operatorBindingDeclaration(operator));
     const bound = prepareProviderBindings({ seed, plan, manifests, declarations }, options => kernel.binding({ ...options, deployment }));
     plan = bound.plan; seed = bound.seed;
-    const completion = bound.problems.length ? { record: null, problems: bound.problems }
-      : kernel.complete({ seed, plan, manifests, mode, deployment, directory, launch: input.launch, helperLaunches: input.helperLaunches });
+    let completion;
+    if (bound.problems.length) completion = { record: null, problems: bound.problems };
+    else {
+      try { completion = kernel.complete({ seed, plan, manifests, mode, deployment, directory, launch: input.launch, helperLaunches: input.helperLaunches }); }
+      catch (error) {
+        // A typed completion refusal that names its capability is a preparation problem like any
+        // other (slot/capability/origins), never a bare top-level error. Anything else propagates.
+        if (!Array.isArray(error?.problems) || !["needs-configuration", "requirement-conflict"].includes(error.code)) throw error;
+        completion = { record: null, problems: error.problems.map(problem => ({ ...problem, origins: problem.origins ?? originsOf(plan, problem.capability) })) };
+      }
+    }
     let resolution = null;
     if (completion.record) resolution = commitCapturedResolution(deployment, completion.record);
     // Publishing valid immutable inputs/records need not roll back on a later

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. */
@@ -42,7 +43,7 @@ export function prepareProviderBindings({seed,plan,manifests,declarations},invok
   }).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',
-    `${id} ${slot} ${phase} binding could not be prepared`); // Never provider free text.
+    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(problem(manifest.layer,id,'needs-configuration','fundamental capability must be selected in its own layer'));

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-]*$/ });