@awebai/oats 0.24.8 → 0.24.9

package/bin/oats.mjs

@@ -600,6 +600,12 @@ function officialMigrationState(legacyLocks, { teamScope, ctx }) {
  * nearer scope's package of the same id — a provider that never exported it. */
 const levelRows = (locks, level) => locks.levels.find((l) => l.level === level) || { packages: Object.create(null), capabilities: Object.create(null) };
 
+/** A capability has an executable surface when its manifest declares commands,
+ *  hooks or launch environment — the things `oats trust` approves. A
+ *  data-only capability (skills/injects) has none, and trust is not-applicable. */
+function hasExecutableSurface(manifest) {
+  return !!(Object.keys(manifest?.commands || {}).length || Object.keys(manifest?.hooks || {}).length || (manifest?.environment?.length || 0));
+}
 function capabilityHealth(level, cap, capRow, pkgRow) {
   const dir = installedCapabilityDir(level, cap.id);
   if (!cap.installed) return { status: "missing", code: "missing-capability-artifact", dir, detail: `capability ${cap.id} is locked but not materialized — run \`oats install\` to re-materialize it` };
@@ -615,9 +621,7 @@ function capabilityHealth(level, cap, capRow, pkgRow) {
     try { verifyCapabilityInstallation(dir, cap.id, capRow, pkgRow); }
     catch (e) { return { status: "provenance-mismatch", code: e.code || "invalid-lock", dir, integrity, detail: `capability ${cap.id}: ${e.message}` }; }
   }
-  const executable = Object.keys(cap.manifest?.commands || {}).length
-    || Object.keys(cap.manifest?.hooks || {}).length
-    || (cap.manifest?.environment?.length || 0);
+  const executable = hasExecutableSurface(cap.manifest);
   if (executable && !cap.trusted) return { status: "untrusted", code: "untrusted-surface", dir, integrity, detail: `capability ${cap.id}: executable surface UNTRUSTED — \`oats trust ${cap.id}\`` };
   return { status: "ok", code: null, dir, integrity, detail: null };
 }
@@ -945,7 +949,7 @@ function computeInspect({ onFail } = {}) {
         byId.set(c.id, {
           id: c.id, package: p.package, version: c.version || null, layer: c.manifest?.layer || null, command: c.manifest?.command || null,
           origin: "installed", level: p.level, source: p.source || null, commit: p.commit ?? rows.packages[p.package]?.commit ?? null, dir: h.dir,
-          health: { status: h.status, code: h.code, detail: h.detail, installed: !!c.installed, locked: true, trusted: c.trusted === true, integrity: c.integrity || null, installedIntegrity: h.integrity ?? null },
+          health: { status: h.status, code: h.code, detail: h.detail, installed: !!c.installed, locked: true, trusted: c.trusted === true, executableSurface: hasExecutableSurface(c.manifest), integrity: c.integrity || null, installedIntegrity: h.integrity ?? null },
         });
       }
     }
@@ -953,13 +957,13 @@ function computeInspect({ onFail } = {}) {
   for (const [id, m] of Object.entries(mans)) {
     if (byId.has(id)) continue;
     const trust = capabilityTrust(m, ctx);
-    const executable = Object.keys(m.commands || {}).length || Object.keys(m.hooks || {}).length || (m.environment?.length || 0);
+    const executable = hasExecutableSurface(m);
     let integrity = trust.integrity || null;
     if (!integrity) { try { integrity = capabilityArtifactIntegrity(m._dir); } catch { integrity = null; } }
     byId.set(id, {
       id, package: m._package || null, version: m.version || null, layer: m.layer || null, command: m.command || null,
       origin: String(m._origin || "").split(":")[0] || "unknown", level: String(m._origin || "").split(":").slice(1).join(":") || null, source: null, dir: m._dir,
-      health: { status: executable && !trust.trusted ? "untrusted" : "ok", code: executable && !trust.trusted ? "untrusted-surface" : null, detail: executable && !trust.trusted ? (trust.reason || null) : null, installed: true, locked: !!trust.lock, trusted: !!trust.trusted, integrity, installedIntegrity: integrity },
+      health: { status: executable && !trust.trusted ? "untrusted" : "ok", code: executable && !trust.trusted ? "untrusted-surface" : null, detail: executable && !trust.trusted ? (trust.reason || null) : null, executableSurface: executable, installed: true, locked: !!trust.lock, trusted: !!trust.trusted, integrity, installedIntegrity: integrity },
     });
   }
   // What is EFFECTIVE for the answer: a home's captured bindings and settings
@@ -3215,17 +3219,33 @@ function instanceCmd() {
     bail(e.code || "E_GIT_FAILED", e.message, e.observation ? { observation: e.observation } : undefined);
   }
 }
