@awebai/oats 0.24.7 → 0.24.9

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,
+  findTeamAgent, findTeamInstance, findCapabilityAgent, findInstanceHome, findInstanceHomes, listCapabilityAgents, workspaceOf, stopInstanceSession, recomposeInstanceInstructions,
   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";
@@ -59,12 +59,16 @@ import { CAPTURED_OPERATION_TIMEOUT_MS, runCapturedOperationProcess } from "../l
 import { approveCapturedCapability } from "../lib/artifact-approvals.mjs";
 import { loadSetupExpertEdition, SETUP_EXPERT, SETUP_CAPABILITIES } from "../lib/setup-expert-source.mjs";
 import { observeInstanceGit, diffInstanceFile } from "../lib/instance-git.mjs";
+import { planStop, applyStop, planRetire, resolveInstance as resolveInstanceForCli } from "../lib/instance-lifecycle.mjs";
+const await_import_lifecycle = () => ({ resolveInstance: resolveInstanceForCli });
+import { readinessOf, policyOf } from "../lib/readiness.mjs";
+import { readEvents } from "../lib/instance-events.mjs";
 import { parsePortableSource } from "../lib/source-spec.mjs";
 
 const args = process.argv.slice(2);
 let cmd = args[0];
 const HELP_WORDS = new Set(["help", "--help", "-h"]);
