@awebai/oats 0.24.8 → 0.24.10

package/bin/oats.mjs

@@ -30,7 +30,7 @@ import {
   approveCapability, approveAvailableCapability, updatePackage, removePackage, migrateLegacyLock, applyLegacyLockMigration,
   packageIntegrity, capabilityArtifactIntegrity, verifyCapabilityInstallation, installedCapabilityDir, installedCapabilitiesDir, ownedCapabilitiesDir, loadPackageManifestAt,
   resolveOatsConfig, resolveWorkMode, composeInstanceAgentsMd, planInstanceResources, parseYamlNested, assertSafeConfigValue, assertSafeConfigWriteKey, stripInternalAnnotations, withConfigFile, packagedInject, teamAgentRoots,
-  findTeamAgent, findTeamInstance, findCapabilityAgent, findInstanceHome, findInstanceHomes, listCapabilityAgents, workspaceOf, stopInstanceSession, recomposeInstanceInstructions,
+  findTeamAgent, findTeamInstance, findCapabilityAgent, findInstanceHome, findInstanceHomes, listCapabilityAgents, workspaceOf, stopInstanceSession, recomposeInstanceInstructions, refreshRetirementBaselineHome,
   ensureRoot, findRoot, findAgent, listAgents, listInstances, listAgentDefs, createAgent as coreCreateAgent,
   spawnInstance, retireInstance, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, upsertLocalAgent, defaultRepo, RELATIONS, validateLaunchConfig, resolveLaunchSelection, resolveLaunchExecutable, checkLaunchExecutable, missingLaunchEnvRefs, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, LAUNCH_RUNTIMES, LAUNCH_RECIPE_VERSION, parseLaunchCommand, resolveYolo, planLaunch, redactLaunchCommand, restartInstanceSession,
 } from "../lib/core.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,12 @@ 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")) } : {}),
+      // K6c: with --idempotency-key, a retry of the SAME confirmed decision replays the recorded home instead of spawning twice.
+      ...(flag("idempotency-key") !== undefined && flag("idempotency-key") !== true ? { idempotencyKey: String(flag("idempotency-key")) } : {}),
     });
     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,14 +4342,26 @@ 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; }
