@awebai/oats 0.22.0 → 0.22.2

package/lib/core.mjs

@@ -23,17 +23,20 @@
  * soul.yaml (flat key: value):
  *   name, description, kind (persistent|local), type (optional agent-type/family, targeted by config),
  *   repo (path rel. to workspace or absolute),
- *   work (worktree|checkout|attached), runtime (pi|claude), model (pi model pattern, optional)
+ *   work (worktree|checkout|attached), runtime (pi|claude|codex), model (pi model pattern, optional)
  *   (attached as soul default is for service agents — spawn must supply workDir)
  */
-import { execFileSync, execSync } from "node:child_process";
+import { execFileSync, execSync, spawn as spawnProcess } from "node:child_process";
 import {
-  chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, symlinkSync, writeFileSync,
+  chmodSync, closeSync, copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, symlinkSync, writeFileSync,
 } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { homedir, tmpdir } from "node:os";
 import { createHash } from "node:crypto";
 import { fileURLToPath } from "node:url";
+import { attachSessionTarget } from "./session-viewer.mjs";
+import { inspectSessionTarget, inputSessionTarget } from "./session-input.mjs";
+import { ensureHerdr, allocateHerdr, launchHerdr, inspectHerdr, stopHerdr, validHerdrTarget } from "./herdr.mjs";
 
 export const RESERVED = new Set(["bin", "local-agents", "tmp-agents"]);
 /** The work modes spawn accepts — also the enum a quarantine cleanup descriptor
@@ -426,7 +429,7 @@ export const RETIRED_CAPABILITIES = {
 export function retiredCapabilityReason(id) {
   return Object.hasOwn(RETIRED_CAPABILITIES, id) ? RETIRED_CAPABILITIES[id] : undefined;
 }
-const CONFIG_KEYS = new Set(["name", "team", "agent-types", "capabilities", "skill-overrides", "agents-md-injection", "oats", "work-modes", "templates"]);
+const CONFIG_KEYS = new Set(["name", "team", "agent-types", "capabilities", "skill-overrides", "agents-md-injection", "oats", "work-modes", "templates", "yolo"]);
 /** Renamed-key tables are read with OWN-property semantics only: a config key
  * spelled `constructor`/`toString` inherits a value from `Object.prototype`,
  * and the plain `TABLE[key]` lookup then reported it as the migration hint —
@@ -467,6 +470,7 @@ function loadLevelConfig(dir) {
  * Shared by the level loader and package profile validation (a profile is
  * config source material and must pass the same shape checks). */
 export function validateConfigShape(cfg, file) {
+  if (cfg.yolo !== undefined && typeof cfg.yolo !== "boolean") throw new Error(`yolo in ${file} must be true or false`);
   for (const key of Object.keys(cfg)) {
     if (Object.hasOwn(RENAMED_CONFIG_KEYS, key)) throw new Error(`unsupported oats-config key "${key}" in ${file} — ${RENAMED_CONFIG_KEYS[key]}`);
     if (!CONFIG_KEYS.has(key)) throw new Error(`unsupported oats-config key in ${file}: ${key}`);
@@ -725,6 +729,8 @@ export function resolveCapabilities(contextDir, soulName) {
 export function resolveOatsConfig(contextDir, soulName) {
   const chain = configChain(contextDir);
   const out = { layers: {}, provenance: {}, layerDisabled: {}, injects: [], capabilities: [], name: chain[0]?.name, chain };
+  const yoloCfg = chain.find((c) => c.yolo !== undefined);
+  if (yoloCfg) out.yolo = yoloCfg.yolo;
   // Closest team: declaration wins; the declaring scope is the deployment/team boundary.
   const teamCfg = chain.find((c) => c.team);
   if (teamCfg) out.team = { ...teamCfg.team, scope: teamCfg._level };
@@ -4395,7 +4401,7 @@ export function runLifecycleHooks(event, { home, instance, agentName, soulDir, c
           // OATS_INSTANCE_HOME is the runtime-neutral contract name for the
           // instance home (absolute). OATS_HOME predates it and stays as a
           // compatibility alias: shipped capability hooks read it
-          // (capabilities/oats-aweb, capabilities/oats-okf) and are versioned
+          // (the official oats.aweb and oats.okf packages) and are versioned
           // independently of this kernel. Neither is OATS_HOME_DIR, which is
           // the package STORE root — do not conflate them.
           OATS_EVENT: event, OATS_INSTANCE: instance, OATS_INSTANCE_HOME: home, OATS_HOME: home, OATS_AGENT: agentName,
@@ -4665,7 +4671,7 @@ export function appendLogEntry(file, entry, title = "Log") {
   writeFileSync(file, lines.join("\n").replace(/\n{3,}/g, "\n\n"));
 }
 
-// (soul knowledge scaffolding belongs to capabilities/oats-okf — soul-scaffold hook)
+// (soul knowledge scaffolding belongs to the oats.okf package — soul-scaffold hook)
 
 // ---------- soul scaffolding ----------
 function fileSnapshot(dir) {
@@ -4716,13 +4722,22 @@ function runSoulScaffoldHooks(args) {
   if (Object.keys(owners).length) writeFileSync(ownersFile, JSON.stringify(owners, null, 2) + "\n");
 }
 
-export function writeSoul(root, { name, kind, repo, work, runtime, model, description, type, instructions }) {
+/** Flat soul YAML uses strings; never treat the string "false" as truthy. */
+export function resolveYolo(value) {
+  if (value === undefined) return undefined;
+  if (value === true || value === "true") return true;
+  if (value === false || value === "false") return false;
+  throw new Error("yolo must be true or false");
+}
+
+export function writeSoul(root, { name, kind, repo, work, runtime, model, yolo, description, type, instructions }) {
+  yolo = resolveYolo(yolo);
   const agentDir = agentDirOf(root, name, kind);
   const soulDir = soulOf(agentDir);
   mkdirSync(soulDir, { recursive: true });
   mkdirSync(join(agentDir, "instances"), { recursive: true });
   writeFileSync(join(soulDir, "soul.yaml"), yamlFlat({
-    name, kind, description, type, repo, work: work || "checkout", runtime: runtime || "pi", model,
+    name, kind, description, type, repo, work: work || "checkout", runtime: runtime || "pi", model, yolo,
   }));
   const agentsMd = join(soulDir, "AGENTS.md");
   if (instructions !== undefined || !existsSync(agentsMd)) {
@@ -4767,7 +4782,7 @@ export function createAgent(root, o) {
  * Local souls are full souls — same scaffold and memory as persistent ones —
  * that live in the scope's uncommitted local-agents/. */
 export function upsertLocalAgent(root, o) {
-  let { name, instructions, description, model, repo, work, runtime } = o;
+  let { name, instructions, description, model, repo, work, runtime, yolo } = o;
   if (o.file) {
     const f = resolve(o.file);
     if (!existsSync(f)) throw new Error(`file not found: ${f}`);
@@ -4778,6 +4793,7 @@ export function upsertLocalAgent(root, o) {
     repo = repo ?? meta.repo;
     work = work ?? meta.work;
     runtime = runtime ?? meta.runtime;
+    yolo = yolo ?? meta.yolo;
     instructions = body;
   }
   if (!name) throw new Error("local agent requires a name");
@@ -4789,7 +4805,7 @@ export function upsertLocalAgent(root, o) {
   writeSoul(root, {
     name, kind: "local",
     repo: repo ?? existing?.repo, work: work ?? existing?.work,
-    runtime: runtime ?? existing?.runtime, model: model ?? existing?.model,
+    runtime: runtime ?? existing?.runtime, model: model ?? existing?.model, yolo: yolo ?? existing?.yolo,
     description: description ?? existing?.description, instructions,
   });
   return findAgent(root, name);
@@ -4909,9 +4925,19 @@ export function resolveClaudeBinary(contextDir) {
  * pi: checked against `pi --list-models <pattern>` (authenticated providers).
  * claude: pi-style patterns are translated (anthropic/<id> → <id>) or dropped —
  * claude takes aliases/bare claude-* ids only; nothing usable → "" (claude default).
- * Unknown runtimes or probe failures: first entry wins (pi errors loudly at launch). */
+ * codex: translate openai/openai-codex entries to native ids, otherwise use its default.
+ * Probe failures: first entry wins (pi errors loudly at launch). */
 export function resolveModelPreference(model, runtime = "pi") {
   const prefs = String(model || "").split(",").map((s) => s.trim()).filter(Boolean);
+  if (runtime === "codex") {
+    for (const pref of prefs) {
+      const bare = pref.replace(/:[a-z]+$/i, "");
+      if (!bare.includes("/")) return bare;
+      const [provider, ...rest] = bare.split("/");
+      if (["openai", "openai-codex"].includes(provider) && rest.length) return rest.join("/");
+    }
+    return ""; // let Codex use its configured model rather than another provider's id
+  }
   if (runtime === "claude") {
     // Claude accepts its aliases and bare claude-* ids — NOT pi-style
     // "provider/model[:thinking]" patterns. Agents whose soul default is a
@@ -5017,8 +5043,12 @@ export function spawnInstance(root, agent, o = {}) {
   if (work === "attached" && !o.workDir) throw new Error(`attached mode needs workDir — the owning instance's work tree (its <home>/work)`);
   if (o.task !== undefined && typeof o.task !== "string") throw new Error(`task must be a string (got ${typeof o.task}) — a flag parser handing --task's next flag through shows up here`);
   const runtime = o.runtime || agent.runtime || "pi";
+  if (!["pi", "claude", "codex"].includes(runtime)) throw oatsError("E_UNSUPPORTED_RUNTIME", `unknown runtime "${runtime}" (pi|claude|codex)`);
   const model = resolveModelPreference(o.model || agent.model || "", runtime);
   const session = o.tmuxSession || DEFAULT_TMUX_SESSION;
+  const backend = o.backend || agent.backend || "tmux";
+  if (!["tmux", "herdr"].includes(backend)) throw new Error(`unknown session backend "${backend}" (tmux|herdr)`);
+  if (o.herdrSocket !== undefined && (typeof o.herdrSocket !== "string" || !o.herdrSocket)) throw oatsError("E_BAD_ARGS", "herdrSocket must be a socket path");
   const launch = o.launch !== false;
   const repoAbs = resolveRepo(root, o.repo || agent.repo);
   if (!repoAbs) throw new Error(`agent "${agent.name}" has no repo configured — pass one`);
@@ -5324,6 +5354,7 @@ export function spawnInstance(root, agent, o = {}) {
   const soulDir = agent._soulDir || soulOf(agent._dir);
   const composition = composeInstanceAgentsMd(soulDir, repoAbs, agent.name, work, agent.kind);
   const resolvedCfg = composition.resolved;
+  const yolo = resolveYolo(o.yolo ?? agent.yolo ?? resolvedCfg.yolo);
   const expectedResources = planInstanceResources({ resolved: resolvedCfg, soulDir, agent, contextDir: repoAbs, composition });
   // Runtime extensions selected by ACTIVE capabilities for THIS instance's
   // runtime. Strict launch disables ambient extension discovery, so each one has
@@ -5333,6 +5364,14 @@ export function spawnInstance(root, agent, o = {}) {
   // reconciliation, so this spawn-time check is the authoritative one.
   const runtimePackages = verifyRuntimePackages(runtime, resolvedCfg, repoAbs);
 
+  // Prerequisites must fail before creating a home, worktree, or identity.
+  const claudeBin = runtime === "claude" ? resolveClaudeBinary(repoAbs) : undefined;
+  const bin = which(runtime === "claude" ? claudeBin : runtime);
+  if (!bin) throw new Error(`${runtime === "claude" ? claudeBin : runtime} binary not found on PATH${claudeBin && claudeBin !== "claude" ? " (named by oats-claude-config)" : ""}`);
+  if (launch && !which(backend)) throw new Error(`${backend} not installed${backend === "tmux" ? " (brew install tmux)" : " (https://herdr.dev)"}`);
+  const herdrBase = launch && backend === "herdr" ? ensureHerdr({ binary: which("herdr"), socket: o.herdrSocket }) : undefined;
+  const task = o.task ?? (o.taskFile ? readFileSync(o.taskFile, "utf8") : "");
+
   mkdirSync(home, { recursive: true });
   // TOCTOU: the placement checks above ran BEFORE composition and the runtime
   // package preflight, both of which shell out — a window in which anything able
@@ -5508,41 +5547,71 @@ export function spawnInstance(root, agent, o = {}) {
   // Capability lifecycle hooks (spawn) — the knowledge integration scaffolds instance
   // memory (STATE.md/log.md/notes/ are OKF conventions, not kernel ones); the
   // messaging integration mints the comms identity. Kernel stays memory-agnostic.
-  const task = o.task ?? (o.taskFile ? readFileSync(o.taskFile, "utf8") : "");
   const hookRes = runLifecycleHooks("spawn", {
     home, instance, agentName: agent.name, soulDir, contextDir: repoAbs,
     workspaceDir: workspaceOf(root), resolved: resolvedCfg,
     extraEnv: { OATS_TASK: task, OATS_REPO: repoAbs, OATS_BRANCH: branch || "", OATS_WORK: work, OATS_RUNTIME: runtime, OATS_KIND: agent.kind || "persistent" },
   });
   warnings.push(...hookRes.warnings);
-  // A REQUIRED spawn hook that failed means an active capability is not actually
-  // configured — aweb without a minted identity is an agent that believes it can
-  // be woken by mail and cannot. Fail the spawn and roll back, rather than hand
-  // over a half-configured instance. Nothing is launched yet, so compensation is
-  // retire hooks + worktree/branch + home; the same three-state verification as
-  // the anchor-write path, because a cleanup we cannot confirm must never be
-  // reported as done.
   const requiredFailures = (hookRes.failures || []).filter((f) => f.required);
-  if (requiredFailures.length) {
-    const incomplete = [];
+  let windowMayExist = false;
+  let spawnTmux;
+  let spawnHerdr;
+  const ancillaryCleanup = [];
+  // One compensation owner, from the first hook result through launch and
+  // the final lineage write. Preserve the original failure and retain any
+  // credentials/metadata whose cleanup could not be confirmed.
+  const compensateSpawn = () => {
+    const failed = requiredFailures.length
+      ? requiredFailures.map((f) => ({ capability: f.capability, event: f.event, ...(f.contract ? { contract: f.contract } : {}) }))
+      : [{ capability: "oats.kernel", event: "spawn" }];
+    const incomplete = [...ancillaryCleanup];
     const probe = (argv) => {
       try { return { ok: true, out: execFileSync(argv[0], argv.slice(1), { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }) }; }
-      // With encoding:"utf8" a silent command yields stderr === "" — FALSY — so
-          // `e2.stderr || e2.message` fell through to "Command failed: …" and made
-          // every clean probe look like a failed one. `git rev-parse --verify
-          // --quiet` on an absent ref is exactly that case, so a successful branch
-          // deletion could never be confirmed and rollback always reported
-          // INCOMPLETE. Distinguish "no output" from "no stderr captured".
-          catch (e2) { return { ok: false, status: e2.status, err: String(e2.stderr ?? e2.message ?? "").trim() }; }
+      // An absent ref exits 1 with empty stderr; preserve that distinction.
+      catch (e2) { return { ok: false, status: e2.status, err: String(e2.stderr ?? e2.message ?? "").trim() }; }
     };
-    // Which capabilities still owe cleanup, as IDS the retry can verify against —
-    // the prose in `incomplete` tells a human what happened, but a retry needs
-    // something it can check. Without this, a retry that resolves no capabilities
-    // at all (a descriptor naming none, or config drift since the spawn) runs zero
-    // hooks, finds zero failures, and clears the quarantine having done nothing
-    // (reviewer-dd03a98).
+    // Retain cleanup owners so a retry must actually discharge their debt.
     const outstandingHooks = new Set();
     const outstandingGit = new Set();
+    // A failed new-window command may still have created its window. Verify
+    // quiescence before removing credentials or work that runtime may be using.
+    if (windowMayExist && spawnHerdr) {
+      try { stopHerdr(spawnHerdr); }
+      catch (e) {
+        incomplete.push(`Herdr session: ${e.message}`);
+        for (const cap of resolvedCfg.capabilities) if (cap.hooks?.retire) outstandingHooks.add(cap.id);
+        if (work === "worktree") { outstandingGit.add("worktree"); if (branch) outstandingGit.add("branch"); }
+        return quarantineInstanceHome({ home, instance, agent, incomplete, failed, outstandingHooks, outstandingGit,
+          repoAbs, work, branch, resolvedCfg, hookMeta: hookRes.meta || {},
+          launched: true, sessionTarget: spawnHerdr, recordRetirementBaseline: true });
+      }
+    }
+    if (windowMayExist && backend === "herdr" && !spawnHerdr) {
+      // Allocation starts only an empty shell; the harness command has not run.
+      // A lost receipt cannot authorize closing an unidentified terminal.
+      incomplete.push(`Herdr workspace allocation may have completed on ${herdrBase.socket} (label ${instance}, cwd ${home}); inspect and remove any empty workspace manually`);
+    }
+    if (windowMayExist && backend === "tmux") {
+      shTry(`tmux kill-window -t ${shq(`=${session}:=${instance}`)}`);
+      const winProbe = probe(["tmux", "list-windows", "-t", session, "-F", "#{window_name}"]);
+      const unresolved = !winProbe.ok || winProbe.out.split("\n").includes(instance);
+      if (unresolved) {
+        incomplete.push(!winProbe.ok
+          ? `tmux window ${session}:${instance}: could not verify removal (${winProbe.err || "list-windows failed"})`
+          : `tmux window ${session}:${instance} still running`);
+        for (const cap of resolvedCfg.capabilities) if (cap.hooks?.retire) outstandingHooks.add(cap.id);
+        if (work === "worktree") {
+          outstandingGit.add("worktree");
+          if (branch) outstandingGit.add("branch");
+        }
+        return quarantineInstanceHome({
+          home, instance, agent, incomplete, failed, outstandingHooks, outstandingGit,
+          repoAbs, work, branch, resolvedCfg, hookMeta: hookRes.meta || {},
+          launched: true, tmux: spawnTmux, recordRetirementBaseline: true,
+        });
+      }
+    }
     let compensationMeta = {};
     try {
       const comp = runLifecycleHooks("retire", {
@@ -5597,25 +5666,13 @@ export function spawnInstance(root, agent, o = {}) {
       incomplete.push(`${cap.id}: its spawn hook reported state it created, but the capability declares no retire hook, so OATS cannot undo it`);
       outstandingHooks.add(cap.id);
     }
-    const detail = requiredFailures.map((f) => `  ${f.capability} ${f.event} ${f.contract === "environment" ? "environment contract" : "hook (declared required)"}: ${f.message}`).join("\n");
     let note;
-    if (incomplete.length) {
-      // QUARANTINE, do not delete. Compensation could not finish, and the home
-      // holds the very credentials and metadata a retry needs — for aweb,
-      // <instance-home>/.aw is the only signing key that can self-delete the
-      // remote identity. Removing it converts a transient cleanup failure into
-      // permanent remote residue (aggregate review at 798b156). The worktree and
-      // branch are already gone where that was independently safe; nothing is
-      // launched.
-      // A quarantine cannot promise to prove zero work. If a diagnostic exists
-      // but neither category identified its owner, conservatively require every
-      // retire hook to succeed on retry.
-      if (!outstandingHooks.size && !outstandingGit.size) {
-        for (const cap of resolvedCfg.capabilities) if (cap.hooks?.retire) outstandingHooks.add(cap.id);
-      }
+    if (outstandingHooks.size || outstandingGit.size) {
+      // Preserve credentials and the original hook receipt until cleanup
+      // succeeds. The runtime is stopped; Git cleanup was independently safe.
       note = quarantineInstanceHome({
         home, instance, agent, incomplete,
-        failed: requiredFailures.map((f) => ({ capability: f.capability, event: f.event, ...(f.contract ? { contract: f.contract } : {}) })),
+        failed,
         outstandingHooks, outstandingGit, repoAbs, work, branch, resolvedCfg,
         hookMeta: hookRes.meta || {}, compensationMeta, launched: false,
         recordRetirementBaseline: true,
@@ -5625,342 +5682,258 @@ export function spawnInstance(root, agent, o = {}) {
       if (existsSync(home) && !incomplete.some((m) => m.startsWith("instance home"))) incomplete.push(`instance home ${home}: still present`);
       note = incomplete.length ? ` — rollback INCOMPLETE, clean up manually: ${incomplete.join("; ")}` : " — spawn rolled back";
     }
-    const code = requiredFailures.some((f) => f.contract === "environment") ? "E_HOOK_ENVIRONMENT_CONTRACT" : "E_REQUIRED_HOOK_FAILED";
-    throw oatsError(code, `a capability this soul activates could not configure itself:\n${detail}\n\nThe instance would have started with an invalid or missing capability configuration${note}`);
-  }
-  const briefLines = hookRes.briefs.length ? `\n${hookRes.briefs.join("\n")}` : "";
-  const workDesc = work === "worktree"
-    ? `a dedicated git worktree of ${repoAbs} on branch "${branch}" — commit freely there`
-    : work === "attached"
-    ? `ATTACHED to another instance's work tree (${o.workDir}, branch ${branch}) — you share it with that instance; make your changes and commits focused, and never switch branches`
-    : work === "workspace"
-    ? `the WHOLE WORKSPACE (${realpathSync(join(home, "work"))}) — every member repo is read-context; you coordinate, you do not edit member repos (see your work-mode briefing)`
-    : `a symlink to the ${repoAbs} checkout — you share it; work on the currently checked-out branch (${branch}) and do not switch branches without being asked`;
-  writeFileSync(join(home, "TASK.md"), `# Instance briefing: ${instance}
+    return note;
+  };
+
+  try {
+    if (requiredFailures.length) {
+      const detail = requiredFailures.map((f) => `  ${f.capability} ${f.event} ${f.contract === "environment" ? "environment contract" : "hook (declared required)"}: ${f.message}`).join("\n");
+      const code = requiredFailures.some((f) => f.contract === "environment") ? "E_HOOK_ENVIRONMENT_CONTRACT" : "E_REQUIRED_HOOK_FAILED";
+      throw oatsError(code, `a capability this soul activates could not configure itself:\n${detail}\n\nThe instance would have started with an invalid or missing capability configuration`);
+    }
+    const briefLines = hookRes.briefs.length ? `\n${hookRes.briefs.join("\n")}` : "";
+    const workDesc = work === "worktree"
+      ? `a dedicated git worktree of ${repoAbs} on branch "${branch}" — commit freely there`
+      : work === "attached"
+      ? `ATTACHED to another instance's work tree (${o.workDir}, branch ${branch}) — you share it with that instance; make your changes and commits focused, and never switch branches`
+      : work === "workspace"
+      ? `the WHOLE WORKSPACE (${realpathSync(join(home, "work"))}) — every member repo is read-context; you coordinate, you do not edit member repos (see your work-mode briefing)`
+      : `a symlink to the ${repoAbs} checkout — you share it; work on the currently checked-out branch (${branch}) and do not switch branches without being asked`;
+    writeFileSync(join(home, "TASK.md"), `# Instance briefing: ${instance}
 
 You are instance "${instance}" of agent "${agent.name}".
 - Home: ${home}${resolvedCfg.team ? `\n- Team: ${resolvedCfg.team.name}${resolvedCfg.team.id ? ` (${resolvedCfg.team.id})` : ""} — see teammates with \`oats status --team\`` : ""}
 - Work tree: ./work — ${workDesc}
-- Do all repository work inside ./work. Read ./work/AGENTS.md or ./work/CLAUDE.md first if present.${briefLines}
+- Do all repository work inside ./work. Read ./work/AGENTS.md or ./work/CLAUDE.md first if present.${briefLines}${runtime === "codex" ? "\n## Runtime notification delivery\n\nNative Codex has no built-in messaging channel. Follow the explicit delivery briefing for this instance from your messaging capability, if present; it may arrange notification through this terminal. Shared channel instructions alone do not establish that delivery is configured. Without an instance delivery briefing, check your messaging capability's inbox and pending commands at task boundaries or when the operator asks; do not assume messages will wake this session.\n" : ""}
 ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spawn time — await instructions.\n"}`);
 
-  // Launch command. Spawn IS session start: this command is persisted in
-  // instance.json and executed in the instance's tmux window. Capabilities may
-  // contribute runtime-specific arguments via their spawn hook's `launch` map
-  // (e.g. aweb's Claude Code channel plugin flags).
-  const claudeBin = runtime === "claude" ? resolveClaudeBinary(repoAbs) : undefined;
-  const bin = which(runtime === "claude" ? claudeBin : "pi");
-  if (!bin) throw new Error(`${runtime === "claude" ? claudeBin : runtime} binary not found on PATH${claudeBin && claudeBin !== "claude" ? " (named by oats-claude-config)" : ""}`);
-  const hookArgs = hookRes.launch?.[runtime] ? ` ${hookRes.launch[runtime]}` : "";
-  let cmdline;
-  if (runtime === "claude") {
-    // .claude/skills already links the OATS-composed instance skill set.
-    // "--" terminates option parsing BEFORE the prompt: capability launch
-    // hooks can contribute greedy/variadic flags (e.g. aweb's
-    // --dangerously-load-development-channels), and without the separator
-    // the TASK.md text is swallowed as that flag's next value — claude
-    // errors out ("entries must be tagged: <task text>") and the window
-    // drops to the fallback shell, which reads as a silently stuck spawn.
-    cmdline = `${shq(bin)}${model ? ` --model ${shq(model)}` : ""}${hookArgs} -- "$(cat TASK.md)"`;
-  } else {
-    // STRICT CURRICULUM (pi): the OATS-composed set — no user, ancestor, project
-    // or package skill catalogs, and no auto-discovered AGENTS.md/CLAUDE.md.
-    // NOT "nothing else can contribute": extensions stay ambient by founder
-    // ruling (see below), and an extension's resources_discover hook can add
-    // skill paths that survive --no-skills. The OATS-managed root is exact; the
-    // extension surface is the operator's, and stating otherwise here would
-    // contradict the paragraph twelve lines down (reviewer-aggregate2).
-    //
-    //   --no-skills          ends discovery; --skill stays additive.
-    //   --no-context-files   stops ancestor AGENTS.md/CLAUDE.md auto-injection.
-    //                        It also stops the instance's OWN composed AGENTS.md
-    //                        loading, so that is delivered explicitly via
-    //                        --append-system-prompt. The work tree's AGENTS.md
-    //                        stays READABLE by the read tool: readable, not
-    //                        auto-injected, is the contract.
-    //   --no-prompt-templates  same posture for ambient prompt templates.
-    //
-    // Built-in tools and pi's native interaction model are untouched — OATS
-    // curates the curriculum, it does not cripple the runtime.
-    //
-    // EXTENSIONS STAY AMBIENT, by founder ruling: operators run cross-agent pi
-    // extensions (web search, output formatting) that every instance should
-    // keep. So no --no-extensions, and no -e flags either — pi discovers the
-    // installed extensions itself, and passing them explicitly as well would
-    // load the same extension twice.
-    //
-    // The trade-off is deliberate and narrow: an extension's
-    // `resources_discover` hook can contribute skill paths that survive
-    // --no-skills. Today only the OATS bridge does that, and inside an instance
-    // it contributes that instance's OWN .agents/skills, so the composed set is
-    // unchanged. A third-party extension that contributes skills WOULD add them,
-    // which is the accepted residue of keeping shared extensions working.
-    // Capability-required runtime packages are still verified and recorded
-    // (verifyRuntimePackages), so "aweb on pi requires the aweb pi package"
-    // still holds — it is loaded by pi's own discovery rather than by flag.
-    // pi has no `--` end-of-options marker (it rejects `--` in every position),
-    // so the task positional goes AHEAD of capability-contributed options:
-    // nothing preceding it is waiting for a value, so a trailing variadic
-    // contributed flag cannot consume the task.
-    cmdline = `${shq(bin)} --no-skills --skill ${shq(join(home, ".agents", "skills"))}`
-      + ` --no-context-files --no-prompt-templates`
-      + ` --append-system-prompt ${shq(join(home, "AGENTS.md"))}`
-      + ` --approve --name ${shq(instance)}${model ? ` --model ${shq(model)}` : ""} ${shq("@TASK.md")}${hookArgs}`;
-  }
-  // OATS_INSTANCE_HOME is the runtime-neutral contract name (absolute path to
-  // the instance home) exported to EVERY runtime. PI_AGENT_HOME/PI_AGENT_INSTANCE
-  // are pi-branded predecessors kept as compatibility aliases: the separately
-  // published @awebai/oats-pi extension and bin/oats.mjs still read them, and
-  // an older installed extension must keep working against a newer kernel.
-  const hookEnv = Object.keys(hookRes.env).sort().map((name) => `${name}=${shq(hookRes.env[name])}`).join(" ");
-  cmdline = `OATS_INSTANCE=${shq(instance)} OATS_INSTANCE_HOME=${shq(home)} PI_AGENT_INSTANCE=${shq(instance)} PI_AGENT_HOME=${shq(home)}${hookEnv ? ` ${hookEnv}` : ""} ${cmdline}`;
-
-  const meta = {
-    agent: agent.name, kind: agent.kind || "persistent", instance, home,
-    repo: repoAbs, work, branch, runtime, model: model || undefined,
-    team: resolvedCfg.team || undefined,
-    parentInstance: parentInstance && parentInstance !== instance ? parentInstance : undefined,
-    siblingInstance: siblingInstance && siblingInstance !== instance ? siblingInstance : undefined,
-    relation: relation || undefined,
-    relativeTo: relation ? relativeTo : undefined,
-    spawnOrigin: relation || (parentInstance && parentInstance !== instance) ? "instance" : "operator",
-    capabilityMeta: Object.keys(hookRes.meta).length ? hookRes.meta : undefined,
-    layers: Object.keys(resolvedCfg.provenance).length ? resolvedCfg.provenance : undefined,
-    capabilities: resolvedCfg.capabilities.map((cap) => ({
-      id: cap.id, layer: cap.layer, command: cap.command, origin: cap.origin, level: cap.level,
-      settings: cap.settings, provenance: cap.provenance, skills: cap.skills || [],
-      hooks: Object.keys(cap.hooks || {}), trusted: !!cap.trust?.trusted,
-      ...(cap.environment?.length ? { environment: [...cap.environment] } : {}),
-    })),
-    skills: [...chosen].sort(([a], [b]) => a.localeCompare(b)).map(([name, v]) => ({ name, source: v.source })),
-    instructions: composition.blocks.map((b) => ({ source: b.source, file: b.file })),
-    // The auditable record of the curriculum: what the resolved composition
-    // PROMISED, and what actually landed. Both are asserted equal before launch;
-    // keeping both makes an instance's surface reviewable after the fact without
-    // re-resolving config that may since have changed.
-    composition: {
-      expected: expectedResources.map((r) => ({ type: r.type, source: r.source, declared: r.declared, resolved: r.path, origin: r.origin, level: r.level })),
-      materialized: {
-        skills: materialized.map((m) => ({ name: m.name, source: m.source, from: m.from })),
-        instructions: composition.blocks.map((b) => ({ source: b.source, file: b.file })),
-        // `filtered` records that the operator's settings entry narrows this
-        // package's resources. A non-empty filter is a deliberate choice whose
-        // glob semantics belong to the runtime, so it is auditable here rather
-        // than second-guessed at spawn.
-        runtimePackages: runtimePackages.map((x) => ({ capability: x.capability, runtime: x.runtime, package: x.package, dir: x.dir, filtered: x.filtered, loadedBy: "runtime-discovery" })),
-        // What this instance ACTUALLY sees beyond the OATS-composed set. Recorded
-        // so the deviation from strict composition is auditable instead of
-        // implied — the honest contract, not an aspiration.
-        runtimePosture: runtime === "claude"
-          ? {
-            oatsComposed: "skills via .claude/skills -> ../.agents/skills; instructions via CLAUDE.md -> AGENTS.md",
-            ambient: ["user skills", "project and ancestor skills to the repository root", "user and project plugins", "user and project settings", "user and ancestor CLAUDE.md"],
-            why: "founder ruling: Claude Code's own global and per-repo configuration stays enabled — it is powerful, and the operator decides. An all-OATS setup is the way to opt out.",
-          }
-          : {
-            oatsComposed: "skills via --skill <instance-home>/.agents/skills; instructions via --append-system-prompt",
-            curtailed: ["user skills", "project and ancestor skills", "package skills", "ambient AGENTS.md/CLAUDE.md discovery", "ambient prompt templates"],
-            ambient: ["globally configured pi extensions, and any resources they contribute"],
-            why: "founder ruling: shared cross-agent pi extensions (web search, output formatting) stay available to every instance.",
-          },
-        canonicalSkillTree: join(home, ".agents", "skills"),
-        skillAlias: { path: join(home, ".claude", "skills"), target: join("..", ".agents", "skills") },
+    // Launch command. Spawn IS session start: this command is persisted in
+    // instance.json and executed in the instance's tmux window. Capabilities may
+    // contribute runtime-specific arguments via their spawn hook's `launch` map
+    // (e.g. aweb's Claude Code channel plugin flags).
+    const hookArgs = hookRes.launch?.[runtime] ? ` ${hookRes.launch[runtime]}` : "";
+    let cmdline;
+    if (runtime === "claude") {
+      // .claude/skills already links the OATS-composed instance skill set.
+      // "--" terminates option parsing BEFORE the prompt: capability launch
+      // hooks can contribute greedy/variadic flags (e.g. aweb's
+      // --dangerously-load-development-channels), and without the separator
+      // the TASK.md text is swallowed as that flag's next value — claude
+      // errors out ("entries must be tagged: <task text>") and the window
+      // drops to the fallback shell, which reads as a silently stuck spawn.
+      cmdline = `${shq(bin)}${yolo ? " --dangerously-skip-permissions" : ""}${model ? ` --model ${shq(model)}` : ""}${hookArgs} -- "$(cat TASK.md)"`;
+    } else if (runtime === "codex") {
+      // Codex discovers this home's AGENTS.md and .agents/skills natively.
+      // Keep the operator's native permission policy. --add-dir is not valid
+      // under every policy (including untrusted/read-only startup). Worktrees
+      // already live below home; external paths use native approval handling.
+      // --yolo bypasses execution approvals but Codex still asks to trust a new
+      // project. The operator's explicit yolo choice also trusts this generated
+      // home for this launch, without editing the shared user config.
+      const codexTrust = `projects={${JSON.stringify(realPathOrNearest(home))}={trust_level="trusted"}}`;
+      cmdline = `${shq(bin)} --cd ${shq(home)}${yolo ? ` --yolo -c ${shq(codexTrust)}` : ""}`
+        + `${model ? ` --model ${shq(model)}` : ""}${hookArgs} -- "$(cat TASK.md)"`;
+    } else {
+      // STRICT CURRICULUM (pi): the OATS-composed set — no user, ancestor, project
+      // or package skill catalogs, and no auto-discovered AGENTS.md/CLAUDE.md.
+      // NOT "nothing else can contribute": extensions stay ambient by founder
+      // ruling (see below), and an extension's resources_discover hook can add
+      // skill paths that survive --no-skills. The OATS-managed root is exact; the
+      // extension surface is the operator's, and stating otherwise here would
+      // contradict the paragraph twelve lines down (reviewer-aggregate2).
+      //
+      //   --no-skills          ends discovery; --skill stays additive.
+      //   --no-context-files   stops ancestor AGENTS.md/CLAUDE.md auto-injection.
+      //                        It also stops the instance's OWN composed AGENTS.md
+      //                        loading, so that is delivered explicitly via
+      //                        --append-system-prompt. The work tree's AGENTS.md
+      //                        stays READABLE by the read tool: readable, not
+      //                        auto-injected, is the contract.
+      //   --no-prompt-templates  same posture for ambient prompt templates.
+      //
+      // Built-in tools and pi's native interaction model are untouched — OATS
+      // curates the curriculum, it does not cripple the runtime.
+      //
+      // EXTENSIONS STAY AMBIENT, by founder ruling: operators run cross-agent pi
+      // extensions (web search, output formatting) that every instance should
+      // keep. So no --no-extensions, and no -e flags either — pi discovers the
+      // installed extensions itself, and passing them explicitly as well would
+      // load the same extension twice.
+      //
+      // The trade-off is deliberate and narrow: an extension's
+      // `resources_discover` hook can contribute skill paths that survive
+      // --no-skills. Today only the OATS bridge does that, and inside an instance
+      // it contributes that instance's OWN .agents/skills, so the composed set is
+      // unchanged. A third-party extension that contributes skills WOULD add them,
+      // which is the accepted residue of keeping shared extensions working.
+      // Capability-required runtime packages are still verified and recorded
+      // (verifyRuntimePackages), so "aweb on pi requires the aweb pi package"
+      // still holds — it is loaded by pi's own discovery rather than by flag.
+      // pi has no `--` end-of-options marker (it rejects `--` in every position),
+      // so the task positional goes AHEAD of capability-contributed options:
+      // nothing preceding it is waiting for a value, so a trailing variadic
+      // contributed flag cannot consume the task.
+      cmdline = `${shq(bin)} --no-skills --skill ${shq(join(home, ".agents", "skills"))}`
+        + ` --no-context-files --no-prompt-templates`
+        + ` --append-system-prompt ${shq(join(home, "AGENTS.md"))}`
+        + ` --approve --name ${shq(instance)}${model ? ` --model ${shq(model)}` : ""} ${shq("@TASK.md")}${hookArgs}`;
+    }
+    // OATS_INSTANCE_HOME is the runtime-neutral contract name (absolute path to
+    // the instance home) exported to EVERY runtime. PI_AGENT_HOME/PI_AGENT_INSTANCE
+    // are pi-branded predecessors kept as compatibility aliases: the separately
+    // published @awebai/oats-pi extension and bin/oats.mjs still read them, and
+    // an older installed extension must keep working against a newer kernel.
+    const hookEnv = Object.keys(hookRes.env).sort().map((name) => `${name}=${shq(hookRes.env[name])}`).join(" ");
+    cmdline = `OATS_INSTANCE=${shq(instance)} OATS_INSTANCE_HOME=${shq(home)} PI_AGENT_INSTANCE=${shq(instance)} PI_AGENT_HOME=${shq(home)}${hookEnv ? ` ${hookEnv}` : ""} ${cmdline}`;
+
+    const meta = {
+      agent: agent.name, kind: agent.kind || "persistent", instance, home,
+      repo: repoAbs, work, branch, runtime, model: model || undefined,
+      ...(yolo !== undefined ? { yolo } : {}),
+      team: resolvedCfg.team || undefined,
+      parentInstance: parentInstance && parentInstance !== instance ? parentInstance : undefined,
+      siblingInstance: siblingInstance && siblingInstance !== instance ? siblingInstance : undefined,
+      relation: relation || undefined,
+      relativeTo: relation ? relativeTo : undefined,
+      spawnOrigin: relation || (parentInstance && parentInstance !== instance) ? "instance" : "operator",
+      capabilityMeta: Object.keys(hookRes.meta).length ? hookRes.meta : undefined,
+      layers: Object.keys(resolvedCfg.provenance).length ? resolvedCfg.provenance : undefined,
+      capabilities: resolvedCfg.capabilities.map((cap) => ({
+        id: cap.id, layer: cap.layer, command: cap.command, origin: cap.origin, level: cap.level,
+        settings: cap.settings, provenance: cap.provenance, skills: cap.skills || [],
+        hooks: Object.keys(cap.hooks || {}), trusted: !!cap.trust?.trusted,
+        ...(cap.environment?.length ? { environment: [...cap.environment] } : {}),
+      })),
+      skills: [...chosen].sort(([a], [b]) => a.localeCompare(b)).map(([name, v]) => ({ name, source: v.source })),
+      instructions: composition.blocks.map((b) => ({ source: b.source, file: b.file })),
+      // The auditable record of the curriculum: what the resolved composition
+      // PROMISED, and what actually landed. Both are asserted equal before launch;
+      // keeping both makes an instance's surface reviewable after the fact without
+      // re-resolving config that may since have changed.
+      composition: {
+        expected: expectedResources.map((r) => ({ type: r.type, source: r.source, declared: r.declared, resolved: r.path, origin: r.origin, level: r.level })),
+        materialized: {
+          skills: materialized.map((m) => ({ name: m.name, source: m.source, from: m.from })),
+          instructions: composition.blocks.map((b) => ({ source: b.source, file: b.file })),
+          // `filtered` records that the operator's settings entry narrows this
+          // package's resources. A non-empty filter is a deliberate choice whose
+          // glob semantics belong to the runtime, so it is auditable here rather
+          // than second-guessed at spawn.
+          runtimePackages: runtimePackages.map((x) => ({ capability: x.capability, runtime: x.runtime, package: x.package, dir: x.dir, filtered: x.filtered, loadedBy: "runtime-discovery" })),
+          // What this instance ACTUALLY sees beyond the OATS-composed set. Recorded
+          // so the deviation from strict composition is auditable instead of
+          // implied — the honest contract, not an aspiration.
+          runtimePosture: runtime === "claude"
+            ? {
+              oatsComposed: "skills via .claude/skills -> ../.agents/skills; instructions via CLAUDE.md -> AGENTS.md",
+              ambient: ["user skills", "project and ancestor skills to the repository root", "user and project plugins", "user and project settings", "user and ancestor CLAUDE.md"],
+              why: "founder ruling: Claude Code's own global and per-repo configuration stays enabled — it is powerful, and the operator decides. An all-OATS setup is the way to opt out.",
+            }
+            : runtime === "codex" ? {
+              oatsComposed: "skills via .agents/skills; instructions via AGENTS.md; task via initial prompt",
+              ambient: ["user and ancestor instructions", "user, project, admin and system skills", "user and project configuration and MCP servers"],
+              why: yolo ? "Codex keeps native configuration with approval prompts and sandbox disabled by the OATS yolo setting." : "Codex keeps the operator's native configuration and approval policy, including approval handling for work paths outside the home.",
+            } : {
+              oatsComposed: "skills via --skill <instance-home>/.agents/skills; instructions via --append-system-prompt",
+              curtailed: ["user skills", "project and ancestor skills", "package skills", "ambient AGENTS.md/CLAUDE.md discovery", "ambient prompt templates"],
+              ambient: ["globally configured pi extensions, and any resources they contribute"],
+              why: "founder ruling: shared cross-agent pi extensions (web search, output formatting) stay available to every instance.",
+            },
+          canonicalSkillTree: join(home, ".agents", "skills"),
+          skillAlias: { path: join(home, ".claude", "skills"), target: join("..", ".agents", "skills") },
+        },
       },
-    },
-    capabilityRuntime: resolvedCfg.capabilities.map((cap) => ({
-      id: cap.id, layer: cap.layer, level: cap.level, settings: cap.settings,
-      hooks: cap.hooks, requiredHooks: cap.requiredHooks, environment: cap.environment,
-      missingRequires: cap.missingRequires, trust: cap.trust,
-      executable: cap.executable,
-    })),
-    tmux: { session, window: instance },
-    command: cmdline, createdAt: new Date().toISOString(),
-  };
-  const spawnWarnings = warnings;
-
-  let launched = false;
-  if (launch) {
-    if (!which("tmux")) throw new Error("tmux not installed (brew install tmux)");
-    if (!tmuxAlive(session)) {
-      const hq = existsSync(root) ? root : workspaceOf(root); // all-local scopes may have no agents/ dir
-      sh(`tmux new-session -d -s ${shq(session)} -n hq -c ${shq(hq)}`);
-      shTry(`tmux set-option -t ${shq(session)} -g window-size latest`);
-      shTry(`tmux set-option -t ${shq(session)} -g aggressive-resize on`);
-    }
-    if (tmuxWindows(session).includes(instance)) throw new Error(`tmux window "${instance}" already exists in session ${session}`);
-    meta.tmux.socket = tmuxSocket(session);
-    meta.launched = true;
-    // Commit the final child metadata and its independent byte authority before
-    // the managed runtime can write. No child-home transition follows launch.
-    writeFileSync(join(home, "instance.json"), JSON.stringify(meta, null, 2) + "\n");
-    writeRetirementBaseline(home, join(home, "work"), work === "worktree", wm, resolvedCfg.capabilities, { launched: true, tmux: meta.tmux });
-    // Wrap the command so the window drops into an interactive shell when the
-    // agent exits (e.g. Ctrl-C) instead of tmux killing the window.
-    const windowCmd = `${cmdline}; exec "\${SHELL:-/bin/zsh}"`;
-    sh(`tmux new-window -t ${shq(session)} -n ${shq(instance)} -c ${shq(home)} ${shq(windowCmd)}`);
-    launched = true;
-  } else {
-    meta.launched = false;
-    writeFileSync(join(home, "instance.json"), JSON.stringify(meta, null, 2) + "\n");
-    writeRetirementBaseline(home, join(home, "work"), work === "worktree", wm, resolvedCfg.capabilities, { launched: false, tmux: meta.tmux });
-  }
-
-  // parent relation: re-point the ANCHOR's recorded lineage so its parent is
-  // the new instance (e.g. a maintainer reviewing the spawner sits above it).
-  // Committed LAST — after every other fallible step incl. launch — so a
-  // failed spawn (missing tmux, window collision, new-window error) never
-  // leaves the anchor's graph pointing at a zombie. --no-launch reaches here
-  // too: the scaffold itself succeeded, which is that path's definition of
-  // success. The write ITSELF is fallible (anchor retired concurrently,
-  // unwritable file): on failure the spawn is COMPENSATED — kill the launched
-  // window and remove the scaffold — so the operation stays all-or-nothing:
-  // either agent live + lineage recorded, or neither.
-  if (relation === "parent" && anchorMeta && anchorMetaPath) {
-    // Atomic anchor update: writeFileSync truncates-then-writes, so a mid-write
-    // failure (ENOSPC, I/O) could leave the anchor's instance.json empty.
-    // Write a same-directory temp file and rename it over the anchor — rename
-    // is atomic on POSIX, so the anchor is always either old or new, never
-    // truncated.
-    const tmpPath = `${anchorMetaPath}.tmp-${instance}`;
-    try {
-      anchorMeta.parentInstance = instance;
-      delete anchorMeta.siblingInstance; // the new parent carries the old sibling link
-      writeFileSync(tmpPath, JSON.stringify(anchorMeta, null, 2) + "\n");
-      renameSync(tmpPath, anchorMetaPath);
-    } catch (e) {
-      // Compensation steps are each independent and best-effort: no step may
-      // abort the remaining rollback or mask the original anchor-write error
-      // (rmSync force:true only suppresses ENOENT — EPERM/IO still throw).
-      // Failures are COLLECTED and reported: the thrown message must never
-      // claim a cleanup that did not happen.
-      const incomplete = [];
-      // Verification probes are argv-based (no shell interpolation — branch
-      // names may contain valid-but-hostile metacharacters like $(…)) and
-      // THREE-STATE: confirmed-absent | still-present | could-not-verify.
-      // Both of the latter are reported — a failed probe must never pass as
-      // a confirmed cleanup (fail closed).
-      const probe = (argv) => {
-        try { return { ok: true, out: execFileSync(argv[0], argv.slice(1), { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }) }; }
-        // With encoding:"utf8" a silent command yields stderr === "" — FALSY — so
-          // `e2.stderr || e2.message` fell through to "Command failed: …" and made
-          // every clean probe look like a failed one. `git rev-parse --verify
-          // --quiet` on an absent ref is exactly that case, so a successful branch
-          // deletion could never be confirmed and rollback always reported
-          // INCOMPLETE. Distinguish "no output" from "no stderr captured".
-          catch (e2) { return { ok: false, status: e2.status, err: String(e2.stderr ?? e2.message ?? "").trim() }; }
-      };
-      let windowUnresolved = false;
-      try { rmSync(tmpPath, { force: true }); } catch (e2) { incomplete.push(`temp file ${tmpPath}: ${e2.message}`); }
-      if (launched) {
-        // shTry returns "" on success and undefined on failure — neither is a
-        // reliable signal for kill-window, so verify the EFFECT unconditionally.
-        shTry(`tmux kill-window -t ${shq(`=${session}:=${instance}`)}`);
-        const winProbe = probe(["tmux", "list-windows", "-t", session, "-F", "#{window_name}"]);
-        if (!winProbe.ok) { incomplete.push(`tmux window ${session}:${instance}: could not verify removal (${winProbe.err || "list-windows failed"})`); windowUnresolved = true; }
-        else if (winProbe.out.split("\n").includes(instance)) { incomplete.push(`tmux window ${session}:${instance} still running`); windowUnresolved = true; }
+      capabilityRuntime: resolvedCfg.capabilities.map((cap) => ({
+        id: cap.id, layer: cap.layer, level: cap.level, settings: cap.settings,
+        hooks: cap.hooks, requiredHooks: cap.requiredHooks, environment: cap.environment,
+        missingRequires: cap.missingRequires, trust: cap.trust,
+        executable: cap.executable,
+      })),
+      ...(backend === "herdr" ? { backend } : { tmux: { session, window: instance } }),
+      command: cmdline, createdAt: new Date().toISOString(),
+    };
+    const spawnWarnings = warnings;
+
+    spawnTmux = meta.tmux;
+    if (launch && backend === "herdr") {
+      windowMayExist = true;
+      spawnHerdr = allocateHerdr(herdrBase, { home, instance });
+      meta.sessionTarget = spawnHerdr;
+      meta.launched = true;
+      writeFileSync(join(home, "instance.json"), JSON.stringify(meta, null, 2) + "\n");
+      writeRetirementBaseline(home, join(home, "work"), work === "worktree", wm, resolvedCfg.capabilities, { launched: true, sessionTarget: spawnHerdr });
+      launchHerdr(spawnHerdr, cmdline);
+    } else if (launch) {
+      if (!tmuxAlive(session)) {
+        const hq = existsSync(root) ? root : workspaceOf(root); // all-local scopes may have no agents/ dir
+        sh(`tmux new-session -d -s ${shq(session)} -n hq -c ${shq(hq)}`);
+        shTry(`tmux set-option -t ${shq(session)} -g window-size latest`);
+        shTry(`tmux set-option -t ${shq(session)} -g aggressive-resize on`);
       }
-      // Outstanding debt as IDS, so a retry can verify it — same contract the
-      // required-hook rollback records.
-      const outstandingHooks = new Set();
-      const outstandingGit = new Set();
-      let compMeta = hookRes.meta || {};
+      if (tmuxWindows(session).includes(instance)) throw new Error(`tmux window "${instance}" already exists in session ${session}`);
+      meta.tmux.socket = tmuxSocket(session);
+      meta.launched = true;
+      // Commit the final child metadata and its independent byte authority before
+      // the managed runtime can write. No child-home transition follows launch.
+      writeFileSync(join(home, "instance.json"), JSON.stringify(meta, null, 2) + "\n");
+      writeRetirementBaseline(home, join(home, "work"), work === "worktree", wm, resolvedCfg.capabilities, { launched: true, tmux: meta.tmux });
+      // Wrap the command so the window drops into an interactive shell when the
+      // agent exits (e.g. Ctrl-C) instead of tmux killing the window.
+      const windowCmd = `${cmdline}; exec "\${SHELL:-/bin/zsh}"`;
+      windowMayExist = true;
+      sh(`tmux new-window -t ${shq(session)} -n ${shq(instance)} -c ${shq(home)} ${shq(windowCmd)}`);
+    } else {
+      meta.launched = false;
+      writeFileSync(join(home, "instance.json"), JSON.stringify(meta, null, 2) + "\n");
+      writeRetirementBaseline(home, join(home, "work"), work === "worktree", wm, resolvedCfg.capabilities, { launched: false, tmux: meta.tmux });
+    }
+
+    // parent relation: re-point the ANCHOR's recorded lineage so its parent is
+    // the new instance (e.g. a maintainer reviewing the spawner sits above it).
+    // Committed LAST — after every other fallible step incl. launch — so a
+    // failed spawn (missing tmux, window collision, new-window error) never
+    // leaves the anchor's graph pointing at a zombie. --no-launch reaches here
+    // too: the scaffold itself succeeded, which is that path's definition of
+    // success. The write ITSELF is fallible (anchor retired concurrently,
+    // unwritable file): on failure the spawn is COMPENSATED — kill the launched
+    // window and remove the scaffold — so the operation stays all-or-nothing:
+    // either agent live + lineage recorded, or neither.
+    if (relation === "parent" && anchorMeta && anchorMetaPath) {
+      // Atomic anchor update: writeFileSync truncates-then-writes, so a mid-write
+      // failure (ENOSPC, I/O) could leave the anchor's instance.json empty.
+      // Write a same-directory temp file and rename it over the anchor — rename
+      // is atomic on POSIX, so the anchor is always either old or new, never
+      // truncated.
+      const tmpPath = `${anchorMetaPath}.tmp-${instance}`;
       try {
-        const comp = runLifecycleHooks("retire", {
-          home, instance, agentName: agent.name, soulDir, contextDir: repoAbs,
-          workspaceDir: workspaceOf(root), rootDir: root, resolved: resolvedCfg,
-          priorMeta: hookRes.meta || {},
-        });
-        // runLifecycleHooks catches hook errors internally — detect them via
-        // the structured failures field, not this outer catch.
-        for (const f of comp.failures || []) { incomplete.push(`retire hook ${f.capability}: ${f.message}`); outstandingHooks.add(f.capability); }
-        // Exit 0 while reporting "not retired" is also unfinished cleanup.
-        for (const [capId, m] of Object.entries(comp.meta || {})) {
-          if (m && typeof m === "object" && m.retired === false && m.reason !== "nothing-to-delete") {
-            incomplete.push(`retire hook ${capId}: reported incomplete cleanup${m.reason ? ` (${m.reason})` : ""} — external state may remain`);
-            outstandingHooks.add(capId);
-          }
-        }
-        compMeta = { ...compMeta, ...(comp.meta || {}) };
-      } catch (e2) {
-        incomplete.push(`retire hooks: ${e2.message}`);
-        for (const cap of resolvedCfg.capabilities) if (cap.hooks?.retire) outstandingHooks.add(cap.id);
-      }
-      if (work === "worktree") {
-        const wt = join(home, "work");
-        // Git canonicalizes symlinked parent components when registering a
-        // worktree. Use the path captured immediately after successful add —
-        // retire-hook compensation may already have removed/inaccessible'd wt.
-        const wtCanonical = worktreeCanonical;
-        if (!wtCanonical) incomplete.push(`git worktree ${wt}: could not verify removal (canonical path unavailable)`);
-        probe(["git", "-C", repoAbs, "worktree", "remove", "--force", wt]);
-        probe(["git", "-C", repoAbs, "worktree", "prune"]);
-        // Verify effects, not exit codes: parse exact NUL-delimited `worktree`
-        // records (never substring-match a lexical path against Git's canonical
-        // registered path). The tree must be deregistered or later rmSync(home)
-        // strands stale Git metadata.
-        const wtProbe = probe(["git", "-C", repoAbs, "worktree", "list", "--porcelain", "-z"]);
-        if (!wtProbe.ok) { incomplete.push(`git worktree ${wtCanonical}: could not verify removal (${wtProbe.err || "worktree list failed"})`); outstandingGit.add("worktree"); }
-        else {
-          const registered = wtProbe.out.split("\0").filter((field) => field.startsWith("worktree ")).map((field) => field.slice("worktree ".length));
-          if (wtCanonical && registered.includes(wtCanonical)) { incomplete.push(`git worktree ${wtCanonical}: still registered`); outstandingGit.add("worktree"); }
-        }
-        if (branch) {
-          probe(["git", "-C", repoAbs, "branch", "-D", branch]);
-          // rev-parse --verify: exit 0 = ref exists; exit 1 with empty stderr
-          // under --quiet = confirmed absent; anything else = could not verify.
-          const brProbe = probe(["git", "-C", repoAbs, "rev-parse", "--verify", "--quiet", `refs/heads/${branch}`]);
-          if (brProbe.ok) { incomplete.push(`git branch ${branch}: still exists`); outstandingGit.add("branch"); }
-          else if (brProbe.status !== 1 || brProbe.err) { incomplete.push(`git branch ${branch}: could not verify deletion (${brProbe.err || `rev-parse exit ${brProbe.status}`})`); outstandingGit.add("branch"); }
-        }
-      }
-      // QUARANTINE, do not delete. This path deleted the home unconditionally —
-      // including while its own retire hook was reporting failure — which is
-      // exactly the credential destruction the required-hook path was fixed to
-      // avoid (reviewer-terminal54a87fd). A quarantine with nothing outstanding
-      // would be a proof obligation of zero, so the record is filled
-      // conservatively when both categories somehow came up empty.
-      // Quarantine only for state that COMPENSATION owns and did not finish: a
-      // retire hook that failed, Git the rollback could not undo, or a window
-      // still running. Litter beside the anchor (a leftover temp file) is
-      // reported but is not the child's external state, and retaining a home
-      // for it would turn an ordinary failure into a --force cleanup.
-      const unresolved = outstandingHooks.size > 0 || outstandingGit.size > 0 || windowUnresolved;
-      let rollbackNote;
-      if (unresolved) {
-        if (!outstandingHooks.size && !outstandingGit.size) {
-          for (const cap of resolvedCfg.capabilities) if (cap.hooks?.retire) outstandingHooks.add(cap.id);
-        }
-        rollbackNote = quarantineInstanceHome({
-          home, instance, agent, incomplete,
-          failed: [{ capability: "oats.kernel", event: "spawn" }],
-          outstandingHooks, outstandingGit, repoAbs, work, branch, resolvedCfg,
-          // The SPAWN metadata — the aweb alias a retry needs to delete the
-          // remote identity. Passing the compensation result overwrote it with
-          // `{retired:false}`, discarding the very handle cleanup requires.
-          hookMeta: hookRes.meta || {}, compensationMeta: compMeta,
-          launched: windowUnresolved, tmux: meta.tmux,
-          recordRetirementBaseline: true,
-        }).replace(/^ — /, "");
-      } else {
-        try { rmSync(home, { recursive: true, force: true }); } catch (e2) { incomplete.push(`instance home ${home}: ${e2.message}`); }
-        if (existsSync(home) && !incomplete.some((m) => m.startsWith("instance home"))) incomplete.push(`instance home ${home}: still present`);
-        rollbackNote = incomplete.length
-          ? `rollback INCOMPLETE — clean up manually: ${incomplete.join("; ")}`
-          : "spawn rolled back (window killed, hooks compensated, scaffold removed)";
+        anchorMeta.parentInstance = instance;
+        delete anchorMeta.siblingInstance; // the new parent carries the old sibling link
+        writeFileSync(tmpPath, JSON.stringify(anchorMeta, null, 2) + "\n");
+        renameSync(tmpPath, anchorMetaPath);
+      } catch (e) {
+        try { rmSync(tmpPath, { force: true }); }
+        catch (cleanupError) { ancillaryCleanup.push(`temp file ${tmpPath}: ${cleanupError.message}`); }
+        throw new Error(`relation "parent": failed to re-point anchor "${relativeTo}" (${e.message})`);
       }
-      throw new Error(`relation "parent": failed to re-point anchor "${relativeTo}" (${e.message}) — ${rollbackNote}`);
     }
-  }
 
-  return { ...meta, attach: `tmux attach -t ${session}`, warnings: spawnWarnings.length ? spawnWarnings : undefined };
+    return { ...meta, attach: spawnHerdr ? `HERDR_SOCKET_PATH=${shq(spawnHerdr.socket)} ${shq(spawnHerdr.binary)} terminal attach ${shq(spawnHerdr.terminalId)}` : backend === "herdr" ? "not launched" : `tmux attach -t ${session}`, warnings: spawnWarnings.length ? spawnWarnings : undefined };
+  } catch (error) {
+    const note = compensateSpawn();
+    error.message += note;
+    throw error;
+  }
 }
 
 export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION) {
   const windows = tmuxWindows(tmuxSession);
   const readInstancesOf = (agentDir) => {
     const instancesDir = join(agentDir, "instances");
+    // An instance name starts with a letter or digit (INSTANCE_NAME_RE); a
+    // dot-directory under instances/ is kernel bookkeeping (.oats-retirement
+    // holds baselines and recoveries), never a home (oats-5xl).
     return (existsSync(instancesDir) ? readdirSync(instancesDir, { withFileTypes: true }) : [])
-      .filter((e) => e.isDirectory())
+      .filter((e) => e.isDirectory() && !e.name.startsWith("."))
       .map((e) => {
         const metaPath = join(instancesDir, e.name, "instance.json");
         const home = join(instancesDir, e.name);
@@ -5975,12 +5948,47 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION) {
           try { rollbackIncomplete = JSON.parse(readFileSync(quarantine, "utf8")); }
           catch { rollbackIncomplete = { reason: "rollback incomplete" }; }
         }
-        return { ...meta, running: windows.includes(meta.instance || e.name), ...(rollbackIncomplete ? { rollbackIncomplete } : {}) };
+        // A self-retire that has been requested but not completed: the home is
+        // owed a retirement, not live work. Read-only here — completion is the
+        // detached child's or an operator's `oats retire`, never status.
+        const pending = retirePendingMarkerPath(home);
+        let retirePending;
+        if (existsSync(pending)) {
+          try { retirePending = JSON.parse(readFileSync(pending, "utf8")); }
+          catch { retirePending = { reason: "retire pending" }; }
+        }
+        let liveness = { running: windows.includes(meta.instance || e.name) };
+        if (meta.sessionTarget) {
+          try { const state = inspectHerdr({ ...meta.sessionTarget, binary: "herdr" }); liveness = { running: state.present, runtimeState: state.status }; }
+          catch (error) { liveness = { running: null, runtimeState: "unreachable", runtimeError: error.message }; }
+        }
+        return { ...meta, ...liveness, ...(rollbackIncomplete ? { rollbackIncomplete } : {}), ...(retirePending ? { retirePending } : {}) };
+
       });
   };
+  // Failed deferred self-retirements leave their outcome beside the home; a
+  // successful one is evidence only and is not a problem to surface.
+  const readRetireFailuresOf = (agentDir) => {
+    const instancesDir = join(agentDir, "instances");
+    if (!existsSync(instancesDir)) return [];
+    const out = [];
+    for (const e of readdirSync(instancesDir, { withFileTypes: true })) {
+      const m = e.isFile() && /^\.oats-retired-(.+)\.json$/.exec(e.name);
+      if (!m) continue;
+      try {
+        const r = JSON.parse(readFileSync(join(instancesDir, e.name), "utf8"));
+        if (r.ok === false) out.push({ instance: m[1], completedAt: r.completedAt, error: r.error?.message, incomplete: r.result?.rollbackIncomplete, retry: r.retry, resultPath: join(instancesDir, e.name) });
+      } catch { out.push({ instance: m[1], error: "unreadable result file", resultPath: join(instancesDir, e.name) }); }
+    }
+    return out;
+  };
+  const withFailures = (entry, agentDir) => {
+    const retireFailures = readRetireFailuresOf(agentDir);
+    return retireFailures.length ? { ...entry, retireFailures } : entry;
+  };
   const out = listAgents(root).map((a) => {
     const { _dir, ...soul } = a;
-    return { ...soul, dir: _dir, instances: readInstancesOf(a._dir) };
+    return withFailures({ ...soul, dir: _dir, instances: readInstancesOf(a._dir) }, a._dir);
   });
   // Capability-defined agents home under local-agents/<name>/ WITHOUT a local
   // soul (it lives read-only in the package) — surface their instances too.
@@ -5990,9 +5998,10 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION) {
     for (const e of readdirSync(dir, { withFileTypes: true })) {
       if (!e.isDirectory() || seen.has(e.name)) continue;
       const instances = readInstancesOf(join(dir, e.name));
-      if (!instances.length) continue;
+      const retireFailures = readRetireFailuresOf(join(dir, e.name));
+      if (!instances.length && !retireFailures.length) continue;
       const cap = instances.find((i) => i.capability)?.capability;
-      out.push({ name: e.name, kind: "capability", capability: cap, description: cap ? `capability agent (${cap})` : "capability agent", dir: join(dir, e.name), instances });
+      out.push({ name: e.name, kind: "capability", capability: cap, description: cap ? `capability agent (${cap})` : "capability agent", dir: join(dir, e.name), instances, ...(retireFailures.length ? { retireFailures } : {}) });
       seen.add(e.name);
     }
   }
@@ -6068,14 +6077,9 @@ export const QUARANTINE_CLEANUP_VERSION = 1;
 /** The rollback-owned Git steps a quarantine can still owe. */
 export const QUARANTINE_GIT_DEBT = ["worktree", "branch"];
 
-/** Retain a half-built instance home and mark it, so `oats retire <instance>` can
- * finish the cleanup that failed. THE one implementation: a spawn has two
- * rollback paths — a failed required hook, and a failure after the instance was
- * already launched (re-pointing a parent anchor) — and the second one deleted the
- * home while its own retire hook was reporting failure, destroying the credential
- * needed to undo the external state that survived (reviewer-terminal54a87fd).
- * Two copies of this logic is how that divergence happened; there is now one. */
-function quarantineInstanceHome({ home, instance, agent, incomplete, failed, outstandingHooks, outstandingGit, repoAbs, work, branch, resolvedCfg, hookMeta, compensationMeta, launched, tmux, recordRetirementBaseline = false, reason }) {
+/** Retain the home and its cleanup receipt when spawn compensation or retirement
+ * cannot finish. Keeping the original credentials makes cleanup retryable. */
+function quarantineInstanceHome({ home, instance, agent, incomplete, failed, outstandingHooks, outstandingGit, repoAbs, work, branch, resolvedCfg, hookMeta, compensationMeta, launched, tmux, sessionTarget, recordRetirementBaseline = false, reason }) {
   try {
     writeFileSync(join(home, ".oats-rollback-incomplete.json"), JSON.stringify({
       // `reason` is optional and DEFAULTS to the spawn wording, so every existing
@@ -6091,6 +6095,7 @@ function quarantineInstanceHome({ home, instance, agent, incomplete, failed, out
       cleanup: {
         version: QUARANTINE_CLEANUP_VERSION,
         repo: repoAbs, work, branch, launched, tmux,
+        ...(sessionTarget ? { sessionTarget } : {}),
         outstanding: { hooks: [...outstandingHooks], git: [...outstandingGit] },
         capabilityRuntime: (resolvedCfg.capabilities || []).map((cap) => ({
           id: cap.id, layer: cap.layer, level: cap.level, settings: cap.settings,
@@ -6105,7 +6110,7 @@ function quarantineInstanceHome({ home, instance, agent, incomplete, failed, out
   } catch { /* the quarantine still stands without its marker */ }
   if (recordRetirementBaseline) {
     try {
-      writeRetirementBaseline(home, join(home, "work"), work === "worktree", resolveWorkMode(repoAbs, work), resolvedCfg.capabilities || [], { launched: launched === true, tmux });
+      writeRetirementBaseline(home, join(home, "work"), work === "worktree", resolveWorkMode(repoAbs, work), resolvedCfg.capabilities || [], { launched: launched === true, tmux, sessionTarget });
     } catch (e) {
       incomplete.push(`independent retirement authority: ${e.message}`);
     }
@@ -6179,6 +6184,15 @@ function retirementBaselinePath(home) {
   return join(retirementStateRoot(home), "baselines", `${retirementKey(home)}.json`);
 }
 
+/** git's output for a large tree (status with untracked and ignored files,
+ *  the index listing, a large blob) easily exceeds Node's 1 MiB default child
+ *  buffer; the spawn then dies with ENOBUFS and retirement reports the
+ *  recovery as unverifiable (cjr, ~9500 tracked long paths). Every git call
+ *  on the retirement path gets this bound instead. It raises the practical
+ *  limit, it does not remove it: a single blob over 512 MiB would still fail,
+ *  loudly, and streaming is deliberately not attempted in this change. */
+const GIT_MAX_BUFFER = 512 * 1024 * 1024;
+
 function fingerprintTree(root, { excludeRoot = new Set(), excludeGitMetadata = false } = {}) {
   const hash = createHash("sha256");
   const rootStat = lstatSync(root);
@@ -6208,7 +6222,7 @@ function fingerprintTree(root, { excludeRoot = new Set(), excludeGitMetadata = f
 
 function worktreeStatus(repo) {
   try {
-    return execFileSync("git", ["-C", repo, "status", "--porcelain=v1", "-z", "--untracked-files=all", "--ignored=matching", "--ignore-submodules=none"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+    return execFileSync("git", ["-C", repo, "status", "--porcelain=v1", "-z", "--untracked-files=all", "--ignored=matching", "--ignore-submodules=none"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] , maxBuffer: GIT_MAX_BUFFER });
   } catch (e) {
     throw oatsError("E_WORK_INSPECTION_FAILED", `could not inspect instance worktree: ${String(e.stderr ?? e.message ?? "").trim() || "git status failed"}`);
   }
@@ -6259,6 +6273,7 @@ function writeRetirementBaseline(home, work, isWorktree, workMode, capabilities,
     runtime: {
       launched: runtime?.launched === true,
       ...(runtime?.tmux ? { tmux: { session: runtime.tmux.session, window: runtime.tmux.window, ...(runtime.tmux.socket ? { socket: resolve(runtime.tmux.socket) } : {}) } } : {}),
+      ...(runtime?.sessionTarget ? { sessionTarget: runtime.sessionTarget } : {}),
     },
   };
   const path = retirementBaselinePath(home);
@@ -6284,7 +6299,7 @@ function branchOnlyCommits(repo, branch) {
   if (!repo || !branch) return [];
   const target = `refs/heads/${branch}`;
   try {
-    execFileSync("git", ["-C", repo, "rev-parse", "--verify", "--quiet", target], { stdio: ["ignore", "pipe", "pipe"] });
+    execFileSync("git", ["-C", repo, "rev-parse", "--verify", "--quiet", target], { stdio: ["ignore", "pipe", "pipe"] , maxBuffer: GIT_MAX_BUFFER });
   } catch (e) {
     const detail = String(e.stderr ?? "").trim();
     // A quarantine retry may follow a successful rollback-owned branch removal.
@@ -6293,9 +6308,9 @@ function branchOnlyCommits(repo, branch) {
     throw oatsError("E_WORK_INSPECTION_FAILED", `could not inspect local branch reachability: ${detail || String(e.message ?? "").trim() || "git ref probe failed"}`);
   }
   try {
-    const refs = execFileSync("git", ["-C", repo, "for-each-ref", "--format=%(refname)"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] })
+    const refs = execFileSync("git", ["-C", repo, "for-each-ref", "--format=%(refname)"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] , maxBuffer: GIT_MAX_BUFFER })
       .split("\n").filter((ref) => ref && ref !== target);
-    return execFileSync("git", ["-C", repo, "rev-list", target, ...(refs.length ? ["--not", ...refs] : [])], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim().split("\n").filter(Boolean);
+    return execFileSync("git", ["-C", repo, "rev-list", target, ...(refs.length ? ["--not", ...refs] : [])], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER }).trim().split("\n").filter(Boolean);
   } catch (e) {
     throw oatsError("E_WORK_INSPECTION_FAILED", `could not inspect local branch reachability: ${String(e.stderr ?? e.message ?? "").trim() || "git ref probe failed"}`);
   }
@@ -6305,11 +6320,55 @@ function runtimeAuthorityOf(baseline) {
   const runtime = baseline?.runtime;
   if (!isPlainObject(runtime) || typeof runtime.launched !== "boolean") return undefined;
   if (!runtime.launched) return { launched: false };
+  if (runtime.sessionTarget !== undefined) {
+    if (runtime.tmux || !validHerdrTarget(runtime.sessionTarget)) return undefined;
+    return { launched: true, sessionTarget: runtime.sessionTarget };
+  }
   const tmux = runtime.tmux;
   if (!isPlainObject(tmux) || ![tmux.session, tmux.window, tmux.socket].every((v) => typeof v === "string" && v.length > 0)) return undefined;
   return { launched: true, tmux: { session: tmux.session, window: tmux.window, socket: resolve(tmux.socket) } };
 }
 
+/** Session control uses the same independent endpoint receipt as retirement. */
+function instanceSessionTarget(home) {
+  if (typeof home !== "string" || !isAbsolute(home)) throw oatsError("E_BAD_ARGS", "session needs an absolute instance home");
+  home = realPathOrNearest(home);
+  let baseline, meta;
+  try {
+    baseline = JSON.parse(readFileSync(retirementBaselinePath(home), "utf8"));
+    meta = JSON.parse(readFileSync(join(home, "instance.json"), "utf8"));
+  } catch (e) { throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `cannot read session receipt for ${home}: ${e.message}`); }
+  const authority = baseline.version === RETIRE_BASELINE_VERSION && baseline.home === home && runtimeAuthorityOf(baseline);
+  if (!authority) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `independent session receipt is missing or invalid for ${home}`);
+  const endpointAgrees = authority.sessionTarget
+    ? !meta.tmux && ["backend", "binary", "socket", "workspaceId", "paneId", "terminalId", "protocol"].every((key) => meta.sessionTarget?.[key] === authority.sessionTarget[key])
+    : !meta.sessionTarget && meta.tmux?.session === authority.tmux?.session && meta.tmux?.window === authority.tmux?.window && resolve(meta.tmux?.socket || ".") === authority.tmux?.socket;
+  if (meta.launched !== authority.launched || (authority.launched && !endpointAgrees)) throw oatsError("E_RUNTIME_AUTHORITY_MISMATCH", "instance metadata disagrees with independent session receipt");
+  return { home, target: authority.launched ? authority.sessionTarget || { backend: "tmux", ...authority.tmux } : undefined };
+}
+
+export function inspectInstanceSession(home) {
+  if (typeof home === "string" && isAbsolute(home) && !existsSync(home)) return { home: realPathOrNearest(home), backend: null, present: false, state: "stopped" };
+  const s = instanceSessionTarget(home);
+  if (!s.target) return { home: s.home, backend: null, present: false, state: "not-launched" };
+  try { return { home: s.home, ...inspectSessionTarget(s.target) }; }
+  catch (e) { throw oatsError("E_SESSION_UNAVAILABLE", `cannot inspect session: ${e.message}`); }
+}
+
+export async function attachInstanceSession(home) {
+  const s = instanceSessionTarget(home);
+  if (!s.target) throw oatsError("E_SESSION_NOT_RUNNING", "instance was not launched");
+  return attachSessionTarget(s.target);
+}
+
+export function inputInstanceSession(home, text) {
+  if (typeof text !== "string" || !text.trim() || text.includes("\0") || Buffer.byteLength(text) > 256 * 1024) throw oatsError("E_BAD_ARGS", "session input must be nonempty text without NUL, at most 256 KiB");
+  const s = instanceSessionTarget(home);
+  if (!s.target) throw oatsError("E_SESSION_NOT_RUNNING", "instance was not launched");
+  try { return { home: s.home, ...inputSessionTarget(s.target, text) }; }
+  catch (e) { throw oatsError("E_SESSION_INPUT_FAILED", `cannot submit session input: ${e.message}`); }
+}
+
 function inspectRetirementWork(home, work, isWorktree, { branchDeletion } = {}) {
   const classes = [];
   let baseline;
@@ -6356,14 +6415,14 @@ const RECOVERABLE_GIT_ADMIN = [
 ];
 
 function restoreStandaloneGitState(sourceWork, recoveredRepo) {
-  const sourceGit = execFileSync("git", ["-C", sourceWork, "rev-parse", "--absolute-git-dir"], { encoding: "utf8" }).trim();
+  const sourceGit = execFileSync("git", ["-C", sourceWork, "rev-parse", "--absolute-git-dir"], { encoding: "utf8" , maxBuffer: GIT_MAX_BUFFER }).trim();
   const recoveredGit = join(recoveredRepo, ".git");
-  const indexRows = execFileSync("git", ["-C", sourceWork, "ls-files", "--stage", "-z"]);
+  const indexRows = execFileSync("git", ["-C", sourceWork, "ls-files", "--stage", "-z"], { maxBuffer: GIT_MAX_BUFFER });
   for (const row of indexRows.toString("utf8").split("\0").filter(Boolean)) {
     const match = row.match(/^\d+ ([0-9a-f]+) \d+\t/);
     if (!match) continue;
-    const blob = execFileSync("git", ["-C", sourceWork, "cat-file", "blob", match[1]]);
-    const restored = execFileSync("git", ["-C", recoveredRepo, "hash-object", "-w", "--stdin"], { input: blob, encoding: "utf8" }).trim();
+    const blob = execFileSync("git", ["-C", sourceWork, "cat-file", "blob", match[1]], { maxBuffer: GIT_MAX_BUFFER });
+    const restored = execFileSync("git", ["-C", recoveredRepo, "hash-object", "-w", "--stdin"], { input: blob, encoding: "utf8" , maxBuffer: GIT_MAX_BUFFER }).trim();
     if (restored !== match[1]) throw new Error(`recovered Git object ${restored} did not match source ${match[1]}`);
   }
   copyFileSync(join(sourceGit, "index"), join(recoveredGit, "index"));
@@ -6378,11 +6437,11 @@ function restoreStandaloneGitState(sourceWork, recoveredRepo) {
 
 function detachRecoveryClone(source, recovered) {
   let stash;
-  try { stash = execFileSync("git", ["-C", source, "rev-parse", "--verify", "--quiet", "refs/stash"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim(); }
+  try { stash = execFileSync("git", ["-C", source, "rev-parse", "--verify", "--quiet", "refs/stash"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] , maxBuffer: GIT_MAX_BUFFER }).trim(); }
   catch { stash = undefined; }
   if (stash) {
-    execFileSync("git", ["-C", recovered, "fetch", "--quiet", source, "refs/stash:refs/stash"]);
-    const sourceCommon = execFileSync("git", ["-C", source, "rev-parse", "--path-format=absolute", "--git-common-dir"], { encoding: "utf8" }).trim();
+    execFileSync("git", ["-C", recovered, "fetch", "--quiet", source, "refs/stash:refs/stash"], { maxBuffer: GIT_MAX_BUFFER });
+    const sourceCommon = execFileSync("git", ["-C", source, "rev-parse", "--path-format=absolute", "--git-common-dir"], { encoding: "utf8" , maxBuffer: GIT_MAX_BUFFER }).trim();
     const stashLog = join(sourceCommon, "logs", "refs", "stash");
     if (existsSync(stashLog)) {
       const recoveredLog = join(recovered, ".git", "logs", "refs", "stash");
@@ -6390,17 +6449,17 @@ function detachRecoveryClone(source, recovered) {
       copyFileSync(stashLog, recoveredLog);
     }
   }
-  try { execFileSync("git", ["-C", recovered, "remote", "remove", "origin"], { stdio: "ignore" }); } catch { /* no remote is already independent */ }
+  try { execFileSync("git", ["-C", recovered, "remote", "remove", "origin"], { stdio: "ignore" , maxBuffer: GIT_MAX_BUFFER }); } catch { /* no remote is already independent */ }
 }
 
 function materializeNestedRepositories(sourceWork, recoveredRepo) {
   for (const source of nestedGitRoots(sourceWork)) {
     const rel = relative(sourceWork, source);
     const dest = join(recoveredRepo, rel);
-    const head = execFileSync("git", ["-C", source, "rev-parse", "HEAD"], { encoding: "utf8" }).trim();
+    const head = execFileSync("git", ["-C", source, "rev-parse", "HEAD"], { encoding: "utf8" , maxBuffer: GIT_MAX_BUFFER }).trim();
     rmSync(dest, { recursive: true, force: true });
-    execFileSync("git", ["clone", "--no-local", "--quiet", source, dest], { stdio: ["ignore", "pipe", "pipe"] });
-    execFileSync("git", ["-C", dest, "checkout", "--quiet", head]);
+    execFileSync("git", ["clone", "--no-local", "--quiet", source, dest], { stdio: ["ignore", "pipe", "pipe"] , maxBuffer: GIT_MAX_BUFFER });
+    execFileSync("git", ["-C", dest, "checkout", "--quiet", head], { maxBuffer: GIT_MAX_BUFFER });
     detachRecoveryClone(source, dest);
     restoreStandaloneGitState(source, dest);
     for (const e of readdirSync(source, { withFileTypes: true })) {
@@ -6427,7 +6486,7 @@ function preserveRetirementWork(observation, meta, instance) {
     }
     if (meta.work === "worktree" && meta.repo && meta.branch && (existsSync(observation.work) || observation.branchExists)) {
       const recoveredRepo = join(staging, "repo");
-      execFileSync("git", ["clone", "--no-local", "--quiet", "--branch", meta.branch, meta.repo, recoveredRepo], { stdio: ["ignore", "pipe", "pipe"] });
+      execFileSync("git", ["clone", "--no-local", "--quiet", "--branch", meta.branch, meta.repo, recoveredRepo], { stdio: ["ignore", "pipe", "pipe"] , maxBuffer: GIT_MAX_BUFFER });
       const sourceGitContext = existsSync(observation.work) ? observation.work : meta.repo;
       detachRecoveryClone(sourceGitContext, recoveredRepo);
       if (existsSync(observation.work)) {
@@ -6445,8 +6504,8 @@ function preserveRetirementWork(observation, meta, instance) {
         if (fingerprintTree(observation.work, { excludeRoot: new Set([".git"]), excludeGitMetadata: true }) !== fingerprintTree(recoveredRepo, { excludeRoot: new Set([".git"]), excludeGitMetadata: true })) throw new Error("worktree recovery verification disagreed with the source");
         if (worktreeStatus(observation.work) !== worktreeStatus(recoveredRepo)) throw new Error("recovered Git index/status disagreed with the source");
       }
-      const recoveredHead = execFileSync("git", ["-C", recoveredRepo, "rev-parse", "HEAD"], { encoding: "utf8" }).trim();
-      const sourceHead = execFileSync("git", ["-C", meta.repo, "rev-parse", `refs/heads/${meta.branch}`], { encoding: "utf8" }).trim();
+      const recoveredHead = execFileSync("git", ["-C", recoveredRepo, "rev-parse", "HEAD"], { encoding: "utf8" , maxBuffer: GIT_MAX_BUFFER }).trim();
+      const sourceHead = execFileSync("git", ["-C", meta.repo, "rev-parse", `refs/heads/${meta.branch}`], { encoding: "utf8" , maxBuffer: GIT_MAX_BUFFER }).trim();
       if (recoveredHead !== sourceHead) throw new Error("recovery clone does not retain the instance branch tip");
     }
     writeFileSync(join(staging, "recovery.json"), JSON.stringify({ version: 1, instance, classes: observation.classes, sourceHome: observation.home, createdAt: new Date().toISOString() }, null, 2) + "\n", { mode: 0o600 });
@@ -6459,9 +6518,143 @@ function preserveRetirementWork(observation, meta, instance) {
   }
 }
 
+/** Marker a self-retiring instance leaves BESIDE its home: the retirement is
+ *  requested and owed, and a detached completion is on its way. It is not
+ *  written into the home, so the caller changes no instance bytes and the
+ *  completion's work inspection sees exactly what the instance left. */
+export function retirePendingMarkerPath(home) {
+  return join(dirname(home), `.oats-retire-pending-${basename(home)}.json`);
+}
+
+/** Where a deferred self-retirement writes its explicit outcome: a FILE beside
+ *  the (former) home, so it survives the home's removal and never reads as an
+ *  instance directory. */
+export function deferredRetireResultPath(home) {
+  return join(dirname(home), `.oats-retired-${basename(home)}.json`);
+}
+
+const DEFERRED_RETIRE_SCRIPT = `import { completeDeferredRetirement } from ${JSON.stringify(import.meta.url)};
+process.exitCode = completeDeferredRetirement(JSON.parse(process.env.OATS_RETIRE_INTENT)) ? 0 : 1;`;
+
+/** Self-retire (aweb-abep): persist intent, then hand the retirement to a
+ *  detached process that runs it as an ORDINARY external retirement after the
+ *  caller's window has died. Nothing destructive happens in the caller: no
+ *  inspection, no hooks, no removal — the runtime is still alive, and the
+ *  quiesce rule stays intact. The child owns its own process group so the
+ *  tmux window kill (SIGHUP to the pane's group) cannot take it down, and the
+ *  caller's instance env is stripped so the child is an external operator,
+ *  not another self-retire. The intent travels to the child in its env; the
+ *  marker beside the home is the operator-visible promise and is written only
+ *  once a completion process exists (reviewer D2). */
+function scheduleDeferredSelfRetirement(root, found, name, o, session) {
+  const delaySec = o.selfKillDelaySec ?? 8;
+  const marker = retirePendingMarkerPath(found.home);
+  const resultPath = deferredRetireResultPath(found.home);
+  const logPath = resultPath.replace(/\.json$/, ".log");
+  // A second `--self` while the first completion is still on its way must not
+  // start a second, racing retirement: report the one already owed.
+  if (existsSync(marker) && !existsSync(resultPath)) {
+    let prior; try { prior = JSON.parse(readFileSync(marker, "utf8")); } catch { prior = undefined; }
+    if (prior?.resultPath) {
+      return { retired: name, agent: found.agent.name, deferred: true, alreadyScheduled: true, pendingMarker: marker, resultPath: prior.resultPath, logPath, completesInSec: prior.delaySec ?? delaySec, requestedAt: prior.requestedAt };
+    }
+  }
+  const intent = {
+    instance: name, agent: found.agent.name, root: resolve(root),
+    requestedAt: new Date().toISOString(), requestedByPid: process.pid, delaySec,
+    options: { deleteBranch: !!o.deleteBranch, ...(o.keepDir ? { keepDir: true } : {}), tmuxSession: session }, resultPath,
+  };
+  const env = { ...process.env, OATS_RETIRE_INTENT: JSON.stringify(intent) };
+  for (const k of CORE_LAUNCH_ENV) delete env[k];
+  rmSync(resultPath, { force: true });
+  const scheduleFailed = (why) => oatsError("E_SELF_RETIRE_SCHEDULE_FAILED", `could not start the deferred retirement of ${name}: ${why}. Nothing was inspected, run, or removed; the instance is still live and can be retired externally with \`oats retire ${name}\``);
+  let fd, child;
+  try {
+    fd = openSync(logPath, "w");
+    child = spawnProcess(process.execPath, ["--input-type=module", "-e", DEFERRED_RETIRE_SCRIPT], {
+      detached: true, stdio: ["ignore", fd, fd], env, cwd: dirname(found.home),
+    });
+  } catch (e) {
+    if (fd !== undefined) { try { closeSync(fd); } catch { /* already closed */ } }
+    rmSync(logPath, { force: true });
+    throw scheduleFailed(e.message);
+  }
+  closeSync(fd);
+  if (!child.pid) { rmSync(logPath, { force: true }); throw scheduleFailed("no process was created"); }
+  // A spawn failure Node reports asynchronously (EAGAIN, EMFILE) would arrive
+  // after this returns; record it as a failed outcome so status shows the
+  // debt instead of an uncaught exception behind a success message.
+  child.on("error", (e) => {
+    try {
+      writeFileSync(resultPath, JSON.stringify({ instance: name, agent: found.agent.name, requestedAt: intent.requestedAt, completedAt: new Date().toISOString(), ok: false, error: { code: e.code, message: `the deferred retirement could not start: ${e.message}` }, retry: `oats retire ${name}` }, null, 2) + "\n");
+    } catch { /* the marker alone then shows RETIRING; status names its age */ }
+  });
+  child.unref();
+  writeFileSync(marker, JSON.stringify(intent, null, 2) + "\n");
+  return {
+    retired: name, agent: found.agent.name, deferred: true, pendingMarker: marker,
+    resultPath, logPath, completesInSec: delaySec, completionPid: child.pid,
+  };
+}
+
+/** Run by the detached child: wait for the caller's window to be gone, then
+ *  retire the instance as an ordinary external operator. Returns true only
+ *  when the home is actually gone, and then leaves no file behind. A failure
+ *  writes an explicit outcome beside the home and leaves the pending marker
+ *  (and, after hooks ran, the usual quarantine) in place, so `oats status`
+ *  shows the debt and `oats retire <name>` retries and clears it. Accepts the
+ *  intent object (the child gets it in its env) or a marker path. */
+export function completeDeferredRetirement(intentOrMarkerPath, opts = {}) {
+  let intent = intentOrMarkerPath;
+  if (typeof intentOrMarkerPath === "string") {
+    try { intent = JSON.parse(readFileSync(intentOrMarkerPath, "utf8")); }
+    catch (e) { console.error(`deferred retirement: cannot read ${intentOrMarkerPath}: ${e.message}`); return false; }
+  }
+  if (!isPlainObject(intent) || !intent.instance || !intent.root) { console.error("deferred retirement: intent is not usable"); return false; }
+  const record = (payload) => {
+    if (!intent.resultPath) return;
+    try {
+      writeFileSync(intent.resultPath, JSON.stringify({
+        instance: intent.instance, agent: intent.agent, requestedAt: intent.requestedAt,
+        completedAt: new Date().toISOString(), ...payload,
+      }, null, 2) + "\n");
+    } catch (e) { console.error(`deferred retirement: cannot write ${intent.resultPath}: ${e.message}`); }
+  };
+  const delayMs = Math.max(0, Number(opts.delaySec ?? intent.delaySec ?? 8) * 1000);
+  if (delayMs) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, delayMs);
+  let result;
+  try {
+    result = retireInstance(intent.root, intent.instance, {
+      deleteBranch: !!intent.options?.deleteBranch, keepDir: !!intent.options?.keepDir, tmuxSession: intent.options?.tmuxSession,
+    });
+  } catch (e) {
+    record({ ok: false, error: { code: e.code, message: e.message }, retry: `oats retire ${intent.instance}` });
+    console.error(`deferred retirement of ${intent.instance} failed: ${e.message}`);
+    return false;
+  }
+  if (result.rollbackIncomplete) {
+    record({ ok: false, result, retry: `oats retire ${intent.instance}` });
+    console.error(`deferred retirement of ${intent.instance} is INCOMPLETE; the home is retained:\n  ${result.rollbackIncomplete.join("\n  ")}`);
+    return false;
+  }
+  if (intent.options?.keepDir) {
+    const retained = findInstanceHome(intent.root, intent.instance);
+    if (retained) rmSync(retirePendingMarkerPath(retained.home), { force: true });
+  }
+  // Success leaves nothing beside the home: the home is gone, the marker went
+  // with it, and a kept success record per retired reviewer or harvester would
+  // accumulate forever (reviewer D4). Only failures leave files, and they are
+  // the ones status surfaces and a retry clears.
+  try { rmSync(intent.resultPath.replace(/\.json$/, ".log"), { force: true }); } catch { /* nothing to keep */ }
+  return true;
+}
+
 export function retireInstance(root, name, o = {}) {
   const session = o.tmuxSession || DEFAULT_TMUX_SESSION;
-  const self = o.self === true; // self-retire: the caller IS the instance — kill the window LAST
+  // self-retire: the caller IS the instance. Without --keep-dir the whole
+  // retirement is deferred to a detached external completion (below); with
+  // --keep-dir the old in-process path runs and kills the window LAST.
+  const self = o.self === true;
   const found = findInstanceHome(root, name);
   if (!found) throw new Error(`no instance named "${name}"`);
   const metaPath = join(found.home, "instance.json");
@@ -6498,6 +6691,7 @@ export function retireInstance(root, name, o = {}) {
   if (quarantine && typeof quarantine.cleanup.launched === "boolean") {
     meta.launched = quarantine.cleanup.launched;
     meta.tmux = quarantine.cleanup.tmux;
+    meta.sessionTarget = quarantine.cleanup.sessionTarget;
   }
   // A home with NEITHER instance.json NOR a usable cleanup descriptor cannot be
   // retired safely: hooks would be skipped and the directory removed, which is
@@ -6517,8 +6711,13 @@ export function retireInstance(root, name, o = {}) {
   const workPath = join(found.home, "work");
   const isWorktree = meta.work === "worktree" ||
     (existsSync(workPath) && !lstatSync(workPath).isSymbolicLink());
-  if (self && !o.keepDir) {
-    throw oatsError("E_SELF_RETIRE_NOT_QUIESCED", `self-retire cannot establish a stable final work inspection while the calling runtime is active; exit the runtime, then have an external operator retire ${name}`);
+  // A live runtime cannot establish a stable final work inspection of itself,
+  // so self-retire never inspects, runs hooks, or removes anything here. It
+  // persists the intent and hands the whole retirement to a detached process
+  // that runs it as an ordinary EXTERNAL retirement once the runtime is gone
+  // (aweb-abep). `--keep-dir` keeps the old in-process path: nothing to inspect.
+  if (self && (!o.keepDir || meta.sessionTarget)) {
+    return scheduleDeferredSelfRetirement(root, found, name, o, session);
   }
   // First inspection is non-destructive. Only after it succeeds may OATS quiesce
   // the managed runtime; recovery copying never races a live managed Pi.
@@ -6533,11 +6732,12 @@ export function retireInstance(root, name, o = {}) {
     if (!runtimeAuthority) {
       throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `cannot quiesce ${name}: independent runtime endpoint authority is missing or invalid`);
     }
-    const metaAgrees = meta.launched === runtimeAuthority.launched && (!runtimeAuthority.launched || (
-      meta.tmux?.session === runtimeAuthority.tmux.session &&
-      meta.tmux?.window === runtimeAuthority.tmux.window &&
-      resolve(meta.tmux?.socket || ".") === runtimeAuthority.tmux.socket
-    ));
+    const endpointAgrees = runtimeAuthority.sessionTarget
+      ? !meta.tmux && ["backend", "binary", "socket", "workspaceId", "paneId", "terminalId", "protocol"].every((key) => meta.sessionTarget?.[key] === runtimeAuthority.sessionTarget[key])
+      : !meta.sessionTarget && meta.tmux?.session === runtimeAuthority.tmux?.session
+        && meta.tmux?.window === runtimeAuthority.tmux?.window
+        && resolve(meta.tmux?.socket || ".") === runtimeAuthority.tmux?.socket;
+    const metaAgrees = meta.launched === runtimeAuthority.launched && (!runtimeAuthority.launched || endpointAgrees);
     if (!metaAgrees) {
       throw oatsError("E_RUNTIME_AUTHORITY_MISMATCH", `cannot quiesce ${name}: mutable instance metadata disagrees with independent runtime endpoint authority`);
     }
@@ -6545,7 +6745,11 @@ export function retireInstance(root, name, o = {}) {
   // `=` forces exact matching: tmux targets otherwise PREFIX-match window names.
   // A no-launch instance is already quiesced. A launched one must have exact
   // window absence established before recovery copying begins.
-  if (!self && runtimeAuthority?.launched) {
+  if (!self && runtimeAuthority?.launched && runtimeAuthority.sessionTarget) {
+    try { stopHerdr(runtimeAuthority.sessionTarget); }
+    catch (e) { throw oatsError("E_RUNTIME_QUIESCE_FAILED", `could not establish that Herdr session for ${name} stopped: ${e.message}`); }
+  }
+  if (!self && runtimeAuthority?.launched && !runtimeAuthority.sessionTarget) {
     const runtimeSession = runtimeAuthority.tmux.session;
     const runtimeWindow = runtimeAuthority.tmux.window;
     const runtimeSocket = runtimeAuthority.tmux.socket;
@@ -6588,13 +6792,12 @@ export function retireInstance(root, name, o = {}) {
   // describes. A hook that reports nothing, or reports retired:true, is
   // unaffected; only an explicit "I did not finish" changes the outcome.
   let ordinaryIncomplete = [];
-  // SELF-RETIRE IS DELIBERATELY EXCLUDED. A self-retiring instance is the caller;
-  // it cannot hold the authority to complete owner cleanup, and turning its exit
-  // into a retained owner quarantine would change a path this change is not
-  // scoped to touch (reviewer-5c8b724: control deletes and schedules teardown,
-  // the first draft retained and quarantined). Self-retire keeps tearing down
-  // local state and leaving the incomplete operation for the recorded cleanup
-  // owner to reconcile.
+  // The IN-PROCESS self path (--self --keep-dir only, since aweb-abep) is
+  // excluded: that caller is the instance and cannot hold the authority to
+  // complete owner cleanup (reviewer-5c8b724). A plain --self never reaches
+  // here as `self`: its deferred completion calls retireInstance as an
+  // external operator, so a self-retiring reviewer or harvester whose hook
+  // reports incomplete cleanup IS quarantined like any other instance.
   if (!quarantine && !self) {
     for (const f of hookResults?.failures || []) ordinaryIncomplete.push(`retire hook ${f.capability}: ${f.message}`);
     // A hook may exit 0 and still report it did not finish. Only an explicit
@@ -6777,7 +6980,15 @@ export function retireInstance(root, name, o = {}) {
   // unreachable remote) would be unremovable through OATS forever — the same
   // dead end the unusable-marker fixes closed, just reached from a valid one.
   const forced = !!(stillIncomplete && o.force);
-  if (!o.keepDir && (!stillIncomplete || forced)) rmSync(found.home, { recursive: true, force: true });
+  if (!o.keepDir && (!stillIncomplete || forced)) {
+    rmSync(found.home, { recursive: true, force: true });
+    // The owed retirement is paid: clear the pending marker, and the failed
+    // outcome an earlier deferred attempt may have left beside the home; a
+    // deferred completion writes its own outcome after this returns.
+    rmSync(retirePendingMarkerPath(found.home), { force: true });
+    rmSync(deferredRetireResultPath(found.home), { force: true });
+    rmSync(deferredRetireResultPath(found.home).replace(/\.json$/, ".log"), { force: true });
+  }
 
 
   const result = { retired: name, agent: found.agent.name, workRecovery, workRecoveries: workRecoveries.length > 1 ? workRecoveries : undefined, worktreeRemoved: isWorktree, branchDeleted: !!(o.deleteBranch && meta.branch) || quarantineBranchDeleted, removedDir: !o.keepDir && (!stillIncomplete || forced), rollbackIncomplete: forced ? undefined : stillIncomplete, forcedIncomplete: forced ? stillIncomplete : undefined, retainedHome: stillIncomplete && !forced ? found.home : undefined, harvested, relinked: relinked.length ? relinked : undefined, capabilityMeta: hookResults?.meta, warnings: hookResults?.warnings?.length ? hookResults.warnings : undefined };