-const KERNEL_COMMANDS = new Set(["prepare", "capture", "config", "create", "doctor", "inspect", "instance", "operation", "soul", "launch-config", "experimental", "onboard", "init", "inject", "install", "list", "catalog", "migrate", "pane", "recall", "remove", "retire", "root", "schedule", "server", "session", "setup", "spawn", "status", "trust", "type", "update", "use", "version"]);
+const KERNEL_COMMANDS = new Set(["prepare", "capture", "config", "create", "doctor", "inspect", "instance", "operation", "readiness", "soul", "launch-config", "experimental", "onboard", "init", "inject", "install", "list", "catalog", "migrate", "pane", "recall", "remove", "retire", "root", "schedule", "server", "session", "setup", "spawn", "status", "trust", "type", "update", "use", "version"]);
 const flag = (name) => {
   const i = args.indexOf(`--${name}`);
   return i >= 0 ? (args[i + 1] && !args[i + 1].startsWith("--") ? args[i + 1] : true) : undefined;
@@ -596,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` };
@@ -611,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 };
 }
@@ -822,7 +830,7 @@ function homeContexts(home, meta) {
  *  about the soul, not a prompt to infer one. */
 function soulDeclarations(soulDir) {
   const file = join(soulDir, "soul.yaml");
-  const empty = { declarations: { requires: null, defaults: null, knowledge: null, teams: null, resources: null }, provenance: null, problems: [] };
+  const empty = { declarations: { requires: null, defaults: null, knowledge: null, teams: null, resources: null, children: null }, provenance: null, problems: [] };
   if (!existsSync(file)) return empty;
   let parsed;
   try { parsed = withConfigFile(file, () => parseYamlNested(readFileSync(file, "utf8"))); }
@@ -830,7 +838,7 @@ function soulDeclarations(soulDir) {
   const section = (key) => (parsed[key] !== undefined && parsed[key] !== null && typeof parsed[key] === "object") ? parsed[key] : (parsed[key] === undefined ? null : parsed[key]);
   const provenance = section("provenance");
   return {
-    declarations: { requires: section("requires"), defaults: section("defaults"), knowledge: section("knowledge"), teams: section("teams"), resources: section("resources") },
+    declarations: { requires: section("requires"), defaults: section("defaults"), knowledge: section("knowledge"), teams: section("teams"), resources: section("resources"), children: section("children") },
     provenance: provenance && typeof provenance === "object" ? {
       kind: provenance.kind ?? null, source: provenance.source ?? null, revision: provenance.revision ?? null,
       path: provenance.path ?? null, workspaceRevision: provenance.workspaceRevision ?? null,
@@ -860,8 +868,12 @@ function soulEntry(soul, root, { capability } = {}) {
  *  invoking process's ambient agents-root override must not redirect them
  *  to its own deployment. */
 function dropAmbientRoot() { delete process.env.PI_AGENTS_ROOT; }
-function inspectCmd() {
-  const bail = (code, msg) => (JSON_MODE ? jsonFail(code, msg) : die(msg));
+function inspectCmd() { const result = computeInspect(); if (!result) return; if (JSON_MODE) { const { _print, ...data } = result; jsonOk(data); return; } printInspect(result); }
+/** The inspect answer as data — shared by `oats inspect` and `oats readiness`
+ *  (K5), so the readiness quartet is derived from the SAME capability,
+ *  activation, trust and soul facts inspect reports, never a second opinion. */
+function computeInspect({ onFail } = {}) {
+  const bail = onFail || ((code, msg) => (JSON_MODE ? jsonFail(code, msg) : die(msg)));
   dropAmbientRoot();
   const homeFlag = flag("home");
   const home = homeFlag === true ? bail("E_BAD_ARGS", "--home needs an absolute instance home") : homeFlag;
@@ -936,8 +948,8 @@ function inspectCmd() {
         const h = capabilityHealth(p.level, c, rows.capabilities[c.id], rows.packages[p.package]);
         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, 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 },
+          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, executableSurface: hasExecutableSurface(c.manifest), integrity: c.integrity || null, installedIntegrity: h.integrity ?? null },
         });
       }
     }
@@ -945,13 +957,13 @@ function inspectCmd() {
   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
@@ -1051,7 +1063,12 @@ function inspectCmd() {
     problems: [...(lockError ? [lockError] : []), ...packagedDiagnostics.map((d) => ({ code: d.code, message: d.message, capability: d.capability })),
       ...(meta ? snapshotCaps.filter((c) => !mans[c.id]).map((c) => ({ code: "captured-capability-missing", message: `${c.id} was active when this home was composed but no manifest for it is acquired now`, capability: c.id })) : [])],
   };
-  if (JSON_MODE) { jsonOk(result); return; }
+  result._print = { ctx, selectedSoul, home };
+  return result;
+}
+function printInspect(result) {
+  const { ctx, selectedSoul, home } = result._print; delete result._print;
+  const { souls, layers, capabilities } = result;
   console.log(`oats inspect — ${shortPath(ctx)}${selectedSoul ? ` soul ${selectedSoul.name}` : ""}${home ? ` home ${shortPath(home)}` : ""}`);
   for (const s of souls) console.log(`  soul ${s.name} [${s.kind}${s.capability ? ` ${s.capability}` : ""}] runtime ${s.runtime}${s.model ? ` model ${s.model}` : ""} work ${s.work}${s.editable.fields.length ? "" : " (read-only)"}`);
   for (const l of LAYERS) console.log(`  layer ${l}: ${layers[l].id || (layers[l].disabled ? "disabled" : "none")}${layers[l].provenance ? `  (${layers[l].provenance})` : ""}`);
@@ -3116,9 +3133,55 @@ function renderMergeRegion(r) {
 function instanceCmd() {
   const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
   const sub = args[1], name = args[2];
-  const usage = "usage: oats instance git <instance> [--home <abs>] [--dir <d>] [--json] | oats instance diff <instance> --file <id> --revision <rev> [--index-revision <rev>] [--home <abs>] [--dir <d>] [--json]";
-  if (!["git", "diff"].includes(sub) || !name || name.startsWith("--")) return bail("E_BAD_ARGS", usage);
+  const usage = "usage: oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--dir <d>] [--json] | oats instance git <instance> [--home <abs>] [--dir <d>] [--json] | oats instance diff <instance> --file <id> --revision <rev> [--index-revision <rev>] [--home <abs>] [--dir <d>] [--json] | oats instance stop <instance> (--plan | --apply --plan-revision <rev> --idempotency-key <key>) [--no-recursive] [--grace-ms <n>] [--home <abs>] [--dir <d>] [--json]";
+  if (!["git", "diff", "stop", "events"].includes(sub) || !name || name.startsWith("--")) return bail("E_BAD_ARGS", usage);
   dropAmbientRoot();
+  if (sub === "events") {
+    // K7: typed producer events, bounded window; nothing inferred.
+    const homeOpt = flag("home"); if (homeOpt === true || (homeOpt !== undefined && !isAbsolute(homeOpt))) return bail("E_BAD_ARGS", "--home needs an absolute instance home");
+    let root; try { root = ensureRoot(dirFlag()); } catch (e) { return bail(e.code || "E_NO_ROOT", e.message); }
+    const limit = flag("limit"); const since = flag("since");
+    if (limit === true || since === true) return bail("E_BAD_ARGS", usage);
+    try {
+      const { resolveInstance } = await_import_lifecycle();
+      let home = homeOpt;
+      if (!home) home = resolveInstance(dirFlag(), root, name).home;
+      const ev = readEvents(home, { ...(limit !== undefined ? { limit: Math.max(1, Math.min(2000, Number(limit) || 200)) } : {}), ...(since ? { since } : {}) });
+      if (JSON_MODE) { jsonOk(ev); return; }
+      console.log(`${ev.instance}: ${ev.returned} of ${ev.count} event(s)${ev.truncated ? " (window truncated)" : ""}${ev.waitingOnYou ? ` — waiting on you since ${ev.waitingOnYou.since} (${ev.waitingOnYou.producer})` : ""}`);
+      for (const e of ev.events) console.log(`  ${e.at ?? "?"}  ${e.kind.padEnd(20)} ${e.producer}${e.data ? `  ${JSON.stringify(e.data).slice(0, 120)}` : ""}`);
+      return;
+    } catch (e) { return bail(e.code || "E_EVENTS_FAILED", e.message, e.candidates ? { candidates: e.candidates } : undefined); }
+  }
+  if (sub === "stop") {
+    // K3: plan → apply. The plan is what a confirmation shows; apply carries
+    // its revision back and refuses if reality moved.
+    const homeOpt = flag("home");
+    if (homeOpt === true || (homeOpt !== undefined && !isAbsolute(homeOpt))) return bail("E_BAD_ARGS", "--home needs an absolute instance home");
+    let root; try { root = ensureRoot(dirFlag()); } catch (e) { return bail(e.code || "E_NO_ROOT", e.message); }
+    const recursive = !args.includes("--no-recursive");
+    const wantPlan = args.includes("--plan"), wantApply = args.includes("--apply");
+    if (wantPlan === wantApply) return bail("E_BAD_ARGS", "stop needs exactly one of --plan or --apply");
+    try {
+      if (wantPlan) {
+        const plan = planStop(dirFlag(), root, name, { home: homeOpt, recursive });
+        if (JSON_MODE) { jsonOk(plan); return; }
+        console.log(`stop ${name}${recursive ? " (and recorded children)" : ""} — plan ${plan.planRevision}`);
+        for (const t of plan.targets) console.log(`  ${"  ".repeat(t.depth)}${t.instance}: session ${t.session.state}${t.work.observed ? `, ${t.work.changed} changed / ${t.work.untracked} untracked on ${t.work.branch ?? "detached"}` : ", work not observed"}${t.midTask === true ? " — mid-task" : t.midTask === "unknown" ? " — activity unknown" : ""}`);
+        for (const n of plan.notes) console.log(`  note: ${n}`);
+        console.log(`apply with: oats instance stop ${name} --apply --plan-revision ${plan.planRevision} --idempotency-key <key>`);
+        return;
+      }
+      const rev = flag("plan-revision"), key = flag("idempotency-key"), grace = flag("grace-ms");
+      if (rev === true || key === true || grace === true) return bail("E_BAD_ARGS", usage);
+      const receipt = applyStop(dirFlag(), root, name, { home: homeOpt, recursive, planRevision: rev, idempotencyKey: key, ...(grace !== undefined ? { graceMs: Number(grace) } : {}) });
+      if (JSON_MODE) { jsonOk(receipt); return; }
+      for (const r of receipt.results) console.log(`  ${r.instance}: ${r.ok ? (r.stopped ? "stopped" : `already ${r.state}`) : `${r.code} — ${r.message}`}`);
+      console.log(receipt.ok ? `stopped${receipt.replayed ? " (replayed receipt)" : ""}; home, work, transcript and launch configuration retained — restart with \`oats session restart\`` : "some targets are still running; nothing was escalated");
+      if (!receipt.ok) process.exit(1);
+      return;
+    } catch (e) { return bail(e.code || "E_LIFECYCLE_FAILED", e.message, e.plan ? { plan: e.plan } : e.candidates ? { candidates: e.candidates } : undefined); }
+  }
   let home = flag("home");
   if (home === true) return bail("E_BAD_ARGS", "--home needs an absolute instance home");
   if (home !== undefined && !isAbsolute(home)) return bail("E_BAD_ARGS", "--home needs an absolute instance home");
