@awebai/oats 0.22.1 → 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 };
@@ -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
@@ -5335,9 +5366,10 @@ export function spawnInstance(root, agent, o = {}) {
 
   // Prerequisites must fail before creating a home, worktree, or identity.
   const claudeBin = runtime === "claude" ? resolveClaudeBinary(repoAbs) : undefined;
-  const bin = which(runtime === "claude" ? claudeBin : "pi");
+  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("tmux")) throw new Error("tmux not installed (brew install tmux)");
+  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 });
@@ -5524,6 +5556,7 @@ export function spawnInstance(root, agent, o = {}) {
   const requiredFailures = (hookRes.failures || []).filter((f) => f.required);
   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
@@ -5543,7 +5576,23 @@ export function spawnInstance(root, agent, o = {}) {
     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) {
+    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);
@@ -5655,7 +5704,7 @@ export function spawnInstance(root, agent, o = {}) {
 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
@@ -5672,7 +5721,18 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
       // 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)"`;
+      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.
@@ -5729,6 +5789,7 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
     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,
@@ -5768,7 +5829,11 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
               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"],
@@ -5784,13 +5849,21 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
         missingRequires: cap.missingRequires, trust: cap.trust,
         executable: cap.executable,
       })),
-      tmux: { session, window: instance },
+      ...(backend === "herdr" ? { backend } : { tmux: { session, window: instance } }),
       command: cmdline, createdAt: new Date().toISOString(),
     };
     const spawnWarnings = warnings;
 
     spawnTmux = meta.tmux;
-    if (launch) {
+    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)}`);
@@ -5844,7 +5917,7 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
       }
     }
 
-    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;
@@ -5856,8 +5929,11 @@ 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);
@@ -5872,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.
@@ -5887,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);
     }
   }
@@ -5967,7 +6079,7 @@ export const QUARANTINE_GIT_DEBT = ["worktree", "branch"];
 
 /** 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, recordRetirementBaseline = false, reason }) {
+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
@@ -5983,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,
@@ -5997,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}`);
     }
@@ -6071,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);
@@ -6100,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"}`);
   }
@@ -6151,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);
@@ -6176,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.
@@ -6185,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"}`);
   }
@@ -6197,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;
@@ -6248,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"));
@@ -6270,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");
@@ -6282,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 })) {
@@ -6319,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)) {
@@ -6337,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 });
@@ -6351,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");
@@ -6390,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
@@ -6409,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.
@@ -6425,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`);
     }
@@ -6437,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;
@@ -6480,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
@@ -6669,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 };