-/** `oats readiness [--soul <name>] [--home <abs>] [--verify-signatures] [--policy] [--dir <d>] --json` — K5. */
+/** `oats readiness [--soul <name> [--agents-root <abs>]] [--home <abs>] [--verify-signatures] [--policy] [--dir <d>] --json` — K5. */
 function readinessCmd() {
   const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
   dropAmbientRoot();
+  // A captured incarnation's readiness comes from its retained resolution, not
+  // from the current configuration this command reads; refuse before inspecting.
+  const homeArg = flag("home");
+  if (homeArg && homeArg !== true) {
+    let capturedMeta = null; try { capturedMeta = JSON.parse(readFileSync(join(String(homeArg), "instance.json"), "utf8")); } catch { /* computeInspect reports the unreadable home */ }
+    if (capturedMeta?.executionBinding || capturedMeta?.captured) return bail("E_UNSUPPORTED_MODE", `${basename(String(homeArg))} is a captured incarnation: its readiness is the retained resolution's, not the current configuration's (inspect it with oats operation --deployment/--resolution)`, { home: String(homeArg), captured: true });
+  }
   const inspect = computeInspect({ onFail: bail });
   if (!inspect) return;
   const soul = flag("soul") === true ? null : flag("soul") || inspect.selected?.soul || null;
   const verify = args.includes("--verify-signatures");
   let catalog = null; try { catalog = describeOfficialCatalog(); catalog = { packages: Object.fromEntries(catalog.packages.map((p) => [p.package, p])) }; } catch { catalog = null; }
   const deploymentDir = inspect.scope?.context ?? null;
-  const readiness = readinessOf(inspect, { soul, verifySignatures: verify, catalog, deploymentDir });
+  // Echo the exact selector this read was made with, so a consumer can bind the
+  // result to its own admitted target without inventing a revision.
+  // Every field is the argument AS GIVEN (no realpath): a consumer compares it
+  // byte-exact with what it sent. The canonical scope is subject.context.
+  const given = (name) => { const v = flag(name); return v && v !== true ? String(v) : null; };
+  const agentsRootArg = given("agents-root"), dirArg = given("dir");
+  const selector = homeArg && homeArg !== true ? { kind: "home", home: String(homeArg), soul, agentsRoot: agentsRootArg }
+    : soul ? { kind: "soul", soul, agentsRoot: agentsRootArg, dir: dirArg }
+    : { kind: "scope", dir: dirArg };
+  const readiness = readinessOf(inspect, { soul, verifySignatures: verify, catalog, deploymentDir, selector });
   if (args.includes("--policy")) {
     const homeOpt = flag("home");
     let meta = null;
@@ -4162,7 +4182,21 @@ function spawnCmd() {
   let root;
   try { root = ensureRoot(dirFlag()); }
   catch (e) { bail("E_NO_DEPLOYMENT", e.message || e); throw e; }
+  const isPreview = args.includes("--preview");
+  // --agents-root <abs>: the exact root the soul must live in (as inspect and
+  // readiness take it). With it, no team-soul / capability-agent / importable-
+  // def fallback: the soul is there or the spawn refuses E_SOUL_UNKNOWN.
+  const agentsRootFlag = flag("agents-root");
+  if (agentsRootFlag !== undefined && (agentsRootFlag === true || !isAbsolute(String(agentsRootFlag)))) bail("E_BAD_ARGS", "--agents-root needs an absolute agents root");
+  if (agentsRootFlag !== undefined && realOrResolved(String(agentsRootFlag)) !== realOrResolved(root)) {
+    const teamHit = findTeamAgent(dirFlag(), name), hit = (teamHit?.matches || []).find((m) => realOrResolved(m.root) === realOrResolved(String(agentsRootFlag)));
+    if (!hit) bail("E_SOUL_UNKNOWN", `soul "${name}" is not at agents root ${String(agentsRootFlag)} (this scope's root is ${shortPath(root)})`);
+    root = hit.root;
+  }
   let agent = findAgent(root, name);
+  if (agentsRootFlag !== undefined && !agent) bail("E_SOUL_UNKNOWN", `soul "${name}" is not at agents root ${String(agentsRootFlag)}`);
+  if (isPreview && !agent) bail("E_SOUL_UNKNOWN", `soul "${name}" is not in ${shortPath(root)}; a preview never creates or imports a soul (known: ${listAgents(root).map((a) => a.name).join(", ") || "none"})`);
+  if (isPreview && (flag("instructions-file") !== undefined || flag("def-file") !== undefined)) bail("E_BAD_ARGS", "--preview does not take --instructions-file/--def-file: a preview never writes a soul");
   const instrFile = flag("instructions-file");
   const defFile = flag("def-file");
   if (!agent && !instrFile && !defFile) {
@@ -4285,8 +4319,10 @@ function spawnCmd() {
       // K6: --preview decides everything and touches nothing; --base <ref>
       // selects a worktree's start point; --model @native-default is the
       // explicit "runtime's own default" (distinct from omitting --model).
-      ...(args.includes("--preview") ? { preview: true } : {}),
+      ...(args.includes("--preview") ? { preview: true, subject: { soul: name, agentsRoot: agentsRootFlag !== undefined ? String(agentsRootFlag) : null, dir: flag("dir") !== undefined && flag("dir") !== true ? String(flag("dir")) : null } } : {}),
       ...(flag("base") !== undefined && flag("base") !== true ? { baseRef: flag("base") } : {}),
+      // A confirmed preview binds this apply (K6b): drift → E_DECISION_STALE, nothing created.
+      ...(flag("expect-decision") !== undefined && flag("expect-decision") !== true ? { expectDecision: String(flag("expect-decision")) } : {}),
     });
     if (args.includes("--preview")) { if (JSON_MODE) { jsonOk(r); return; } console.log(`preview ${r.agent} → ${r.instance} (${r.work}${r.branch ? `, branch ${r.branch} from ${r.base.ref}@${r.base.oid.slice(0, 12)}` : ""}) runtime ${r.runtime}${r.model ? ` model ${r.model}` : ` (${r.modelSource})`}; nothing was created`); return; }
   } catch (e) {
@@ -4304,6 +4340,8 @@ function spawnCmd() {
     if (e?.code === "E_REQUIREMENT_INACTIVE") { bail(e.code, e.message, { soul: e.soul, capabilities: e.capabilities, context: e.context, remedy: e.remedy }); throw e; }
     if (e?.code === "E_CHILD_SPAWNS_DISABLED") { bail(e.code, e.message, { parent: e.parent, policy: e.policy }); throw e; }
     if (["E_BRANCH_EXISTS", "E_BASE_UNKNOWN"].includes(e?.code)) { bail(e.code, e.message); throw e; }
+    // K6b: the confirmed decision drifted — the fresh decision travels with the refusal so a GUI re-previews.
+    if (e?.code === "E_DECISION_STALE") { bail(e.code, e.message, { decision: e.decision }); throw e; }
     bail(["E_BAD_ARGS", "E_RELATIVE_AMBIGUOUS"].includes(e.code) ? e.code : "E_SPAWN_FAILED", e.message || e); throw e;
   }
   // The instance exists from here on: a failed wake save is reported beside
@@ -4980,7 +5018,7 @@ function versionCmd() {
     // on it (an older CLI without the surface must fail closed with a
     // reason, not an argument error). `features`: kernel abilities a peer
     // must see before relying on them (retire-home: retire --home).
-    console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, runtimes: ["pi", "claude", "codex"], sessionBackends: ["tmux", "herdr"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations"], features: ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "session-upload", "operations", "catalog", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "schedule-history", "session-recompose"], instanceGitApi: 1, soulsApi: 1, lifecycleApi: 1, readinessApi: 1, spawnPreviewApi: 1, eventsApi: 1, scheduleHistoryApi: 2, scheduleApi: SCHEDULE_API, operationsApi: 1, capturedDispatchApi: 1, capturedDispatchActions: ["inspect", "compose", "command", "operation", "spawn", "trust"] }));
+    console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, runtimes: ["pi", "claude", "codex"], sessionBackends: ["tmux", "herdr"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations"], features: ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "session-upload", "operations", "catalog", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "schedule-history", "session-recompose", "readiness-verify", "spawn-preview-2"], instanceGitApi: 1, soulsApi: 1, lifecycleApi: 1, readinessApi: 1, spawnPreviewApi: 2, eventsApi: 1, scheduleHistoryApi: 2, scheduleApi: SCHEDULE_API, operationsApi: 1, capturedDispatchApi: 1, capturedDispatchActions: ["inspect", "compose", "command", "operation", "spawn", "trust"] }));
     return;
   }
   console.log(`@awebai/oats ${OATS_VERSION} (desktop API v1)`);
@@ -5639,7 +5677,10 @@ Usage:
   oats instance stop <instance> --apply --plan-revision <rev> --idempotency-key <key>
                                              quiesce (SIGTERM, bounded, never escalated),
                                              children first; home/work/launch retained
-  oats readiness [--soul <n>] [--home <abs>] [--verify-signatures] [--policy] [--json]
+  oats readiness [--soul <n> [--agents-root <abs>]] [--home <abs>] [--verify-signatures] [--policy] [--json]
+                                             quartet installed|trusted|configured|enrolled for a scope,
+                                             a soul, or an instance home (captured homes refuse:
+                                             their readiness is the retained resolution's)
                                              installed | trusted | configured | enrolled, each
                                              pass|fail|unknown|not-applicable with items and
                                              remedies; signature status per artifact; enforced

package/capabilities/oats-okf/bin/oats-okf.mjs

@@ -2,7 +2,7 @@
 import { randomUUID } from 'node:crypto';
 import { fs, join, dirname, resolve, readJSON, save, safePath, cliPath, oats, fail, unlock } from '../lib/io.mjs';
 import { loadBindings, declaration, splitRef } from '../lib/config.mjs';
-import { register, registerCaptured, loadInvocationSourceReceipt, homeSource, loadSource, loadStatus, saveStatus, updateStatus, capture, scheduleSource, service, markerPath, views } from '../lib/sources.mjs';
+import { register, registerCaptured, loadInvocationSourceReceipt, homeSource, loadSource, loadStatus, saveStatus, updateStatus, capture, scheduleSource, settleRetiredSchedule, service, markerPath, views } from '../lib/sources.mjs';
 import { runSource, complete, retry, readRun, requireQualifiedHelper } from '../lib/worker.mjs';
 import { initBase, migrate, deliverMigration, cutoverMigration, migrateSource } from '../lib/migration.mjs';
 import { inspect } from '../lib/inspection.mjs';
@@ -121,13 +121,13 @@ else {
         let s;
         if(sourceReceipt.mode==='captured') {s=registerCaptured(home,sourceReceipt.receipt);if(s.skipped) {result={meta:{retired:true,reason:'service'}};s=null;}}
         else {if(!fs.existsSync(markerPath(home))) fail('E_MIGRATION','captured retire requires a durable registered source or explicit helper receipt');s=src();}
-        if(s) {scheduleSource(s);const r=capture(s,{final:true});result={meta:{retired:r.complete===true,source:s.file,capture:r},brief:'Final input is in durable custody. Delivery remains asynchronous.'};}
+        if(s) {scheduleSource(s);const r=capture(s,{final:true});const schedule=settleRetiredSchedule(s);result={meta:{retired:r.complete===true,source:s.file,capture:r,schedule},brief:'Final input is in durable custody. Delivery remains asynchronous.'};}
       } else if(service(home)) result={meta:{retired:true}};
       else if(!fs.existsSync(markerPath(home))) {
         if(['STATE.md','log.md','notes','.okf-harvest-record.json','.okf-harvest-record.next.json'].some(p=>fs.existsSync(join(home,p)))) fail('E_MIGRATION','unregistered/legacy source has memory; explicitly migrate/register before retirement');
         result={meta:{retired:true,reason:'nothing-to-delete'}};
       } else {
-        const s=src();scheduleSource(s);const r=capture(s,{final:true});result={meta:{retired:r.complete===true,source:s.file,capture:r},brief:'Final input is in durable custody. Delivery remains asynchronous.'};
+        const s=src();scheduleSource(s);const r=capture(s,{final:true});const schedule=settleRetiredSchedule(s);result={meta:{retired:r.complete===true,source:s.file,capture:r,schedule},brief:'Final input is in durable custody. Delivery remains asynchronous.'};
       }
     } else if(event==='harvest') {
       if(capturedHarvest) {

package/capabilities/oats-okf/lib/binding-wire.mjs

@@ -245,7 +245,27 @@ export function loadInvocationKnowledgeBinding(env=process.env) {
   let runtime;try{runtime=sourceRuntimeFromKnowledgeBinding(binding);}catch{invocationError();}
   return {kind:'captured',file,binding,runtime};
 }
-function problem(code) {return {code};}
+// Closed vocabulary of check-phase reasons: one fixed literal per cause, so the
+// operator learns WHICH qualification failed without any value, path, alias or
+// caught message reaching the wire. Every literal is also in oats.json
+// binding.reasons (byte-exact) — the manifest test pins that.
+const checkReasons=Object.freeze({
+  'action:not-admitted':'check action is not an admitted knowledge operation',
+  'bindings:invalid':'bound runtime bindings file is missing or invalid',
+  'bases:too-many':'more than 64 git knowledge bases declared',
+  'base:stage-failed':'declared knowledge base could not be staged from its git source',
+  'base:not-validated':'declared knowledge base is not a validated knowledge tree',
+  'base:owner-unmet':'knowledge base owner or remote custody requirement not met',
+  'base:source-mismatch':'staged git source does not match the declared knowledge base',
+  'runtime:command-missing':'harvest runtime command is not installed on this host',
+  'runtime:not-qualified':'harvest runtime could not be qualified against the accepted bases',
+});
+function problem(code,reason) {
+  if(reason===undefined) return {code};
+  if(!Object.hasOwn(checkReasons,reason)) wireError('invalid-binding');
+  return {code,message:checkReasons[reason]};
+}
+export const CHECK_REASONS=Object.values(checkReasons);
 function providerActionName(action) {
   if(action.kind==='operation' && action.slot===SLOT) return action.name;
   if(action.kind!=='command') return null;
@@ -261,19 +281,26 @@ function checkPhase(req) {
   const harvestInvocation=req.input.invocation;
   const admittedHarvest=name==='harvest' && action.kind==='operation' && action.slot==='knowledge' && action.name==='harvest'
     && harvestInvocation?.subject.kind==='persistent' && harvestInvocation.instance!==null && !!harvestInvocation.intent;
-  if(name && (unsupportedCapturedCommands.has(name) || name==='run-source' || (name==='harvest' && !admittedHarvest))) return {status:'needs-configuration',problems:[problem('provider-not-qualified')]};
+  if(name && (unsupportedCapturedCommands.has(name) || name==='run-source' || (name==='harvest' && !admittedHarvest))) return {status:'needs-configuration',problems:[problem('provider-not-qualified','action:not-admitted')]};
   if(action.kind==='hook' && action.name==='soul-scaffold') return {status:'ready',problems:[]};
-  let bindings;try{bindings=validateBindings(runtime.bindings,runtime.descriptorFile);}catch{return {status:'needs-configuration',problems:[problem('needs-configuration')]};}
+  let bindings;try{bindings=validateBindings(runtime.bindings,runtime.descriptorFile);}catch{return {status:'needs-configuration',problems:[problem('needs-configuration','bindings:invalid')]};}
   const accepted={},gitBases=Object.entries(bindings.bases).filter(([,base])=>base.kind==='git');
-  if(gitBases.length>64) return {status:'unavailable',problems:[problem('provider-not-qualified')]};
-  let scratch=null;
+  if(gitBases.length>64) return {status:'unavailable',problems:[problem('provider-not-qualified','bases:too-many')]};
+  let scratch=null,stage='base';
   try {
     if(gitBases.length) scratch=fs.mkdtempSync(join(fs.realpathSync(tmpdir()),'oats-okf-binding-check-'));
-    for(const [alias,base] of Object.entries(bindings.bases)) accepted[alias]=(base.kind==='directory'?validateBase(base.path,base):stageBase(base,join(scratch,alias))).meta;
+    for(const [alias,base] of Object.entries(bindings.bases)) {
+      stage=base.kind==='directory'?'validate':'stage';
+      accepted[alias]=(base.kind==='directory'?validateBase(base.path,base):stageBase(base,join(scratch,alias))).meta;
+    }
+    stage='runtime';
     checkKnowledgeRuntime({rendered:runtime,accepted});
   } catch(error) {
-    if(error.code==='E_COMMAND') return {status:'unavailable',problems:[problem('provider-unavailable')]};
-    if(['E_OWNER','E_BASE','E_VALIDATION','E_DIRECTORY_GIT','E_CONFIRM'].includes(error.code)) return {status:'needs-configuration',problems:[problem('provider-not-qualified')]};
+    if(error.code==='E_COMMAND') return {status:'unavailable',problems:[problem('provider-unavailable','runtime:command-missing')]};
+    if(error.code==='E_OWNER') return {status:'needs-configuration',problems:[problem('provider-not-qualified','base:owner-unmet')]};
+    if(error.code==='E_CONFIRM') return {status:'needs-configuration',problems:[problem('provider-not-qualified','base:source-mismatch')]};
+    if(['E_BASE','E_VALIDATION','E_DIRECTORY_GIT'].includes(error.code)) return {status:'needs-configuration',problems:[problem('provider-not-qualified',stage==='stage'?'base:stage-failed':'base:not-validated')]};
+    if(stage==='runtime') return {status:'unavailable',problems:[problem('provider-unavailable','runtime:not-qualified')]};
     return {status:'unavailable',problems:[problem('provider-unavailable')]};
   } finally {
     if(scratch) fs.rmSync(scratch,{recursive:true,force:true});

package/capabilities/oats-okf/lib/config.mjs

@@ -67,6 +67,7 @@ export function loadBindings(file = settings()['bindings-file'], opts = {}) {
 export function declaration(soul) {
   if(fs.existsSync(join(soul,'.okf-cutover.json'))) fail('E_MIGRATION','incomplete explicit migration cutover: rerun its recorded migrate --cutover command');
   if(fs.existsSync(join(soul,'knowledge'))) fail('E_MIGRATION','legacy soul/knowledge exists: use oats okf migrate to preserve and stage it, then explicit cutover; no automatic loss');
+  if(!fs.existsSync(join(soul,'okf.json'))) fail('E_CONFIG',`soul has no okf.json: this soul reads/owns no knowledge yet. Provision it explicitly (oats okf init, or oats okf migrate for a legacy soul), or deactivate oats.okf for this soul; nothing was created`);
   return validateDeclaration(readJSON(join(soul,'okf.json')));
 }
 export function validateDeclaration(d) {

package/capabilities/oats-okf/lib/sources.mjs

@@ -246,6 +246,21 @@ export function input(source,id) {
   const value=readJSON(join(dirname(source.file),'inputs',`${id}.json`));
   if(hash(value)!==id) fail('E_INPUT','durable evidence hash mismatch');return value;
 }
+/** Switch a retired source's job off once nothing is pending. Idempotent; a
+ *  scheduler failure is recorded, never thrown — the evidence is already safe. */
+export function settleRetiredSchedule(source) {
+  const status=loadStatus(source);
+  if(status.schedule?.settled===true) return {status:'already-disabled',id:status.schedule.id};
+  if(!status.retired || status.auto || status.schedule?.id===undefined) return {status:'kept'};
+  try {
+    oats(['schedule','disable',status.schedule.id,'--dir',source.context,'--json'],source.context);
+    updateStatus(source,current=>{current.schedule={...current.schedule,settled:true,settledAt:new Date().toISOString()};});
+    return {status:'disabled',id:status.schedule.id};
+  } catch(e) {
+    updateStatus(source,current=>{current.schedule={...current.schedule,settled:false,settleError:e.message};});
+    return {status:'disable-failed',id:status.schedule.id};
+  }
+}
 export function capture(source,{final=false,deadlineMs=85000}={}) {
   return withLock(join(dirname(source.file),'capture.lock'),()=>{
     const status=loadStatus(source);
@@ -318,7 +333,15 @@ export function capture(source,{final=false,deadlineMs=85000}={}) {
       }
       status.lastCapture={status:report.status,complete:report.complete===true,ignored:report.ignored||0,at:new Date().toISOString()};
       if(report.complete!==true) fail('E_CAPTURE',`capture ${report.status || 'uncertified'}: retain source and retry`);
-      if(final) {status.retired=true;status.auto=status.auto && !noLaunch;status.retiredAt=new Date().toISOString();}
+      if(final) {
+        status.retired=true;status.retiredAt=new Date().toISOString();
+        // A retired source whose every captured input is already processed has
+        // no further work: its schedule is switched off now (never deleted —
+        // the job definition stays as evidence). Anything still pending keeps
+        // the job enabled until the worker drains it (see worker.mjs).
+        const drained=status.captured.inputs.every(id=>status.processed.includes(id));
+        status.auto=status.auto && !noLaunch && !drained;
+      }
       saveCapture(source,status);return {...status.lastCapture,inputs:status.captured.inputs.length};
     } catch(e) {
       status.lastCapture={status:'incomplete',complete:false,error:e.message,at:new Date().toISOString()}; saveCapture(source,status);throw e;
@@ -351,7 +374,9 @@ export function scheduleSource(source) {
       if(!sameJson(responsible,spec.responsibleHuman)) fail('E_SCHEDULE','captured source schedule responsible human differs');
       if(actual.execution && (actual.execution.deployment!==source.executionBinding.deployment || actual.execution.resolution?.id!==source.executionBinding.resolution.id)) fail('E_SCHEDULE','captured source schedule execution binding differs');
     }
-    updateStatus(source,status=>{status.schedule={id:spec.id,status:'ready',result};});return result;
+    // A job already settled off for a retired, drained source stays settled:
+    // registration re-verifies the definition but does not forget the switch-off.
+    updateStatus(source,status=>{const settled=status.schedule?.settled===true?{settled:true,settledAt:status.schedule.settledAt}:{};status.schedule={id:spec.id,status:'ready',result,...settled};});return result;
   } catch(e) {
     updateStatus(source,status=>{status.schedule={...(status.schedule || {}),id:spec.id,status:'failed',error:e.message};});throw e;
   }

package/capabilities/oats-okf/lib/worker.mjs

@@ -1,7 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { isAbsolute, resolve } from 'node:path';
 import { fs, join, dirname, safePath, readJSON, save, atomic, tree, materialize, digest, hash, withLock, oats, command, fail, relPath } from './io.mjs';
-import { loadSource, loadStatus, saveStatus, updateStatus, capture, input, markerPath, homeSource } from './sources.mjs';
+import { loadSource, loadStatus, saveStatus, updateStatus, capture, input, markerPath, homeSource, settleRetiredSchedule } from './sources.mjs';
 import {capturedSource,qualifyCapturedWorker,assertCapturedRun,capturedScaffold,retainCapturedWorkerCustody,assertCapturedWorkerHome,capturedStart} from './captured-worker.mjs';
 import { metadata, splitRef } from './config.mjs';
 import { stageBase, validateBase, allowedChanges, verifyGitScope, gitPublish, directoryPublish, journalPath, baseLock, recoveryStage, reconcileDirectoryIntent, gitRecoveryState } from './stores.mjs';
@@ -63,7 +63,10 @@ export function runSource(source,{noLaunch=false,manual=false,capturedInvocation
     const previous=status.pendingRejudgment?readRun(source,status.pendingRejudgment):null;
     if(previous) checkRecoveryGuards(source,previous);
     const ids=previous?previous.inputs:status.captured.inputs.filter(id=>!status.processed.includes(id));
-    if(!ids.length) return status.finalCaptureUncertified?{status:'source-unavailable',processedCapturedInput:true,finalCaptureComplete:false}:{status:'empty',processed:true};
+    if(!ids.length) {
+      if(status.retired && !status.finalCaptureUncertified) {updateStatus(source,current=>{current.auto=false;});settleRetiredSchedule(source);}
+      return status.finalCaptureUncertified?{status:'source-unavailable',processedCapturedInput:true,finalCaptureComplete:false}:{status:'empty',processed:true};
+    }
     const selected=[];let bytes=0;
     for(const id of ids) {const n=Buffer.byteLength(JSON.stringify(input(source,id)));if(selected.length && bytes+n>192000) break;selected.push(id);bytes+=n;}
     if(!source.decl.owns.length) fail('E_OWNER','source has evidence but owns no destination; retained for explicit ownership routing');

package/capabilities/oats-okf/oats.json

@@ -1,7 +1,7 @@
 {
   "capability": "oats.okf",
   "command": "okf",
-  "version": "2.1.2",
+  "version": "2.1.3",
   "compatibility": {
     "oats": ">=0.24.4"
   },
@@ -62,7 +62,16 @@
       "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"
+      "setting harvest-model must be null or a non-empty string",
+      "check action is not an admitted knowledge operation",
+      "bound runtime bindings file is missing or invalid",
+      "more than 64 git knowledge bases declared",
+      "declared knowledge base could not be staged from its git source",
+      "declared knowledge base is not a validated knowledge tree",
+      "knowledge base owner or remote custody requirement not met",
+      "staged git source does not match the declared knowledge base",
+      "harvest runtime command is not installed on this host",
+      "harvest runtime could not be qualified against the accepted bases"
     ]
   },
   "inject": "injects/okf.md",
@@ -76,13 +85,17 @@
       "command": "bin/oats-okf.mjs spawn",
       "required": true,
       "inputs": {
-        "sourceReceipt": { "version": 1 }
+        "sourceReceipt": {
+          "version": 1
+        }
       }
     },
     "retire": {
       "command": "bin/oats-okf.mjs retire",
       "inputs": {
-        "sourceReceipt": { "version": 1 }
+        "sourceReceipt": {
+          "version": 1
+        }
       }
     }
   },
@@ -99,8 +112,18 @@
       "context": "home",
       "description": "Capture this source into durable custody and request an independent worker.",
       "args": [
-        {"name": "native-request", "flag": "--native-request", "required": false, "description": "Captured operations require an explicit absolute backend-only native request JSON; provider owns the worker task."},
-        {"name": "worker-mode", "flag": "--worker-mode", "required": false, "description": "Captured worker mode: prepare or launch (default launch); legacy behavior is unchanged when absent."}
+        {
+          "name": "native-request",
+          "flag": "--native-request",
+          "required": false,
+          "description": "Captured operations require an explicit absolute backend-only native request JSON; provider owns the worker task."
+        },
+        {
+          "name": "worker-mode",
+          "flag": "--worker-mode",
+          "required": false,
+          "description": "Captured worker mode: prepare or launch (default launch); legacy behavior is unchanged when absent."
+        }
       ]
     }
   }

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-22 10:30Z (clock verified with `date -u`; the previous "22:20Z" stamp was a wall-clock error) · **Slice 2b MERGED** (PR65) · **K3 producer pins closed** (PR66 advertisement + guarded Remove; PR67 kernel-owned child stop, confirmed-branch binding, per-key stop replay, ambiguous parentage) · `oats session recompose` seam (in-place instruction refresh) · engineer wiring **2c** on `aed94b74` → 5 → 6b → 7b → 8 · lead: reviews; tag 0.24.8 when 2c lands
+**Last update:** 2026-09-22 17:30Z · main `1b8349e5` · Slice 5 ✅ (PR71) · security follow-up ✅ (PR73) · K5 pins ✅ (PR74/75) · **K6b ✅ (PR76: `spawnPreviewApi 2` / `spawn-preview-2` — side-effect-free preview, `--agents-root`, `--expect-decision`/`E_DECISION_STALE`, bounded preflight)** · **PR77 ✅ killGroup pid-0 guard (HIGH; engineer-found)** · OKF 2.1.3 ✅ · engineer → **6b READ wiring** (API 2 gate) → 6b apply companion (proposal) → 7b → 8 · open contracts: K11 admission, attach-knowledge (OKF node refs), auto-PR (P1 write approval), branch enumeration · **0.24.9** after 6b read (release-notes file FIRST)
 
 Legend: ✅ on main/published · 🔄 in flight (PR/branch) · 🟡 preserved, not adopted · ⬜ not started · ⛔ blocked
 

package/docs/desktop-cli-api.md

@@ -239,6 +239,40 @@ executable, runtime packages, child-spawn policy) and returns what the spawn
   knowledge provider (05 excluded, attach stays), auto-PR intent (ADE-owned,
   P1).
 
+### Preview API 2 (0.24.9+, feature `spawn-preview-2`) — the safe-mode fence
+
+**API 1 previews wrote before they returned** (a refused child spawn appended an
+event to the parent; a Herdr backend could be started; an unknown soul could be
+imported from an importable def). A consumer must therefore gate on
+**`spawnPreviewApi === 2` AND `features.includes("spawn-preview-2")`** — API 1 is
+the pre-fix marker and is never accepted for dispatch.
+
+- **No writes, success or refusal.** A preview appends no event, starts no
+  daemon (`backendStatus {name, installed, started:false}` reports what it
+  observed), and never creates/updates a soul (`E_SOUL_UNKNOWN` instead of an
+  import; `--instructions-file`/`--def-file` refused with `E_BAD_ARGS`). Test:
+  the deployment tree is byte-identical after a success, a refusal and an
+  unknown-soul preview.
+- **Exact root**: `spawn <soul> --agents-root <abs>` binds the soul to that root
+  (as inspect/readiness take it) — no team-soul / capability-agent / importable-
+  def fallback; mismatch → `E_SOUL_UNKNOWN`. The preview echoes
+  `subject {soul, agentsRoot|null, dir|null}` **as given, byte-exact**.
+- **Decision binding**: `decision {instance, home, branch, base{ref,oid},
+  revision}` (24-hex). Apply with `spawn … --expect-decision <revision>`: the
+  kernel recomputes name/home/branch/base under the same placement path and
+  refuses **`E_DECISION_STALE`** with `details.decision` (the fresh one) on ANY
+  drift — no auto-suffix, no silent re-base, nothing created. A GUI re-previews
+  and re-confirms; it never second-guesses names or paths. Without the flag the
+  CLI keeps its legacy auto-suffix for humans.
+- **Bounded preflight**: every native probe a preview runs (`pi --list-models`,
+  `pi list`, `claude plugin list`) shares ONE budget (20 s default), runs in its
+  own process group and is group-killed on timeout; `preflight {status:
+  complete|timeout, budgetMs, elapsedMs}` says which. A hanging runtime cannot
+  hang a preview.
+- Still absent (named follow-ups, not parity-done): attach-knowledge node refs
+  (provider contract), auto-PR (P1/ADE write approval), branch enumeration
+  (producer seam).
+
 ## Readiness quartet, signatures, enforced policy (`oats readiness`, `readinessApi: 1`, OATS 0.24.8+)
 
 `oats readiness [--soul <name>] [--home <abs>] [--verify-signatures] [--policy] [--dir <d>] --json`
@@ -298,6 +332,58 @@ instance's recorded (enforced) one; with only `--soul` it is the declaration
 (`enforced: false`). It is a lifecycle-authority claim, not an OS sandbox —
 the UI says so.
 
+### Slice-5 producer pins (0.24.9+; all additive — gate items on field presence)
+
+- **`configured` is EFFECTIVE activation.** `activation.enabled` is the resolved
+  verdict for the subject; a capability *declared* for the soul but disabled is
+  `fail` with reason `declared for soul <n> but disabled (…)`. Declaration is
+  never activation.
+- **Trust is not-applicable for data-only capabilities.** The inspect row now
+  carries `health.executableSurface` (manifest commands/hooks/launch env — what
+  `oats trust` approves). No surface → `trusted` item `not-applicable`, reason
+  `no executable surface`, whatever the lock records. This is why a fresh
+  `oats trust <package> --all-capabilities` "skipped" `oats.core` and readiness
+  still said fail before 0.24.9.
+- **Typed linkage on every item**: `capability {id, level, scope}` and
+  `origin {kind: requires|declares|default|inventory, target}`; plus
+  `summary.byCapability[] {capability, origin, required, checks{installed,
+  trusted, configured, enrolled}, ownReady, ready}` — the SAME items regrouped,
+  no second observation. `ownReady` is the capability's own four verdicts;
+  `ready` is `ownReady` AND no **subject-level blocker** — items that belong to
+  no capability (workspace membership, soul declarations) are listed in
+  `summary.subjectBlockers[] {check, subject, status}` and block every row.
+  A per-capability row never says ready while the subject is blocked, and a
+  row's verdict is never promoted to the subject's `summary.ready`. Render
+  per-capability rows from this; never parse subjects.
+- **Selector echo**: `subject.selector` = the arguments **as given, byte-exact,
+  no realpath** — `{kind:"scope", dir|null}` · `{kind:"soul", soul,
+  agentsRoot|null, dir|null}` · `{kind:"home", home, soul, agentsRoot|null}`.
+  Compare with what you sent, byte for byte; never filesystem-normalize a
+  response path. The canonical scope is `subject.context` (may differ from
+  `dir`, e.g. `/var` vs `/private/var` on macOS).
+- **Unreadable member document** (`oats.yaml` unreadable, or `workspace:`
+  present but not a mapping) → `enrolled` item `unknown` with
+  `evidence.file`, never `not-applicable`. A declared backlink stays `unknown`
+  with reason `reciprocal admission not observed …` until the CLI fetches the
+  workspace's members (K11).
+- **Captured homes refuse**: `readiness --home <captured>` →
+  `E_UNSUPPORTED_MODE` (`details.captured: true`) before any current-config
+  interpretation.
+- **`--agents-root <abs>`** is accepted with `--soul` (and with `--home`), as
+  inspect takes it — pin the exact root you admitted.
+- **Signature verification (feature `readiness-verify`)**: `--verify-signatures`
+  is bounded custody — **one total budget per readiness read** (120 s default)
+  shared by every capability's fetch and verify (an exhausted budget refuses the
+  remaining capabilities with `budget-exhausted`, no fetch), each Git child in
+  its own process group and the **whole group** SIGKILLed on timeout or failure,
+  scratch repositories removed on normal exit and on SIGINT/SIGTERM/SIGHUP, `GIT_CONFIG_GLOBAL
+  =/dev/null` + no system config + no prompts/askpass, **only https/ssh**
+  transports. `signature.failure` is `null` or `{code}` from the closed set
+  `transport-not-allowed | fetch-failed | fetch-timeout | budget-exhausted |
+  verifier-failed | verifier-timeout | cannot-check`; `signature.reason` is a
+  fixed sentence, **never stderr**. Gate the *Verify signatures…* action on the
+  feature name; keep it an explicit user action.
+
 ## Lifecycle plans — Stop and Remove (`lifecycleApi: 1`, OATS 0.24.8+)
 
 The Desktop's Stop and Remove confirmations render **plans**: a read-only

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

@@ -0,0 +1,67 @@
+# OATS v0.24.9 — readiness pins, side-effect-free spawn preview (API 2), process-group safety, Desktop Readiness view
+
+Kernel/Pi/Desktop **0.24.9**. Tag `v0.24.9` → the commit carrying these notes;
+the version-bump commit lands after the tag. Consumers gate on `oats version
+--json` `features[]` names and API integers — never on the version.
+
+## Kernel
+
+- **Spawn preview API 2** (feature `spawn-preview-2`, `spawnPreviewApi: 2`).
+  API 1 previews **wrote before they returned** — a refused child spawn appended
+  an event to the parent, a Herdr backend could be started, an unknown soul
+  could be imported from an importable def — and nothing bound a later spawn to
+  the previewed decision. API 2: a preview touches nothing, success or refusal
+  (proven by a byte-identical deployment tree); `spawn --agents-root <abs>`
+  binds the exact root with no fallback and the preview echoes `subject` as
+  given; `decision {instance, home, branch, base, revision}` + `spawn
+  --expect-decision <rev>` refuses **`E_DECISION_STALE`** with the fresh
+  decision on any drift (no auto-suffix, no silent re-base, nothing created);
+  every native probe shares one bounded preflight budget and is process-group
+  killed on timeout (`preflight {status, budgetMs, elapsedMs}`). **Gate on API
+  2 — API 1 is the pre-fix marker.**
+- **Readiness pins** (`oats readiness`): `configured` is *effective* activation
+  (a capability declared for the soul but disabled is a fail that says so);
+  data-only capabilities (skills/inject, no commands/hooks/env) report trust
+  **not-applicable** — the inspect row carries `health.executableSurface`;
+  every item is typed (`capability {id, level, scope}`, `origin {kind,
+  target}`) and `summary.byCapability[]` regroups the same items with
+  `ownReady` vs `ready` (never ready under a `summary.subjectBlockers[]` item
+  such as unknown membership); `subject.selector` echoes the arguments as given,
+  byte-exact; an unreadable member document is `unknown`, not not-applicable;
+  `readiness --home <captured>` refuses `E_UNSUPPORTED_MODE`; `--agents-root`
+  documented. **Signature verification** (feature `readiness-verify`) is
+  bounded custody: one budget per read, process-group kill, cleanup on
+  SIGINT/SIGTERM/SIGHUP, `GIT_CONFIG_GLOBAL=/dev/null`, https/ssh only, a closed
+  `signature.failure.code` — never stderr.
+- **Process-group safety (high).** Bounded-custody code killed a child's
+  process group on timeout with `process.kill(-child.pid)`; a **failed** spawn
+  (binary missing → `ENOENT`) reports `pid: 0`, and `kill(-0)` signals the
+  caller's own process group — `oats readiness --verify-signatures` without
+  `git` would have SIGKILLed the operator's shell/tmux/Desktop backend. One
+  guarded helper now refuses non-positive PIDs at every kill site.
+- **OKF 2.1.3** mirrored and pinned in the official catalog: per-cause `check`
+  reasons, a named remedy when a soul has no `okf.json` (was a raw ENOENT from
+  the required spawn hook), retired drained sources switch their `okf-<id>` job
+  off.
+
+## Desktop
+
+- **Readiness** (frame 09/04): Workspace header entry and first-run
+  invitation; the quartet from `oats readiness` with items, remedies (display
+  only), *View policy*, *Skip for now* (presentation only). Verify signatures
+  and Enrol are shown unavailable with the exact reason until their contracts
+  land. Effective-readiness section per scope on the Capabilities view.
+- **Normalized route classification**: one classifier decides every specialized
+  IPC route from the normalized pathname — dot-segment, percent-encoded,
+  backslash, tab and CRLF aliases can no longer skip a route's frame/epoch
+  guard.
+- Spawn modal: kernel **preview** (API 2) for the instance name, home, worktree,
+  branch and resolved base — *Suggest* asks the kernel for its default
+  candidate; preview-only choices block legacy submission rather than being
+  dropped. Apply companion, attach-knowledge, auto-PR and branch enumeration are
+  named follow-ups, not parity-done.
+
+## Upgrade
+
+`npm i -g @awebai/oats@0.24.9`, then `oats doctor`. Desktops on an older CLI
+show the new controls as unavailable until the CLI advertises them.

package/docs/workspace-adoption.md

@@ -107,7 +107,10 @@ onboarding and legacy roster/knowledge cutover remain separate.
   production store or grants are supplied. An acceptance fixture is parent-owned
   and cannot be counted as production knowledge adoption.
 - 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
+  messaging **oats.aweb@1.11.2** (both OATS >=0.24.4), not optional defaults.
+  The official catalog now offers **oats.okf 2.1.3** (per-cause `check` reasons,
+  a named remedy for a soul without `okf.json`, retired sources switch their
+  job off); editions move to it when their owner re-reviews them. 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.

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.2#oats-package
+    source: git:github.com/awebai/oats-okf@v2.1.3#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/core.mjs

@@ -26,7 +26,7 @@
  *   work (worktree|checkout|attached|workspace|directory), runtime (pi|claude|codex), model (pi model pattern, optional)
  *   (attached as soul default is for service agents — spawn must supply workDir)
  */
-import { execFileSync, execSync, spawn as spawnProcess } from "node:child_process";
+import { execFileSync, execSync, spawn as spawnProcess, spawnSync } from "node:child_process";
 import {
   chmodSync, closeSync, copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, symlinkSync, writeFileSync,
 } from "node:fs";
@@ -41,6 +41,7 @@ import { capturedPiSessionDirectory, requireCapturedPiRecordSupport, inspectCapt
 import { attachSessionTarget } from "./session-viewer.mjs";
 import { inspectSessionTarget, inputSessionTarget } from "./session-input.mjs";
 import { appendEvent } from "./instance-events.mjs";
+import { killGroup } from "./process-group.mjs";
 import { ensureHerdr, allocateHerdr, launchHerdr, inspectHerdr, stopHerdr, validHerdrTarget, herdrSnapshot, herdrCommand } from "./herdr.mjs";
 
 import { oatsError } from "./errors.mjs";
@@ -129,6 +130,30 @@ function legacyOperationalSkills(soulDir) {
 // ---------- shell helpers ----------
 function sh(cmdline) { return execSync(cmdline, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim(); }
 function shTry(cmdline) { try { return sh(cmdline); } catch { return undefined; } }
+/** A native PROBE (a runtime binary asked about its catalogue or packages) under
+ *  a preview: bounded by what is left of the shared preflight budget, run in its
+ *  own process group and group-killed on timeout. Cheap lookups (`command -v`)
+ *  are not probes and never draw from the budget. Outside a preview: shTry. */
+function probeTry(cmdline) {
+  if (!previewPreflightBudget) return shTry(cmdline);
+  const left = previewPreflightBudget.deadline - Date.now();
+  if (left <= 0) { previewPreflightBudget.exhausted = true; return undefined; }
+  const r = spawnSync("/bin/sh", ["-c", cmdline], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: left, killSignal: "SIGKILL", detached: true, env: { ...process.env, GIT_TERMINAL_PROMPT: "0", GIT_ASKPASS: "/bin/false" } });
+  if (r.error || r.signal) { killGroup(r); if (r.error?.code === "ETIMEDOUT" || r.signal === "SIGKILL") previewPreflightBudget.exhausted = true; return undefined; }
+  return r.status === 0 ? String(r.stdout).trim() : undefined;
+}
+let previewPreflightBudget = null;
+/** execFileSync for a native probe: under a preview budget, the timeout is what
+ *  is left of it and the child is group-killed; otherwise the caller's timeout. */
+function probeExecFile(file, args, options = {}) {
+  if (!previewPreflightBudget) return execFileSync(file, args, options);
+  const left = previewPreflightBudget.deadline - Date.now();
+  if (left <= 0) { previewPreflightBudget.exhausted = true; throw Object.assign(new Error("preflight budget exhausted"), { code: "E_PREFLIGHT_BUDGET" }); }
+  const r = spawnSync(file, args, { ...options, timeout: Math.min(left, options.timeout ?? left), killSignal: "SIGKILL", detached: true });
+  if (r.error || r.signal) { killGroup(r); if (r.error?.code === "ETIMEDOUT" || r.signal === "SIGKILL") previewPreflightBudget.exhausted = true; throw r.error || Object.assign(new Error("probe killed"), { code: "E_PREFLIGHT_BUDGET" }); }
+  if (r.status !== 0) throw Object.assign(new Error(`probe exited ${r.status}`), { status: r.status, stdout: r.stdout });
+  return r.stdout;
+}
 function shIn(cwd, cmdline, timeout = 45000) {
   return execSync(cmdline, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout }).trim();
 }
@@ -4327,7 +4352,7 @@ export const RUNTIME_PACKAGE_MANAGERS = {
       try {
         // The SELECTED executable answers (a wrapper or another binary), with
         // pi's own controlled list subcommand only: never a launch argument.
-        const out = execFileSync(opts.bin || "pi", ["list", "--no-approve"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], env, timeout: 30000 });
+        const out = probeExecFile(opts.bin || "pi", ["list", "--no-approve"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], env, timeout: 30000 });
         const rows = [];
         // pi dims the path with chalk; strip any escapes before matching.
         const lines = out.replace(/\u001b\[[0-9;]*m/g, "").split("\n");
@@ -4418,7 +4443,7 @@ export const RUNTIME_PACKAGE_MANAGERS = {
     list: (env = process.env, opts = {}) => {
       let out;
       try {
-        out = execFileSync(RUNTIME_PACKAGE_MANAGERS.claude.bin(opts), ["plugin", "list", "--json"],
+        out = probeExecFile(RUNTIME_PACKAGE_MANAGERS.claude.bin(opts), ["plugin", "list", "--json"],
           { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 60000, env });
       } catch { return []; }
       let rows;
@@ -5422,7 +5447,7 @@ export function resolveModelPreference(model, runtime = "pi") {
     const [provider, ...rest] = bare.split("/");
     const id = rest.join("/");
     if (!id) return pref; // bare pattern (no provider) — let pi resolve it
-    const out = shTry(`pi --list-models ${shq(id)} 2>/dev/null`) || "";
+    const out = probeTry(`pi --list-models ${shq(id)} 2>/dev/null`) || "";
     const found = out.split("\n").some((line) => {
       const cols = line.trim().split(/\s+/);
       return cols[0] === provider && cols[1] === id;
@@ -5865,7 +5890,14 @@ export function spawnInstance(root, agent, o = {}) {
   if (!repoAbs) throw new Error(`agent "${agent.name}" has no repo configured — pass one`);
   // Launch selection: a named configuration (explicit, or the soul's
   // launch-config default), or none; the runtime and model follow from it.
-  const launchSelection = resolveLaunchSelection({ launchConfigs: launchConfigsOf(configChain(repoAbs)), agent, selection: { launchConfig: o.launchConfig, runtime: o.runtime, model: o.model } });
+  // K6b: a preview's native probes (model catalogue, runtime packages) share
+  // ONE budget from here to the return; each probe is group-killed on timeout.
+  const preflightStarted = Date.now(), preflightBudgetMs = o.preview === true ? (Number(process.env.OATS_PREVIEW_PREFLIGHT_BUDGET_MS) || 20000) : undefined;
+  let preflight = { status: "complete", budgetMs: preflightBudgetMs ?? null };
+  if (o.preview === true) previewPreflightBudget = { deadline: preflightStarted + preflightBudgetMs };
+  let launchSelection;
+  try { launchSelection = resolveLaunchSelection({ launchConfigs: launchConfigsOf(configChain(repoAbs)), agent, selection: { launchConfig: o.launchConfig, runtime: o.runtime, model: o.model } }); }
+  catch (e) { previewPreflightBudget = null; throw e; }
   const launchConfig = launchSelection.config;
   const runtime = launchSelection.runtime;
   const model = launchSelection.model;
@@ -6100,7 +6132,9 @@ export function spawnInstance(root, agent, o = {}) {
     const parentMeta = parentHome && existsSync(join(parentHome, "instance.json")) ? JSON.parse(readFileSync(join(parentHome, "instance.json"), "utf8")) : anchorMeta;
     const policy = childPolicyOf(parentMeta);
     if (policy.allowed === false) {
-      if (parentHome) appendEvent(parentHome, { kind: "child-spawn-refused", data: { child: instance, agent: agent.name, policy } });
+      // A preview touches nothing — not even the parent's event log; the
+      // typed refusal IS the preview's answer.
+      if (parentHome && o.preview !== true) appendEvent(parentHome, { kind: "child-spawn-refused", data: { child: instance, agent: agent.name, policy } });
       throw Object.assign(oatsError("E_CHILD_SPAWNS_DISABLED", `${parentInstance} does not allow child spawns (policy origin: ${policy.origin?.kind ?? "recorded"}${policy.origin?.detail ? ` — ${policy.origin.detail}` : ""}); nothing was spawned. Spawn without a parent relation, or respawn the parent with --allow-child-spawns.`),
         { parent: parentInstance, policy });
     }
@@ -6220,8 +6254,11 @@ export function spawnInstance(root, agent, o = {}) {
   // spawn hooks run, which happens after the home exists.
   if ((launchConfig?.args || []).length && applicableRequirements(runtime, resolvedCfg.capabilities).length) throw oatsError("E_LAUNCH_PROBE_UNSUPPORTED", `${requirementsWithArgsMessage(runtime, resolvedCfg.capabilities, launchConfig)}; nothing was created`);
   const runtimePackages = verifyRuntimePackages(runtime, resolvedCfg, repoAbs, { ...(launchConfig?.executable ? { bin } : {}), env: launchEffectiveEnv({ base: process.env, configEnv: launchConfig?.env || {} }) });
-  if (launch && !which(backend)) throw new Error(`${backend} not installed${backend === "tmux" ? " (brew install tmux)" : " (https://herdr.dev)"}`);
-  const herdrBase = launch && backend === "herdr" ? ensureHerdr({ binary: which("herdr"), socket: o.herdrSocket }) : undefined;
+  if (launch && o.preview !== true && !which(backend)) throw new Error(`${backend} not installed${backend === "tmux" ? " (brew install tmux)" : " (https://herdr.dev)"}`);
+  // Preview never starts a backend daemon: it reports reachability as observed
+  // (binary present?) and leaves the socket alone.
+  const herdrBase = launch && backend === "herdr" && o.preview !== true ? ensureHerdr({ binary: which("herdr"), socket: o.herdrSocket }) : undefined;
+  if (o.preview === true) { preflight = { status: previewPreflightBudget?.exhausted ? "timeout" : "complete", budgetMs: preflightBudgetMs, elapsedMs: Date.now() - preflightStarted }; previewPreflightBudget = null; }
   const task = o.task ?? (o.taskFile ? readFileSync(o.taskFile, "utf8") : "");
 
   if (existsSync(directoryRollbackPath(homeReal))) throw oatsError("E_WORK_INSPECTION_FAILED", `directory cleanup is still owed for ${home}; restore and retire the retained home before reusing its name`);
@@ -6243,8 +6280,13 @@ export function spawnInstance(root, agent, o = {}) {
     plannedBase = { ref: baseRef, oid: baseOid };
   }
   if (o.preview === true) {
+    const decision = { instance, home, branch: plannedBranch, base: plannedBase };
+    decision.revision = createHash("sha256").update(canonicalJson(decision)).digest("hex").slice(0, 24);
     return {
-      spawnPreviewApi: 1, preview: true, agent: agent.name, kind: agent.kind || "persistent", instance, home, repo: repoAbs, work,
+      spawnPreviewApi: 2, preview: true, agent: agent.name, kind: agent.kind || "persistent", instance, home, repo: repoAbs, work,
+      subject: o.subject ?? { soul: agent.name, agentsRoot: root, context: null },
+      decision, preflight,
+      backendStatus: launch ? { name: backend, installed: !!which(backend), started: false } : null,
       runtime, model: model || null, modelSource: launchSelection.modelSource ?? null, launchConfig: launchConfig?.name ?? null, yolo, backend,
       branch: plannedBranch, base: plannedBase, worktree: work === "worktree" ? join(home, "work") : null,
       relation: relation || null, parentInstance: parentInstance && parentInstance !== instance ? parentInstance : null,
@@ -6252,6 +6294,15 @@ export function spawnInstance(root, agent, o = {}) {
       skills: expectedResources.filter((r) => r.type === "skill-tree").flatMap((r) => r.entries || []), task: task || null,
     };
   }
+  if (o.expectDecision !== undefined) {
+    // A confirmed preview binds THIS apply: same name, home, branch and base
+    // oid, recomputed here under the same placement path. Any drift is a typed
+    // refusal carrying the fresh decision — nothing is created, nothing is
+    // auto-suffixed or silently re-based.
+    const fresh = { instance, home, branch: plannedBranch, base: plannedBase };
+    fresh.revision = createHash("sha256").update(canonicalJson(fresh)).digest("hex").slice(0, 24);
+    if (fresh.revision !== o.expectDecision) throw Object.assign(oatsError("E_DECISION_STALE", `the previewed decision changed (${o.expectDecision} → ${fresh.revision}): ${fresh.instance}${plannedBase ? ` from ${plannedBase.ref}@${plannedBase.oid.slice(0, 12)}` : ""}; preview again`), { decision: fresh });
+  }
   mkdirSync(home, { recursive: true });
   // TOCTOU: the placement checks above ran BEFORE composition and the runtime
   // package preflight, both of which shell out — a window in which anything able

package/lib/process-group.mjs

@@ -0,0 +1,12 @@
+/** Kill a detached child's whole process group (e.g. git + its remote helper /
+ *  ssh, or a runtime probe + what it forked). ONLY for a child that was actually
+ *  spawned: a failed spawn (ENOENT) reports `pid: 0`, and `process.kill(-0)` /
+ *  `process.kill(0)` address the CALLER's own process group — the operator's
+ *  shell, tmux session or Desktop backend. Returns whether anything was signalled. */
+export function killGroup(child, signal = "SIGKILL") {
+  const pid = child?.pid;
+  if (!Number.isSafeInteger(pid) || pid <= 0) return false;
+  try { process.kill(-pid, signal); } catch { /* already gone */ }
+  try { process.kill(pid, signal); } catch { /* already gone */ }
+  return true;
+}

package/lib/readiness.mjs

@@ -7,7 +7,8 @@
  * executable approval, activation, runtime-package requirements, soul
  * declarations) — never a second opinion. Unknown is unknown; "Ready" is the
  * consumer's word and only when every required check passes. */
-import { execFileSync } from "node:child_process";
+import { spawnSync } from "node:child_process";
+import { killGroup } from "./process-group.mjs";
 import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -29,26 +30,67 @@ const item = (subject, status, { required = true, reason = null, producer = "ker
 /** Verified Git signature of a source commit, named signer or nothing.
  *  Requires network (fetch) — only when the caller asks (`verify: true`);
  *  otherwise `unknown` with the reason. Never a URL, owner or hash as signer. */
-export function signatureOf({ url, commit }, { verify = false, timeoutMs = 30000 } = {}) {
-  if (!url || !commit || commit === "local") return { status: "not-applicable", signer: null, reason: commit === "local" ? "path-installed capability has no source commit" : "no source recorded" };
-  if (!verify) return { status: "unknown", signer: null, reason: "signature verification needs a network fetch; pass --verify-signatures" };
-  const dir = mkdtempSync(join(tmpdir(), "oats-sig-"));
-  const env = { PATH: process.env.PATH ?? "", HOME: process.env.HOME ?? "", GIT_TERMINAL_PROMPT: "0", GIT_CONFIG_NOSYSTEM: "1", LC_ALL: "C" };
-  const git = (args) => execFileSync("git", ["-C", dir, "-c", "core.fsmonitor=false", "-c", "core.hooksPath=/dev/null", ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: timeoutMs, env, shell: false });
+export const SIGNATURE_FAILURES = Object.freeze(["transport-not-allowed", "fetch-failed", "fetch-timeout", "budget-exhausted", "verifier-failed", "verifier-timeout", "cannot-check", "no-source"]);
+const ALLOWED_TRANSPORTS = /^(https:\/\/|ssh:\/\/|git@[^/:]+:)/;
+/** Verified Git signature of a source commit, named signer or nothing.
+ *  Requires network (fetch) — only when the caller asks (`verify: true`);
+ *  otherwise `unknown` with the reason. Never a URL, owner or hash as signer.
+ *  Bounded custody: one total budget per call (`budgetMs`, default 60s) shared
+ *  by fetch and verify; each Git child runs in its own process group and is
+ *  killed with the group on timeout; the scratch repository is removed on every
+ *  exit including signals; Git reads NO global/system config and cannot prompt;
+ *  only https/ssh transports are fetched. Failures carry a closed `failure`
+ *  code — never stderr. */
+/** One verification budget for a whole readiness read: every signatureOf call
+ *  in that read draws from it, so a target with N capabilities is bounded by the
+ *  TOTAL (default 120 s), not N × per-call. */
+export function verificationBudget(totalMs = 120000) {
+  const started = Date.now();
+  return { totalMs, remaining: () => totalMs - (Date.now() - started) };
+}
+const scratchDirs = new Set();
+let signalCleanupInstalled = false;
+function installSignalCleanup() {
+  if (signalCleanupInstalled) return; signalCleanupInstalled = true;
+  const sweep = () => { for (const d of scratchDirs) { try { rmSync(d, { recursive: true, force: true }); } catch { /* best effort */ } } scratchDirs.clear(); };
+  process.once("exit", sweep);
+  for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) process.once(sig, () => { sweep(); process.exit(128 + (sig === "SIGINT" ? 2 : sig === "SIGTERM" ? 15 : 1)); });
+}
+export function signatureOf({ url, commit }, { verify = false, budgetMs = 60000, budget = null } = {}) {
+  if (!url || !commit || commit === "local") return { status: "not-applicable", signer: null, reason: commit === "local" ? "path-installed capability has no source commit" : "no source recorded", failure: null };
+  if (!verify) return { status: "unknown", signer: null, reason: "signature verification needs a network fetch; pass --verify-signatures", failure: null };
+  if (!ALLOWED_TRANSPORTS.test(url)) return { status: "unknown", signer: null, reason: "source transport is not https or ssh; not fetched", failure: { code: "transport-not-allowed" } };
+  const shared = budget ?? verificationBudget(budgetMs);
+  if (shared.remaining() <= 0) return { status: "unknown", signer: null, reason: "the verification budget was exhausted", failure: { code: "budget-exhausted" } };
+  installSignalCleanup();
+  const dir = mkdtempSync(join(tmpdir(), "oats-sig-")); scratchDirs.add(dir);
+  const cleanup = () => { scratchDirs.delete(dir); try { rmSync(dir, { recursive: true, force: true }); } catch { /* best effort */ } };
+  const env = { PATH: process.env.PATH ?? "", HOME: dir, GIT_TERMINAL_PROMPT: "0", GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: "/dev/null", GIT_ASKPASS: "/bin/false", SSH_ASKPASS: "/bin/false", GIT_SSH_COMMAND: "ssh -o BatchMode=yes", LC_ALL: "C" };
+  const git = (args, stage) => {
+    const left = shared.remaining();
+    if (left <= 0) throw Object.assign(new Error("budget"), { failure: "budget-exhausted" });
+    const child = spawnSync("git", ["-C", dir, "-c", "core.fsmonitor=false", "-c", "core.hooksPath=/dev/null", "-c", "protocol.allow=never", "-c", "protocol.https.allow=always", "-c", "protocol.ssh.allow=always", ...args],
+      { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: left, killSignal: "SIGKILL", detached: true, env, shell: false });
+    if (child.error?.code === "ETIMEDOUT" || child.signal === "SIGKILL") { killGroup(child); throw Object.assign(new Error(stage), { failure: `${stage}-timeout` }); }
+    if (child.error || child.status !== 0) { killGroup(child); throw Object.assign(new Error(stage), { failure: `${stage}-failed` }); }
+    return child.stdout;
+  };
   try {
-    git(["init", "-q"]);
-    try { git(["fetch", "-q", "--depth", "1", url, commit]); }
-    catch (e) { return { status: "unknown", signer: null, reason: `fetch failed: ${String(e.stderr ?? e.message ?? "").trim().slice(0, 200) || "unknown"}` }; }
+    git(["init", "-q"], "verifier");
+    git(["fetch", "-q", "--depth", "1", url, commit], "fetch");
     // %G? : G good, B bad, U good-untrusted, X expired, Y expired key, R revoked, E cannot check, N none
-    const out = git(["log", "-1", "--format=%G?%x00%GS%x00%GK%x00%GF", commit]).trim();
+    const out = git(["log", "-1", "--format=%G?%x00%GS%x00%GK%x00%GF", commit], "verifier").trim();
     const [code, signerName, keyId, fingerprint] = out.split("\0");
-    if (code === "N") return { status: "unsigned", signer: null, reason: "commit carries no signature" };
-    if (code === "G") return { status: "verified", signer: { id: fingerprint || keyId || null, label: signerName || null }, reason: null };
-    if (code === "U") return { status: "verified", signer: { id: fingerprint || keyId || null, label: signerName || null }, reason: "good signature from a key not marked trusted in the local keyring", trust: "untrusted-key" };
-    if (code === "E") return { status: "unknown", signer: null, reason: "signature present but cannot be checked (missing public key)" };
-    return { status: "invalid", signer: null, reason: { B: "bad signature", X: "good signature that has expired", Y: "good signature made by an expired key", R: "good signature made by a revoked key" }[code] || `git reported ${code || "nothing"}` };
-  } catch (e) { return { status: "unknown", signer: null, reason: String(e.stderr ?? e.message ?? "").trim().slice(0, 200) || "verification failed" }; }
-  finally { rmSync(dir, { recursive: true, force: true }); }
+    if (code === "N") return { status: "unsigned", signer: null, reason: "commit carries no signature", failure: null };
+    if (code === "G") return { status: "verified", signer: { id: fingerprint || keyId || null, label: signerName || null }, reason: null, failure: null };
+    if (code === "U") return { status: "verified", signer: { id: fingerprint || keyId || null, label: signerName || null }, reason: "good signature from a key not marked trusted in the local keyring", trust: "untrusted-key", failure: null };
+    if (code === "E") return { status: "unknown", signer: null, reason: "signature present but cannot be checked (missing public key)", failure: { code: "cannot-check" } };
+    return { status: "invalid", signer: null, reason: { B: "bad signature", X: "good signature that has expired", Y: "good signature made by an expired key", R: "good signature made by a revoked key" }[code] || "verifier reported an unrecognised state", failure: null };
+  } catch (e) {
+    const code = SIGNATURE_FAILURES.includes(e.failure) ? e.failure : "verifier-failed";
+    const reasons = { "fetch-failed": "the source could not be fetched", "fetch-timeout": "the fetch exceeded the verification budget", "budget-exhausted": "the verification budget was exhausted", "verifier-failed": "the local verifier failed", "verifier-timeout": "the local verifier exceeded the verification budget" };
+    return { status: "unknown", signer: null, reason: reasons[code], failure: { code } };
+  } finally { cleanup(); }
 }
 
 function sourceOfCapability(cap, catalog) {
@@ -61,37 +103,58 @@ function sourceOfCapability(cap, catalog) {
 }
 
 /** The quartet for a scope or one soul, from an inspect result. */
-export function readinessOf(inspect, { soul = null, verifySignatures = false, catalog = null, deploymentDir = null, memberDocument = null } = {}) {
+export function readinessOf(inspect, { soul = null, verifySignatures = false, catalog = null, deploymentDir = null, memberDocument = null, selector = null, verificationBudgetMs = 120000 } = {}) {
   const caps = inspect.capabilities || [];
+  const budget = verifySignatures ? verificationBudget(verificationBudgetMs) : null;
   const soulEntry = soul ? (inspect.souls || []).find((s) => s.name === soul) : null;
-  const required = new Set(soulEntry?.declarations?.requires?.capabilities ? Object.keys(soulEntry.declarations.requires.capabilities) : caps.filter((c) => c.activation?.enabled).map((c) => c.id));
-  const relevant = soul ? caps.filter((c) => required.has(c.id) || c.activation?.declaredAt?.some((d) => (d.targets || []).includes(`soul:${soul}`))) : caps;
+  const declaredRequires = soulEntry?.declarations?.requires?.capabilities ? Object.keys(soulEntry.declarations.requires.capabilities) : null;
+  const required = new Set(declaredRequires ?? caps.filter((c) => c.activation?.enabled).map((c) => c.id));
+  const declaredForSoul = (c) => !!c.activation?.declaredAt?.some((d) => (d.targets || []).includes(`soul:${soul}`));
+  const relevant = soul ? caps.filter((c) => required.has(c.id) || declaredForSoul(c)) : caps;
+  // Typed linkage for consumers (frame-level per-capability rows): WHICH
+  // capability, at which config level/scope, and WHY it is in this quartet.
+  const capabilityOf = (c) => ({ id: c.id, level: c.activation?.level ?? null, scope: c.activation?.target ?? null });
+  const originOf = (c) => declaredRequires?.includes(c.id) ? { kind: "requires", target: `soul:${soul}` }
+    : soul && declaredForSoul(c) ? { kind: "declares", target: `soul:${soul}` }
+    : c.activation?.enabled ? { kind: "default", target: c.activation?.target ?? "global" } : { kind: "inventory", target: null };
+  const typed = (c) => ({ capability: capabilityOf(c), origin: originOf(c) });
 
   // installed — the artifact's bytes are present and locked with matching integrity
   const installed = relevant.map((c) => {
     const ok = c.health?.installed === true && (c.health.integrity == null || c.health.installedIntegrity == null || c.health.integrity === c.health.installedIntegrity);
     return item(c.id, ok ? "pass" : c.health?.installed === false ? "fail" : "unknown", { required: required.has(c.id), producer: "oats list",
       reason: ok ? null : c.health?.installed === false ? "not acquired" : c.health?.code || "integrity drift", evidence: { version: c.version ?? null, integrity: c.health?.integrity ?? null, origin: c.origin ?? null },
-      remedy: ok ? null : `oats install ${c.package || c.id}` });
+      remedy: ok ? null : `oats install ${c.package || c.id}`, ...typed(c) });
   });
-  for (const id of required) if (!caps.some((c) => c.id === id)) installed.push(item(id, "fail", { producer: "soul declaration", reason: "declared by the soul but not in the inventory", remedy: `oats install <package providing ${id}>` }));
+  for (const id of required) if (!caps.some((c) => c.id === id)) installed.push(item(id, "fail", { producer: "soul declaration", reason: "declared by the soul but not in the inventory", remedy: `oats install <package providing ${id}>`,
+    capability: { id, level: null, scope: null }, origin: { kind: "requires", target: `soul:${soul}` } }));
 
   // trusted — executable approval of the exact artifact; signature separately
   const trusted = relevant.map((c) => {
-    const executable = !!(c.operations?.length || c.health?.code === "untrusted-surface" || c.health?.trusted !== undefined);
+    // The inspect row states whether the manifest has anything trust approves
+    // (commands/hooks/launch env). No surface → trust is not-applicable, however
+    // the lock records it. Older rows without the flag fall back to the old heuristic.
+    const executable = typeof c.health?.executableSurface === "boolean" ? c.health.executableSurface
+      : !!(c.operations?.length || c.health?.code === "untrusted-surface");
     const approved = c.health?.trusted === true;
-    const sig = signatureOf(sourceOfCapability(c, catalog), { verify: verifySignatures });
+    const sig = signatureOf(sourceOfCapability(c, catalog), { verify: verifySignatures, budget });
     return item(c.id, !executable ? "not-applicable" : approved ? "pass" : c.health?.trusted === false ? "fail" : "unknown", { required: required.has(c.id), producer: "artifact approval",
       reason: !executable ? "no executable surface" : approved ? null : "executable surface not approved", evidence: { integrity: c.health?.integrity ?? null }, remedy: approved || !executable ? null : `oats trust ${c.id}`,
-      signature: sig });
+      signature: sig, ...typed(c) });
   });
 
-  // configured — activation for the subject + runtime package requirements + layer readiness problems
+  // configured — EFFECTIVE activation for the subject (a declaration at the
+  // soul is not activation: `enabled` is the resolved verdict for this subject,
+  // and a declared-but-disabled binding is a fail that says so) + runtime
+  // package requirements + layer readiness problems
   const configured = [];
   for (const c of relevant) {
-    const active = soul ? (c.activation?.enabled === true || c.activation?.declaredAt?.some((d) => (d.targets || []).includes(`soul:${soul}`))) : c.activation?.enabled === true;
-    if (required.has(c.id)) configured.push(item(`${c.id} activation`, active ? "pass" : "fail", { producer: "oats-config.yaml", reason: active ? null : `not active for ${soul ? `soul ${soul}` : "this scope"}`, evidence: { target: c.activation?.target ?? null, level: c.activation?.level ?? null }, remedy: active ? null : `oats use ${c.id}${soul ? ` --soul ${soul}` : ""}` }));
-    for (const miss of c.missingRequires || []) configured.push(item(`${c.id} requires ${miss.command}`, "fail", { producer: "capability manifest", reason: miss.why || "required command not on PATH", remedy: miss.install || null }));
+    const active = c.activation?.enabled === true;
+    const declaredOnly = !active && soul && declaredForSoul(c);
+    if (required.has(c.id)) configured.push(item(`${c.id} activation`, active ? "pass" : "fail", { producer: "oats-config.yaml",
+      reason: active ? null : declaredOnly ? `declared for soul ${soul} but disabled${c.activation?.reason ? ` (${c.activation.reason})` : ""}` : `not active for ${soul ? `soul ${soul}` : "this scope"}`,
+      evidence: { target: c.activation?.target ?? null, level: c.activation?.level ?? null, source: c.activation?.source ?? null }, remedy: active ? null : `oats use ${c.id}${soul ? ` --soul ${soul}` : ""}`, ...typed(c) }));
+    for (const miss of c.missingRequires || []) configured.push(item(`${c.id} requires ${miss.command}`, "fail", { producer: "capability manifest", reason: miss.why || "required command not on PATH", remedy: miss.install || null, ...typed(c) }));
   }
   for (const p of inspect.problems || []) if (/runtime package|DISABLED|extension/i.test(p.message || "")) configured.push(item(p.capability || p.code, "fail", { producer: "runtime settings", reason: p.message, remedy: null }));
   if (soulEntry && soulEntry.readiness?.status === "undeclared") configured.push(item(`${soul} declarations`, "not-applicable", { required: false, producer: "soul.yaml", reason: "no requirements declared" }));
@@ -101,16 +164,32 @@ export function readinessOf(inspect, { soul = null, verifySignatures = false, ca
   const enrolled = [];
   const member = memberDocument ?? readMemberDocument(deploymentDir);
   if (!member) enrolled.push(item("workspace membership", "not-applicable", { required: false, producer: "oats.yaml", reason: "standalone deployment: no workspace declared in oats.yaml" }));
+  else if (member.unreadable) enrolled.push(item("workspace membership", "unknown", { producer: "oats.yaml", reason: "workspace member document is unreadable; membership cannot be stated", evidence: { file: member.file ?? null }, remedy: "repair oats.yaml (valid YAML) and re-run" }));
   else if (!member.workspace?.source) enrolled.push(item("workspace membership", "not-applicable", { required: false, producer: "oats.yaml", reason: "oats.yaml declares exports but no workspace backlink" }));
   else enrolled.push(item(`member of ${member.workspace.source}`, member.admitted === true ? "pass" : member.admitted === false ? "fail" : "unknown", { producer: "workspace discovery",
-    reason: member.admitted === true ? null : member.admitted === false ? "this repository is not admitted in the workspace's members" : "admission not verified (needs the workspace observation)",
+    reason: member.admitted === true ? null : member.admitted === false ? "this repository is not admitted in the workspace's members" : "reciprocal admission not observed: this CLI reads the backlink but does not yet fetch the workspace's members (declared, not verified)",
     evidence: { workspace: member.workspace.source, revision: member.workspace.revision ?? null }, remedy: member.admitted === true ? null : "ask the workspace maintainer to admit this repository (oats-workspace.yaml members) — enrolment is admission, not login" }));
 
   const checks = { installed: { status: roll(installed), items: installed }, trusted: { status: roll(trusted), items: trusted }, configured: { status: roll(configured), items: configured }, enrolled: { status: roll(enrolled), items: enrolled } };
   const requiredStatuses = Object.values(checks).flatMap((c) => c.items.filter((i) => i.required).map((i) => i.status));
-  return { readinessApi: READINESS_API, subject: soul ? { kind: "soul", name: soul } : { kind: "scope", context: inspect.scope?.context ?? null }, at: new Date().toISOString(),
+  // Per-capability grouping of the same items (no second observation): each
+  // capability's four verdicts, ready only if all its REQUIRED items pass.
+  const byCapability = [...new Set(Object.values(checks).flatMap((c) => c.items.map((i) => i.capability?.id).filter(Boolean)))].sort().map((id) => {
+    const of = (name) => checks[name].items.filter((i) => i.capability?.id === id);
+    const statuses = Object.keys(checks).flatMap((name) => of(name).filter((i) => i.required).map((i) => i.status));
+    const any = Object.keys(checks).flatMap((name) => of(name)).find(Boolean);
+    return { capability: any?.capability ?? { id, level: null, scope: null }, origin: any?.origin ?? null, required: statuses.length > 0,
+      checks: Object.fromEntries(Object.keys(checks).map((name) => [name, of(name).length ? roll(of(name)) : "not-applicable"])),
+      ownReady: statuses.length > 0 && statuses.every((s) => s === "pass" || s === "not-applicable") };
+  });
+  // Items that belong to no capability (workspace membership, soul declarations)
+  // are SUBJECT-level: a capability's own verdict never overrides them, and a
+  // row must not read "ready" while the subject is blocked by one of them.
+  const subjectBlockers = Object.entries(checks).flatMap(([name, c]) => c.items.filter((i) => i.required && !i.capability && i.status !== "pass" && i.status !== "not-applicable").map((i) => ({ check: name, subject: i.subject, status: i.status })));
+  for (const g of byCapability) g.ready = g.ownReady && subjectBlockers.length === 0;
+  return { readinessApi: READINESS_API, subject: { ...(soul ? { kind: "soul", name: soul } : { kind: "scope", context: inspect.scope?.context ?? null }), ...(selector ? { selector } : {}) }, at: new Date().toISOString(),
     checks, summary: { ready: requiredStatuses.length > 0 && requiredStatuses.every((s) => s === "pass" || s === "not-applicable"), required: requiredStatuses.length,
-      pass: requiredStatuses.filter((s) => s === "pass").length, fail: requiredStatuses.filter((s) => s === "fail").length, unknown: requiredStatuses.filter((s) => s === "unknown").length },
+      pass: requiredStatuses.filter((s) => s === "pass").length, fail: requiredStatuses.filter((s) => s === "fail").length, unknown: requiredStatuses.filter((s) => s === "unknown").length, byCapability, subjectBlockers },
     notes: [
       ...(verifySignatures ? [] : ["signatures are unknown until --verify-signatures (network fetch)"]),
       "ready means every REQUIRED check passes; it is never inferred from an empty set",
@@ -122,8 +201,13 @@ function readMemberDocument(deploymentDir) {
   if (!deploymentDir) return null;
   const file = join(deploymentDir, "oats.yaml");
   if (!existsSync(file)) return null;
-  try { const doc = parseYamlNested(readFileSync(file, "utf8")); return { workspace: doc.workspace && typeof doc.workspace === "object" ? doc.workspace : null, admitted: null, exports: doc.exports ?? null }; }
-  catch { return { workspace: null, admitted: null, unreadable: true }; }
+  try {
+    const doc = parseYamlNested(readFileSync(file, "utf8"));
+    // The lenient parser never throws: a `workspace:` that is present but not a
+    // mapping is a document we cannot read a membership from — unreadable, not absent.
+    if (doc.workspace !== undefined && (doc.workspace === null || typeof doc.workspace !== "object")) return { workspace: null, admitted: null, unreadable: true, file };
+    return { workspace: doc.workspace && typeof doc.workspace === "object" ? doc.workspace : null, admitted: null, exports: doc.exports ?? null };
+  } catch { return { workspace: null, admitted: null, unreadable: true, file }; }
 }
 
 /** Enforced policy for an instance (from its recorded metadata) or a soul

package/package-catalog.json

@@ -3,7 +3,7 @@
   "packages": {
     "oats.okf": {
       "url": "https://github.com/awebai/oats-okf.git",
-      "ref": "v2.1.2",
+      "ref": "v2.1.3",
       "path": "oats-package"
     },
     "oats.aweb": {

package/package.json

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