@@ -3156,6 +3219,49 @@ function instanceCmd() {
     bail(e.code || "E_GIT_FAILED", e.message, e.observation ? { observation: e.observation } : undefined);
   }
 }
+/** `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;
+  // 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;
+    if (homeOpt && homeOpt !== true) { try { meta = JSON.parse(readFileSync(join(homeOpt, "instance.json"), "utf8")); } catch (e) { return bail("E_SESSION_UNKNOWN", `${homeOpt}: ${e.message}`); } }
+    readiness.policy = policyOf({ instanceMeta: meta, soul: soul ? inspect.souls.find((s) => s.name === soul) : null }).policy;
+    readiness.notes.push("policy: a lifecycle-authority claim enforced by the spawn route, not an OS sandbox");
+  }
+  if (JSON_MODE) { jsonOk(readiness); return; }
+  console.log(`readiness — ${readiness.subject.kind === "soul" ? `soul ${readiness.subject.name}` : shortPath(readiness.subject.context)}: ${readiness.summary.ready ? "READY" : `${readiness.summary.fail} failing, ${readiness.summary.unknown} unknown of ${readiness.summary.required} required`}`);
+  for (const [name, check] of Object.entries(readiness.checks)) {
+    console.log(`  ${name}: ${check.status}`);
+    for (const i of check.items) console.log(`    ${i.status.padEnd(14)} ${i.subject}${i.required ? "" : " (optional)"}${i.reason ? ` — ${i.reason}` : ""}${i.signature ? ` · signature ${i.signature.status}${i.signature.signer?.label ? ` by ${i.signature.signer.label}` : ""}` : ""}${i.remedy ? `  → ${i.remedy}` : ""}`);
+  }
+  if (readiness.policy) console.log(`  policy: child spawns ${readiness.policy.childSpawns.allowed ? "allowed" : "disabled"} (${readiness.policy.childSpawns.origin.kind}${readiness.policy.childSpawns.enforced ? ", enforced" : ""}); worktrees ${readiness.policy.worktrees.allowed === null ? "unknown" : readiness.policy.worktrees.allowed ? "allowed" : "not in this work mode"}`);
+  for (const n of readiness.notes) console.log(`  note: ${n}`);
+}
 function catalogCmd() {
   const described = describeOfficialCatalog();
   if (JSON_MODE) { jsonOk(described); return; }
@@ -4066,7 +4172,7 @@ function spawnCmd() {
   };
   checkDirectoryOptions(requestedWork); // before a local soul could be upserted
   const name = args[1];
-  if (!name || name.startsWith("--")) bail("E_USAGE", "usage: oats spawn <agent> [--task <text>|--task-file <f>] [--purpose <slug>] [--relation child|sibling|parent|unrelated --relative-to <instance> [--relative-root <agents-root>]] [--parent <instance>] [--repo <r>] [--work worktree|checkout|attached|workspace|directory] [--work-dir <owner-work>] [--runtime pi|claude|codex] [--backend tmux|herdr] [--herdr-socket <path>] [--yolo|--no-yolo] [--model <m>] [--branch <b>] [--instructions-file <f>|--def-file <f>] [--no-launch] [--json]");
+  if (!name || name.startsWith("--")) bail("E_USAGE", "usage: oats spawn <agent> [--task <text>|--task-file <f>] [--purpose <slug>] [--preview] [--base <ref>] [--model <id>|@native-default] [--allow-child-spawns|--no-child-spawns] [--relation child|sibling|parent|unrelated --relative-to <instance> [--relative-root <agents-root>]] [--parent <instance>] [--repo <r>] [--work worktree|checkout|attached|workspace|directory] [--work-dir <owner-work>] [--runtime pi|claude|codex] [--backend tmux|herdr] [--herdr-socket <path>] [--yolo|--no-yolo] [--model <m>] [--branch <b>] [--instructions-file <f>|--def-file <f>] [--no-launch] [--json]");
   // Retired boundary flags (maintainer transport ruling): fail LOUDLY before
   // ANY side effect — including root discovery and local-agent upsert (an
   // --instructions-file spawn must not scaffold/overwrite a local soul before
@@ -4076,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) {
@@ -4184,8 +4304,11 @@ function spawnCmd() {
   } catch (e) { if (e?.code?.startsWith?.("E_")) bail(e.code, e.message); throw e; }
   let r;
   try {
+    if (args.includes("--allow-child-spawns") && args.includes("--no-child-spawns")) bail("E_BAD_ARGS", "--allow-child-spawns and --no-child-spawns contradict");
+    if (flag("base") === true) bail("E_BAD_ARGS", "--base needs a ref");
     r = spawnInstance(root, agent, {
       purpose: flag("purpose"), task: taskText, taskFile: taskFileFlag, relation, relativeTo, relativeRoot,
+      ...(args.includes("--allow-child-spawns") ? { allowChildSpawns: true } : args.includes("--no-child-spawns") ? { allowChildSpawns: false } : {}),
       // Directory execution uses deployment configuration, not an ambient Git
       // checkout (especially when invoked via --dir from a source instance).
       repo: (requestedWork || agent.work) === "directory"
@@ -4193,7 +4316,15 @@ function spawnCmd() {
       work: requestedWork, workDir, runtime: flag("runtime"), backend, herdrSocket, yolo, model: flag("model"), branch,
       launchConfig: valueFlag("launch-config"),
       launch: !args.includes("--no-launch"),
+      // 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, 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) {
     // A typed CLI failure keeps ITS OWN code: re-badging an unsafe-config-key
     // (raised by the readers spawn walks) as E_SPAWN_FAILED tells an agent
@@ -4207,6 +4338,10 @@ function spawnCmd() {
     // An unmet declared requirement is a fact about the soul's configuration
     // (with a remedy), not a spawn-mechanism failure: keep its code and details.
     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
@@ -4243,9 +4378,23 @@ function spawnCmd() {
 
 function retireCmd() {
   const name = args[1];
-  if (!name || name.startsWith("--")) die("usage: oats retire <instance> [--home <path>] [--self] [--delete-branch] [--keep-dir] [--force] [--json]");
+  if (!name || name.startsWith("--")) die("usage: oats retire <instance> [--plan] [--plan-revision <rev> --idempotency-key <key>] [--home <path>] [--self] [--discard-worktree] [--delete-branch] [--keep-dir] [--force] [--json]");
   let homeFlag = flag("home");
   if (homeFlag === true) die("--home needs the instance home path");
+  if (args.includes("--plan")) {
+    // K3: what retirement would touch, with the design's defaults — read-only.
+    dropAmbientRoot();
+    let root; try { root = ensureRoot(dirFlag()); } catch (e) { return args.includes("--json") ? jsonFail(e.code || "E_NO_ROOT", e.message) : die(e.message); }
+    try {
+      const plan = planRetire(dirFlag(), root, name, { home: homeFlag });
+      if (args.includes("--json")) { jsonOk(plan); return; }
+      console.log(`retire ${name} — plan ${plan.planRevision}`);
+      console.log(`  session ${plan.facts.session.state}; work ${plan.facts.work.observed ? `${plan.facts.work.changed} changed / ${plan.facts.work.untracked} untracked on ${plan.facts.work.branch ?? "detached"}` : `not observed (${plan.facts.work.reason})`}; children ${plan.facts.children.length}; pull request ${plan.facts.pullRequest}`);
+      console.log(`  defaults: retain worktree ${plan.defaults.retainWorktree}, delete branch ${plan.defaults.deleteBranch}, stop children ${plan.defaults.stopChildren}`);
+      for (const n of plan.notes) console.log(`  note: ${n}`);
+      return;
+    } catch (e) { return args.includes("--json") ? jsonFail(e.code || "E_LIFECYCLE_FAILED", e.message, e.candidates ? { candidates: e.candidates } : undefined) : die(e.message); }
+  }
   // The calling instance knows its own home: self-retire never needs to
   // disambiguate a same-named twin by hand.
   if (homeFlag === undefined && process.env.OATS_INSTANCE_HOME && (process.env.PI_AGENT_INSTANCE === name || process.env.OATS_INSTANCE === name)) homeFlag = process.env.OATS_INSTANCE_HOME;
@@ -4260,7 +4409,39 @@ function retireCmd() {
     if (hit && resolve(hit.root) !== resolve(root)) { root = hit.root; (args.includes("--json") ? console.error : console.log)(`(cross-repo: instance homes at ${shortPath(root)})`); }
   }
   const retiringHome = homeFlag || findInstanceHome(root, name);
-  const r = retireInstance(root, name, { home: homeFlag, self: isSelf, deleteBranch: args.includes("--delete-branch"), keepDir: args.includes("--keep-dir"), force: args.includes("--force") });
+  // K3: a GUI-driven Remove carries the plan revision it showed and an
+  // idempotency key. The revision is revalidated against a fresh plan
+  // (E_PLAN_STALE with that plan attached — re-confirm, never act on the old
+  // one); a retried key replays the recorded receipt instead of retiring twice.
+  const planRev = flag("plan-revision"), idemKey = flag("idempotency-key");
+  if (planRev === true || idemKey === true) die("--plan-revision and --idempotency-key need values");
+  if ((planRev !== undefined) !== (idemKey !== undefined)) die("--plan-revision and --idempotency-key go together");
+  let replayPath = null, childrenStopped = null, expectedBranch;
+  if (planRev !== undefined) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(idemKey)) die("--idempotency-key: 1-128 chars of [A-Za-z0-9._:-]");
+    // Replay first: after a successful retire the home is gone, so the receipt
+    // (beside the instances dir, keyed by the idempotency key) is the answer.
+    const replay = (dir) => { const p = join(dir, `.oats-retire-receipt.${idemKey}.json`); if (!existsSync(p)) return false; try { const prior = JSON.parse(readFileSync(p, "utf8")); if (prior.retired !== name) return false; if (args.includes("--json")) jsonOk({ ...prior, replayed: true }); else console.log(`retire ${name}: replayed receipt for key ${idemKey}`); return true; } catch { return false; } };
+    for (const a of listAgents(root)) if (replay(join(a._dir, "instances"))) return;
+    let fresh;
+    try { fresh = planRetire(dirFlag(), root, name, { home: homeFlag }); } catch (e) { return args.includes("--json") ? jsonFail(e.code || "E_LIFECYCLE_FAILED", e.message) : die(e.message); }
+    replayPath = join(dirname(fresh.home), `.oats-retire-receipt.${idemKey}.json`);
+    if (fresh.planRevision !== planRev) return args.includes("--json") ? jsonFail("E_PLAN_STALE", `the retire plan changed since it was shown (${planRev} → ${fresh.planRevision}); review the fresh plan`, { plan: fresh }) : die(`the retire plan changed since it was shown; re-run oats retire ${name} --plan`);
+    // The plan promised: recorded children are STOPPED first (bounded, never
+    // escalated) and retained. A child still running after the grace refuses
+    // the retirement — nothing is retired, the receipt names the pid.
+    childrenStopped = [];
+    for (const kid of fresh.facts.children) {
+      try { const s = stopInstanceSession(kid.home, {}); childrenStopped.push({ instance: kid.instance, home: kid.home, ok: true, stopped: s.stopped, alreadyIdle: s.alreadyIdle }); }
+      catch (e) { childrenStopped.push({ instance: kid.instance, home: kid.home, ok: false, code: e.code || "E_SESSION_STOP_FAILED", message: e.message, stillRunning: e.receipt?.stillRunning ?? null }); }
+    }
+    const running = childrenStopped.filter((k) => !k.ok);
+    if (running.length) return args.includes("--json") ? jsonFail("E_CHILDREN_RUNNING", `${running.map((k) => k.instance).join(", ")} ${running.length === 1 ? "is" : "are"} still running after a bounded stop; nothing was retired and nothing was escalated`, { childrenStopped, plan: fresh }) : die(`children still running: ${running.map((k) => k.instance).join(", ")}; nothing retired`);
+    expectedBranch = fresh.facts.work.observed ? fresh.facts.work.branch : undefined;
+  }
+  const r = retireInstance(root, name, { home: homeFlag, self: isSelf, deleteBranch: args.includes("--delete-branch"), discardWorktree: args.includes("--discard-worktree"), keepDir: args.includes("--keep-dir"), force: args.includes("--force"), ...(expectedBranch !== undefined ? { expectedBranch } : {}) });
+  if (childrenStopped) r.childrenStopped = childrenStopped;
+  if (replayPath) { r.planRevision = planRev; r.idempotencyKey = idemKey; r.replayed = false; try { writeFileAtomic(replayPath, JSON.stringify(r, null, 2)); } catch { /* receipt is evidence, not authority */ } }
   // A retired home's wake jobs are forgotten (definitions only; nothing is
   // stopped by this); a deferred self-retire keeps them until the home is gone.
   if (retiringHome && r.removedDir !== false && !r.deferred) { try { const gone = removeWakeForHome(scheduleScopeOf(workspaceOf(root)), retiringHome); if (gone.length) r.wakeSchedulesRemoved = gone; } catch (e) { r.warnings = [...(r.warnings || []), `wake schedules not cleaned: ${e.message}`]; } }