+    if (e?.code === "E_IDEMPOTENCY_CONFLICT") { bail(e.code, e.message, { instance: e.instance, home: e.home }); throw e; }
+    if (e?.code === "E_PLACEMENT_TAKEN") { bail(e.code, e.message, { instance: e.instance, home: e.home }); throw e; }
+    if (e?.code === "E_SPAWN_INCOMPLETE") { bail(e.code, e.message, { instance: e.instance, home: e.home, launched: e.launched }); 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
   // the full receipt, never hidden, and never causes a second spawn.
   let wakeSchedule, wakeScheduleError;
-  if (wake) {
+  if (wake && r.replayed !== true) { // a replayed receipt re-saves nothing
     try { wakeSchedule = saveWakeForHome(scheduleScopeOf(workspaceOf(root)), { instance: r.instance, home: r.home, wake }); }
     catch (e) { wakeScheduleError = { code: e.code || "E_SCHEDULE_FAILED", message: e.message }; r.warnings = [...(r.warnings || []), `wake schedule NOT saved: ${e.message}`]; }
+    // K6e: record the wake outcome in the home so a same-key replay can report
+    // it instead of leaving "saved or not?" to inference.
+    if (r.spawnIdempotencyKey) {
+      try { const f = join(r.home, "instance.json"); const m = JSON.parse(readFileSync(f, "utf8")); m.wake = { requested: true, saved: !wakeScheduleError, error: wakeScheduleError ?? null }; writeFileSync(f, JSON.stringify(m, null, 2) + "\n"); r.wake = m.wake; refreshRetirementBaselineHome(r.home); } catch { /* the receipt still says it */ }
+    }
+  } else if (r.spawnIdempotencyKey && r.replayed !== true) {
+    try { const f = join(r.home, "instance.json"); const m = JSON.parse(readFileSync(f, "utf8")); m.wake = { requested: false, saved: null, error: null }; writeFileSync(f, JSON.stringify(m, null, 2) + "\n"); r.wake = m.wake; refreshRetirementBaselineHome(r.home); } catch { /* nothing to record */ }
   }
   if (JSON_MODE) {
     // Desktop CLI API v1 spawn result — a FIXED shape (see docs/desktop-cli-api.md).
@@ -4325,6 +4375,9 @@ function spawnCmd() {
       spawnOrigin: r.spawnOrigin, attach: r.attach,
       ...(r.sessionTarget ? { sessionTarget: r.sessionTarget } : {}),
       ...(r.yolo !== undefined ? { yolo: r.yolo } : {}),
+      // K6b/K6c: what bound this spawn, and whether this receipt is a replay of an earlier one.
+      ...(r.decision ? { decision: r.decision } : {}), ...(r.replayed !== undefined ? { replayed: r.replayed } : {}),
+      ...(r.wake !== undefined ? { wake: r.wake } : {}), // {requested, saved|null, error}: saved:null = outcome not recorded
       launchConfig: r.launch?.launchConfig ?? null, launch: r.launch || null, // already redacted by the kernel
     });
     return;
@@ -4980,7 +5033,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", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2"], instanceGitApi: 1, spawnApplyApi: 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 +5692,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 19:10Z · **v0.24.9 PUBLISHED** (tag `04a4f709`; both packages on npm, tarball shasum `6333c01c`; bump PR79 → main `a5cc390e`; artifact probe: readiness/preview API 2/bound apply/E_DECISION_STALE/retire retention/no-git verify all pass, caller alive, soul intact) · **6b READ MERGED** (PR78) · K6b ✅ · PR77 ✅ · engineer → **6b APPLY companion proposal** → 7b → 8 · open contracts: K11, attach-knowledge, auto-PR, branch enumeration
 
 Legend: ✅ on main/published · 🔄 in flight (PR/branch) · 🟡 preserved, not adopted · ⬜ not started · ⛔ blocked
 

package/docs/desktop-cli-api.md

@@ -239,6 +239,92 @@ 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.
+- **Confirmed apply contract** (0.24.10+, feature `spawn-apply-2`,
+  `spawnApplyApi: 1`) — what a GUI may promise at "Confirm spawn":
+  - `decision` gains **`effective {repo, work, runtime, model, launchConfig,
+    yolo, backend, childSpawns, relation{kind, anchor{instance, agentsRoot}}}`**
+    and `revision` hashes placement + effective. An inherited default that would
+    change what launches (the soul's model edited between preview and apply,
+    say) → `E_DECISION_STALE`. A GUI does not re-resolve anything itself.
+  - **No effect before the fence**: backend presence and `ensureHerdr` run only
+    AFTER a successful `--expect-decision` binding and after the placement
+    reservation. A stale apply with `--backend herdr` starts nothing. (The
+    parent-policy refusal still appends `child-spawn-refused` to the PARENT's
+    log on a non-preview apply — that is an audit of a real refusal, not an
+    effect on the target.)
+  - **Exclusive placement**: the home is reserved with a non-recursive `mkdir`
+    immediately after the decision check; a concurrent spawn that lost refuses
+    **`E_PLACEMENT_TAKEN`** having touched nothing. Two concurrent applies of
+    one decision yield exactly one home. There is no wider lock; this
+    reservation is the guarantee.
+  - Gate confirmation AND the exec owner on `spawn-preview-2` +
+    `spawn-apply-2` + `spawn-idempotency`; a legacy local request on such a CLI
+    is refused by the Desktop (`E_PLAN_REQUIRED`), not routed around the fence.
+- **Replay custody** (0.24.10+, feature **`spawn-idempotency-2`** — gate on
+  this, not on `spawn-idempotency`, whose replay could be blocked by
+  `E_BRANCH_EXISTS`): key recovery runs **first**, right after the name is
+  decided and before any placement/branch/base/preflight/backend work — so a
+  retry of a spawn that created its explicit branch still reaches its receipt.
+  The key-bearing home records `spawnCompleted:false` at its first write and
+  `true` only after launch + lineage + final events; a same-key retry of an
+  unfinished spawn refuses **`E_SPAWN_INCOMPLETE`** (`details.{instance, home,
+  launched}`; remedy is the session surface, never another spawn). The key
+  lives in the home by design: durable across the GUI's restart, gone with a
+  retired home — after a retire, "check result" is a roster question. The wake
+  outcome is recorded (`wake {requested, saved, error}`) and returned on
+  replay; `saved:null` means *not recorded* (crash in the interval) — render
+  "Agent created; wake outcome unavailable — check Schedules", never
+  saved/not-saved without the record.
+- **Retention stays clean**: the completion marker and the wake record are
+  kernel writes to `instance.json` made after the spawn's retirement baseline;
+  the kernel re-stamps the baseline's home fingerprint after each, so a fresh
+  keyed home retires with **no** `changed instance-home bytes` — only the
+  agent's own changes ever read as work to recover.
+- **Idempotent apply** (0.24.10+, feature `spawn-idempotency`): `spawn …
+  --expect-decision <rev> --idempotency-key <key>` records the key and the
+  decision in the new home's `instance.json`; a **retry with the same key**
+  replays the recorded receipt (`replayed: true`, same instance/home, no second
+  spawn, no wake re-saved) — found by key across the soul's instances, never by
+  name (the planned name may have been auto-suffixed past it, which is exactly
+  the retry case). The same key with a *different* decision refuses
+  **`E_IDEMPOTENCY_CONFLICT`** (`details.instance/home` of the prior spawn); a
+  different key with a fresh decision is a genuinely new confirmation. Mint the
+  key server-side on the first confirmation and keep it for that intent's
+  retries (as 2c does); a lost response is a replay, never a guess by name.
+- 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 +384,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