@@ -4362,6 +4543,7 @@ async function sessionCmd() {
       return;
     }
     if (args[1] === "inspect") result = inspectInstanceSession(home);
+    else if (args[1] === "recompose") result = recomposeInstanceInstructions(home, { dryRun: args.includes("--dry-run") });
     else if (args[1] === "start" || args[1] === "restart") {
       const bad = (msg) => { throw Object.assign(new Error(msg), { code: "E_BAD_ARGS" }); };
       const model = flag("model");
@@ -4836,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"], 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)`);
@@ -5278,6 +5460,7 @@ else if (cmd === "config") configCmd();
 else if (cmd === "trust") trust();
 else if (cmd === "list") listCmd();
 else if (cmd === "catalog") catalogCmd();
+else if (cmd === "readiness") readinessCmd();
 else if (cmd === "instance") instanceCmd();
 else if (cmd === "remove") removeCmd();
 else if (cmd === "migrate") migrateCmd();
@@ -5480,6 +5663,36 @@ Usage:
   oats instance diff <instance> --file <id> --revision <rev> [--index-revision <rev>] [--home <abs>] [--dir <d>] [--json]
                                              bounded diff of one observed file; refuses when
                                              the tree moved since the observation
+  oats session recompose --home <abs> [--dry-run] [--json]
+                                             refresh a LIVE home's AGENTS.md from its current
+                                             canonical soul + context (same composer as spawn);
+                                             previous text retained; nothing restarted
+  oats instance events <instance> [--limit <n>] [--since <iso>] [--json]
+                                             typed lifecycle events (spawned, launched, stopped,
+                                             restarted, retired, worktree-retained…) written by
+                                             the action that made them true; nothing inferred
+  oats instance stop <instance> --plan [--no-recursive] [--json]
+                                             what Stop would touch: session state, recorded
+                                             children, dirty work; a planRevision to apply
+  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> [--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
+                                             child-spawn / worktree policy with origins
+  oats retire <instance> --plan [--json]     what Remove would touch, with retention defaults
+  oats retire <instance> [--plan-revision <rev> --idempotency-key <key>] [--discard-worktree] [--delete-branch]
+                                             with a plan revision: refuses E_PLAN_STALE (fresh plan
+                                             attached) if facts moved; a repeated key replays
+                                             retire; a worktree is RETAINED (re-homed under
+                                             <workspace>/.agents/worktrees/<repo>/<branch>)
+                                             unless discarded; --delete-branch deletes the
+                                             worktree's verified branch and implies discard
   oats update <package> [<package>@<ref>]    transactional package update: temp fetch,
       [--to <ref>] [--dir <d>]              closure validation, diff, lock replace,
                                             all capability approvals invalidated; a

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;
   }