@awebai/oats 0.22.1 → 0.22.3

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}`);
@@ -667,7 +671,7 @@ export function resolveCapabilities(contextDir, soulName) {
       }
     }
     const ranked = [...list].sort((a, b) => a.specificity - b.specificity || b.scope - a.scope || a.target.localeCompare(b.target));
-    const settings = {};
+    const settings = Object.create(null); // manifest-declared names such as "constructor" must read as unset
     // Setting names come from parsed config, so the RANK table — a key→info
     // lookup, unlike `settings` itself, which is data handed to consumers — is
     // null-prototype: an inherited name must not read as an already-taken rank.
@@ -681,12 +685,28 @@ export function resolveCapabilities(contextDir, soulName) {
         settings[key] = value; settingRank[key] = rank;
       }
     }
+    // Declared defaults (manifest `settings: { <name>: { default } }`) are part
+    // of the effective settings: a requirement conditional on a setting must
+    // see the default for a deployment that never set it, or the default path
+    // silently loses its requirements (aweb review of oats.aweb 1.10.0).
+    const declaredSettings = manifest.settings && typeof manifest.settings === "object" && !Array.isArray(manifest.settings) ? manifest.settings : {};
+    for (const [key, decl] of Object.entries(declaredSettings)) {
+      if (!decl || typeof decl !== "object") continue;
+      if (settings[key] === undefined && decl.default !== undefined) settings[key] = decl.default;
+    }
     const strongest = [...list].sort((a, b) => b.specificity - a.specificity || a.scope - b.scope || a.target.localeCompare(b.target));
     const top = strongest[0];
     const tied = strongest.filter((c) => c.specificity === top.specificity && c.scope === top.scope);
     const enabledValues = new Set(tied.map((c) => c.binding.enabled === undefined ? true : !!c.binding.enabled));
     if (enabledValues.size > 1) throw new Error(`ambiguous enabled/excluded bindings for ${id} at equal specificity (${tied.map((c) => c.target).join(", ")})`);
     if (![...enabledValues][0]) continue;
+    // A declared value set is enforced for an ACTIVE capability: a misspelling
+    // must not switch a conditional requirement off by matching nothing.
+    for (const [key, decl] of Object.entries(declaredSettings)) {
+      if (decl && typeof decl === "object" && Array.isArray(decl.values) && settings[key] !== undefined && !decl.values.some((v) => String(v) === String(settings[key]))) {
+        throw new Error(`capability setting ${id}.${key} is ${JSON.stringify(settings[key])}, not one of ${decl.values.map((v) => JSON.stringify(v)).join(", ")}`);
+      }
+    }
     const compatibility = capabilityCompatibility(manifest);
     if (!compatibility.compatible) throw new Error(`capability "${id}" requires OATS ${compatibility.range}; running ${compatibility.version}`);
     const trust = capabilityTrust(manifest, contextDir);
@@ -699,7 +719,7 @@ export function resolveCapabilities(contextDir, soulName) {
     active.push({
       id, capability: id, manifest, layer: manifest.layer, command: manifest.command,
       level: top.level, origin: manifest._origin, provenance: list.map((c) => `${c.target} @ ${c.level}`),
-      settings, skills: capabilitySkillDirs(id, contextDir), inject,
+      settings: { ...settings }, skills: capabilitySkillDirs(id, contextDir), inject,
       // What the manifest PROMISES, so preflight can tell "declared nothing"
       // from "declared and missing" — the two are indistinguishable in the
       // resolved lists above.
@@ -713,6 +733,7 @@ export function resolveCapabilities(contextDir, soulName) {
       // what required:true claims to prevent (aggregate review at 798b156).
       requiredHooks: manifestRequiredHooks(manifest),
       environment: trust.trusted ? [...(manifest.environment || [])] : [],
+      environmentNamespaces: trust.trusted ? [...(manifest.environmentNamespaces || [])] : [],
       missingRequires: capabilityMissingRequires(id, contextDir), compatibility, trust, executable,
       retirement: trust.trusted ? manifest.retirement : undefined,
       _scope: top.scope,
@@ -725,6 +746,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 };
@@ -883,6 +906,18 @@ function validateCapabilityManifest(m, mf) {
       const vendor = id.match(/^([a-z][a-z0-9]*)\./)?.[1];
       if (!vendor) throw new Error(`capability ${id} must use a lowercase dotted vendor ID to declare launch environment`);
       const prefix = `${vendor.toUpperCase()}_`;
+      // A capability may declare additional namespaces it speaks for, e.g.
+      // the official oats.aweb integration setting the aweb extensions'
+      // AWEB_ variables. Declared, never implied: the names are disclosed at
+      // trust time with the rest of the launch environment, and the reserved
+      // core and bootstrap namespaces can never be claimed this way.
+      const extraNamespaces = m.environmentNamespaces === undefined ? [] : m.environmentNamespaces;
+      if (!Array.isArray(extraNamespaces) || extraNamespaces.some((ns) => typeof ns !== "string")) throw new Error(`capability ${id} manifest environmentNamespaces must be an array of prefixes`);
+      for (const ns of extraNamespaces) {
+        if (!/^[A-Z][A-Z0-9]*_$/.test(ns)) throw new Error(`capability ${id} manifest environmentNamespaces entry ${JSON.stringify(ns)} must be an uppercase prefix ending in an underscore`);
+        if (ns === "OATS_" || ns === "PI_AGENT_" || PROCESS_BOOTSTRAP_PREFIXES.some((reserved) => ns.startsWith(reserved) || reserved.startsWith(ns))) throw new Error(`capability ${id} manifest environmentNamespaces entry ${ns} is a reserved namespace`);
+      }
+      const allowed = [prefix, ...extraNamespaces];
       for (const name of m.environment) {
         if (!PORTABLE_ENV_NAME_RE.test(name)) throw new Error(`capability ${id} manifest environment name ${JSON.stringify(name)} is invalid`);
         if (CORE_LAUNCH_ENV.has(name) || name.startsWith("OATS_") || name.startsWith("PI_AGENT_")) {
@@ -891,7 +926,7 @@ function validateCapabilityManifest(m, mf) {
         if (PROCESS_BOOTSTRAP_ENV.has(name) || PROCESS_BOOTSTRAP_PREFIXES.some((reserved) => name.startsWith(reserved))) {
           throw new Error(`capability ${id} manifest environment name ${name} collides with a reserved process bootstrap variable`);
         }
-        if (!name.startsWith(prefix)) throw new Error(`capability ${id} manifest environment name ${name} is outside its ${prefix} namespace`);
+        if (!allowed.some((ns) => name.startsWith(ns))) throw new Error(`capability ${id} manifest environment name ${name} is outside its ${allowed.join(", ")} namespace${allowed.length > 1 ? "s" : ""} (declare another in environmentNamespaces)`);
       }
     }
   }
@@ -1303,6 +1338,7 @@ export function capabilityTrust(a, b) {
       commands: Object.keys(manifest?.commands || {}),
       hooks: Object.keys(manifest?.hooks || {}),
       environment: [...(manifest?.environment || [])],
+      ...(manifest?.environmentNamespaces?.length ? { environmentNamespaces: [...manifest.environmentNamespaces] } : {}),
     };
     return { ...t, package: t.package || manifest?._package, executableSurface: surface };
   }
@@ -2585,6 +2621,7 @@ function executableSurfaceOf(manifest) {
     commands: Object.keys(manifest?.commands || {}),
     hooks: Object.keys(manifest?.hooks || {}),
     environment: [...(manifest?.environment || [])],
+    ...(manifest?.environmentNamespaces?.length ? { environmentNamespaces: [...manifest.environmentNamespaces] } : {}),
   };
 }
 function hasExecutableSurface(manifest) {
@@ -4248,6 +4285,27 @@ export function packageSpecIdentity(spec) {
 /** What the runtime reports about a required package: is it there, where did it
  * land, and does the user's entry filter its resources? A settings row alone is
  * NOT proof the capability's extension will load (reviewer-8518c49). */
+/** The installed version of a runtime package: neither pi's nor Claude's
+ *  listing reports one, so it is read from the package.json under the
+ *  install directory the listing names; undefined when there is none. */
+export function installedRuntimePackageVersion(runtime, spec, status) {
+  const dir = status?.dir;
+  if (dir && existsSync(join(dir, "package.json"))) {
+    try {
+      const v = JSON.parse(readFileSync(join(dir, "package.json"), "utf8")).version;
+      if (typeof v === "string" && /^\d+\.\d+\.\d+/.test(v)) return v.match(/^\d+\.\d+\.\d+/)[0];
+    } catch { /* unreadable manifest: unknowable */ }
+  }
+  return undefined;
+}
+
+export function compareVersionTriples(a, b) {
+  const pa = String(a).split(".").map((x) => Number.parseInt(x, 10) || 0);
+  const pb = String(b).split(".").map((x) => Number.parseInt(x, 10) || 0);
+  for (let i = 0; i < 3; i++) { const d = (pa[i] || 0) - (pb[i] || 0); if (d) return d; }
+  return 0;
+}
+
 export function runtimePackageStatus(runtime, spec, env = process.env, opts = {}) {
   const mgr = RUNTIME_PACKAGE_MANAGERS[runtime];
   if (!mgr) return { installed: false };
@@ -4336,6 +4394,12 @@ function validateHookEnvironment(capabilityID, value, owners, declarations) {
     throw new HookEnvironmentContractError(`${capabilityID} hook env requires a dotted lowercase alphanumeric vendor component; hyphen, @, and / forms cannot claim an environment namespace`);
   }
   const prefix = `${vendorComponent.toUpperCase()}_`;
+  // The runtime half of the same contract the manifest validator enforces:
+  // a hook may set names under its vendor prefix or under a namespace its
+  // trusted manifest declared (environmentNamespaces), and only names the
+  // manifest listed. Manifest and runtime must permit exactly the same set.
+  const declared = declarations.get(capabilityID) || { names: new Set(), namespaces: [] };
+  const allowed = [prefix, ...(declared.namespaces || [])];
   const accepted = {};
   for (const name of Object.keys(value).sort()) {
     const envValue = value[name];
@@ -4348,10 +4412,10 @@ function validateHookEnvironment(capabilityID, value, owners, declarations) {
     if (PROCESS_BOOTSTRAP_ENV.has(name) || PROCESS_BOOTSTRAP_PREFIXES.some((reserved) => name.startsWith(reserved))) {
       throw new HookEnvironmentContractError(`${capabilityID} hook env name ${name} collides with a reserved process bootstrap variable`);
     }
-    if (!name.startsWith(prefix)) {
-      throw new HookEnvironmentContractError(`${capabilityID} hook env name ${name} is outside its ${prefix} namespace`);
+    if (!allowed.some((ns) => name.startsWith(ns))) {
+      throw new HookEnvironmentContractError(`${capabilityID} hook env name ${name} is outside its ${allowed.join(", ")} namespace${allowed.length > 1 ? "s" : ""}`);
     }
-    if (!(declarations.get(capabilityID) || new Set()).has(name)) {
+    if (!declared.names.has(name)) {
       throw new HookEnvironmentContractError(`${capabilityID} hook env name ${name} is not declared in its trusted manifest environment`);
     }
     if (typeof envValue !== "string") {
@@ -4376,7 +4440,7 @@ function validateHookEnvironment(capabilityID, value, owners, declarations) {
 export function runLifecycleHooks(event, { home, instance, agentName, soulDir, contextDir, workspaceDir, rootDir, resolved, priorMeta = {}, extraEnv = {} }) {
   const results = { meta: {}, briefs: [], warnings: [], order: [], launch: {}, env: {}, failures: [] };
   const envOwners = new Map();
-  const envDeclarations = new Map((resolved.capabilities || []).map((cap) => [cap.id, new Set(cap.environment || [])]));
+  const envDeclarations = new Map((resolved.capabilities || []).map((cap) => [cap.id, { names: new Set(cap.environment || []), namespaces: [...(cap.environmentNamespaces || [])] }]));
   const caps = [...(resolved.capabilities || [])];
   if (event === "retire") caps.reverse();
   for (const cap of caps) {
@@ -4716,13 +4780,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 +4840,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 +4851,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 +4863,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 +4983,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
@@ -4973,6 +5057,11 @@ function verifyRuntimePackages(runtime, resolved, contextDir) {
   for (const cap of resolved.capabilities || []) {
     for (const raw of cap.manifest?.requires || []) {
       if (!raw || typeof raw !== "object" || raw.runtime !== runtime) continue;
+      // A requirement may be conditional on the capability's effective
+      // settings (`when: { delivery: "channel" }`): rows whose condition does
+      // not hold are not requirements of this spawn at all.
+      if (raw.when !== undefined && (!raw.when || typeof raw.when !== "object" || Array.isArray(raw.when))) { problems.push(`${cap.id}: a requirement's \`when\` must be an object of setting names to values`); continue; }
+      if (raw.when && !Object.entries(raw.when).every(([k, v]) => String(cap.settings?.[k] ?? "") === String(v))) continue;
       const spec = raw.package;
       if (!safeRuntimePackageSpec(spec, runtime)) { problems.push(`${cap.id}: ${runtime} package spec is not a plain source token (${JSON.stringify(spec)})`); continue; }
       if (raw.marketplace !== undefined && !safeRuntimeSourceRef(raw.marketplace)) { problems.push(`${cap.id}: marketplace is not a plain source reference (${JSON.stringify(raw.marketplace)})`); continue; }
@@ -4981,7 +5070,10 @@ function verifyRuntimePackages(runtime, resolved, contextDir) {
       const stepList = mgr?.steps ? mgr.steps(spec, raw, probeOpts) : [mgr?.argv(spec, raw, probeOpts) || []];
       const direct = stepList.filter((a) => a.length).map((a) => a.join(" ")).join(" && ");
       const remedy = `run \`oats install --accept-requirement ${runtime}:${runtimePackageIdentity(runtime, spec)} --dir ${contextDir}\`${direct ? ` (or \`${direct}\` directly)` : ""}`;
-      if (!status.installed) { problems.push(`${cap.id} requires the ${runtime} package ${spec}, which is not installed — ${remedy}`); continue; }
+      // `ifInstalled: true`: the row constrains a package that may be absent
+      // (an ambient extension must honour a contract IF it is there); absence
+      // satisfies it. Without the flag, absence fails as before.
+      if (!status.installed) { if (raw.ifInstalled === true) continue; problems.push(`${cap.id} requires the ${runtime} package ${spec}, which is not installed — ${remedy}`); continue; }
       // A settings row is not proof the extension loads. Both of these leave the
       // capability silently absent, which is the loss this gate exists to stop.
       if (status.unverified) { problems.push(`${cap.id} requires the ${runtime} package ${spec}: it is configured, but OATS could not verify it is installed (${status.unverified}) — a config entry is not an installation; ${remedy}`); continue; }
@@ -4993,6 +5085,16 @@ function verifyRuntimePackages(runtime, resolved, contextDir) {
       }
       if (status.disabled) { problems.push(`${cap.id} requires the ${runtime} package ${spec}, which is installed but DISABLED, so it will not load — enable it (\`${probeOpts.bin || runtime} plugin enable ${spec}\` for Claude), or drop the capability for this soul`); continue; }
       if (status.extensionsDisabled) { problems.push(`${cap.id} requires the ${runtime} package ${spec}, but your ${runtime} settings entry sets "extensions": [], which loads none of them — remove that filter, or drop the capability for this soul`); continue; }
+      // A floor on the installed version (`minVersion`), checked once presence
+      // and loadability are settled: a package whose manifest states an older
+      // version, or none, fails closed with the same remedy, since an old
+      // extension that ignores a newer contract (AWEB_DELIVERY) is exactly
+      // what the floor guards.
+      if (raw.minVersion) {
+        const have = installedRuntimePackageVersion(runtime, spec, status);
+        if (!have) { problems.push(`${cap.id} requires the ${runtime} package ${spec} at ${raw.minVersion} or later, but its installed version cannot be established (no package manifest under its install directory) — ${remedy}`); continue; }
+        if (compareVersionTriples(have, raw.minVersion) < 0) { problems.push(`${cap.id} requires the ${runtime} package ${spec} at ${raw.minVersion} or later; ${have} is installed — ${remedy}`); continue; }
+      }
       if (status.extensionsFilter?.length) {
         // Unverifiable, not merely auditable: proving the filter selects this
         // capability's extension means implementing pi's glob semantics, and
@@ -5017,8 +5119,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 +5430,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 +5442,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 +5632,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 +5652,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 +5780,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 +5797,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 +5865,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,
@@ -5742,6 +5879,7 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
         settings: cap.settings, provenance: cap.provenance, skills: cap.skills || [],
         hooks: Object.keys(cap.hooks || {}), trusted: !!cap.trust?.trusted,
         ...(cap.environment?.length ? { environment: [...cap.environment] } : {}),
+        ...(cap.environmentNamespaces?.length ? { environmentNamespaces: [...cap.environmentNamespaces] } : {}),
       })),
       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 })),
@@ -5768,7 +5906,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"],
@@ -5780,17 +5922,25 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
       },
       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,
+        hooks: cap.hooks, requiredHooks: cap.requiredHooks, environment: cap.environment, environmentNamespaces: cap.environmentNamespaces,
         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 +5994,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 +6006,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 +6025,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 +6075,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 +6156,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,10 +6172,11 @@ 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,
-          hooks: cap.hooks, requiredHooks: cap.requiredHooks, environment: cap.environment,
+          hooks: cap.hooks, requiredHooks: cap.requiredHooks, environment: cap.environment, environmentNamespaces: cap.environmentNamespaces,
           missingRequires: cap.missingRequires,
           trust: cap.trust, executable: cap.executable,
         })),
@@ -5997,7 +6187,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 +6261,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 +6299,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 +6350,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 +6376,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 +6385,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 +6397,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;
@@ -6247,17 +6491,44 @@ const RECOVERABLE_GIT_ADMIN = [
   "BISECT_LOG", "BISECT_START", "BISECT_NAMES", "rebase-apply", "rebase-merge", "sequencer",
 ];
 
+/** Object ids among `oids` that `repo` does not have, from one
+ *  `cat-file --batch-check` process. */
+export function missingGitObjects(repo, oids) {
+  if (!oids.length) return [];
+  const out = execFileSync("git", ["-C", repo, "cat-file", "--batch-check=%(objectname) %(objecttype)"], { input: oids.join("\n") + "\n", encoding: "utf8", maxBuffer: GIT_MAX_BUFFER });
+  const missing = [];
+  for (const line of out.split("\n")) {
+    if (!line.endsWith(" missing")) continue;
+    missing.push(line.slice(0, line.indexOf(" ")));
+  }
+  return missing;
+}
+
 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 });
+  // The staged blobs the recovered index will point at. The clone already
+  // holds every blob reachable from a commit; only content that is staged but
+  // never committed is missing, so ask once which objects the recovered
+  // repository lacks (one process for the whole index) and copy only those.
+  // Copying every row cost two Git processes per index entry: a clean 9,500
+  // file tree took ~19,000 launches and looked like a hang. Gitlink rows
+  // (mode 160000) name commits of nested repositories, which
+  // materializeNestedRepositories restores; they are never blobs here.
+  const staged = new Set();
   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();
-    if (restored !== match[1]) throw new Error(`recovered Git object ${restored} did not match source ${match[1]}`);
+    const match = row.match(/^(\d+) ([0-9a-f]+) \d+\t/);
+    if (!match || match[1] === "160000") continue;
+    staged.add(match[2]);
   }
+  for (const oid of missingGitObjects(recoveredRepo, [...staged])) {
+    const blob = execFileSync("git", ["-C", sourceWork, "cat-file", "blob", oid], { 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 !== oid) throw new Error(`recovered Git object ${restored} did not match source ${oid}`);
+  }
+  const stillMissing = missingGitObjects(recoveredRepo, [...staged]);
+  if (stillMissing.length) throw new Error(`recovered repository lacks ${stillMissing.length} staged object(s) after restore: ${stillMissing.slice(0, 3).join(", ")}`);
   copyFileSync(join(sourceGit, "index"), join(recoveredGit, "index"));
   for (const name of RECOVERABLE_GIT_ADMIN) {
     const source = join(sourceGit, name);
@@ -6270,11 +6541,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 +6553,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 })) {
@@ -6312,14 +6583,24 @@ function preserveRetirementWork(observation, meta, instance) {
   const staging = mkdtempSync(join(recoveryRoot, `.${instance}-`));
   const recovery = join(recoveryRoot, basename(staging).slice(1));
   try {
+    // A home-only change (notes, runtime files, credentials) needs a home
+    // snapshot, not another copy of an otherwise disposable clean worktree.
+    // In-progress Git operations retain the full standalone recovery even
+    // when porcelain status has no changed paths.
+    let homeOnly = observation.classes.length === 1 && observation.classes[0] === "changed instance-home bytes"
+      && meta.work === "worktree" && existsSync(observation.work);
+    if (homeOnly) {
+      const gitDir = execFileSync("git", ["-C", observation.work, "rev-parse", "--absolute-git-dir"], { encoding: "utf8", maxBuffer: GIT_MAX_BUFFER }).trim();
+      homeOnly = !RECOVERABLE_GIT_ADMIN.some((name) => existsSync(join(gitDir, name)));
+    }
     const recoveredHome = join(staging, "home");
     copyRecoveryTree(observation.home, recoveredHome, { excludeRoot: new Set(["work"]) });
     if (fingerprintTree(observation.home, { excludeRoot: new Set(["work"]) }) !== fingerprintTree(recoveredHome)) {
       throw new Error("home recovery verification disagreed with the source");
     }
-    if (meta.work === "worktree" && meta.repo && meta.branch && (existsSync(observation.work) || observation.branchExists)) {
+    if (!homeOnly && 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,25 +6618,176 @@ 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 });
+    const repoCopy = homeOnly ? { copied: false, reason: "Only instance-home bytes changed; no work state requires a repository copy", source: meta.repo, branch: meta.branch } : undefined;
+    writeFileSync(join(staging, "recovery.json"), JSON.stringify({ version: 1, instance, classes: observation.classes, sourceHome: observation.home, createdAt: new Date().toISOString(), ...(repoCopy ? { repoCopy } : {}) }, null, 2) + "\n", { mode: 0o600 });
     mkdirSync(dirname(recovery), { recursive: true });
     renameSync(staging, recovery);
-    return { path: recovery, classes: observation.classes };
+    return { path: recovery, classes: observation.classes, ...(repoCopy ? { repoCopy } : {}) };
   } catch (e) {
     rmSync(staging, { recursive: true, force: true });
     throw oatsError("E_WORK_PRESERVATION_FAILED", `retirement work remains at ${observation.home}; recovery could not be verified: ${e.message}`);
   }
 }
 
+/** 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: { home: found.home, 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} --home ${found.home}\``);
+  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} --home ${found.home}` }, 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, {
+      home: intent.options?.home, 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}${intent.options?.home ? ` --home ${intent.options.home}` : ""}` });
+    console.error(`deferred retirement of ${intent.instance} failed: ${e.message}`);
+    return false;
+  }
+  if (result.rollbackIncomplete) {
+    record({ ok: false, result, retry: `oats retire ${intent.instance}${intent.options?.home ? ` --home ${intent.options.home}` : ""}` });
+    console.error(`deferred retirement of ${intent.instance} is INCOMPLETE; the home is retained:\n  ${result.rollbackIncomplete.join("\n  ")}`);
+    return false;
+  }
+  if (intent.options?.keepDir) {
+    // The kept home is the one the intent names, never a same-named twin.
+    const retained = intent.options?.home ? { home: intent.options.home } : 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
-  const found = findInstanceHome(root, name);
-  if (!found) throw new Error(`no instance named "${name}"`);
+  // 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;
+  // Names are unique per agent dir only: two agents can own an instance of
+  // the same name (dev --purpose foo-1 and agent dev-foo). Retirement is
+  // destructive, so a name that resolves to several homes is refused unless
+  // the caller says which home (--home), and a home is accepted only when it
+  // is one of that name's homes under this root.
+  const matches = findInstanceHomes(root, name);
+  if (!matches.length) throw new Error(`no instance named "${name}"`);
+  const sameHome = (a, b) => { try { return realpathSync(a) === realpathSync(b); } catch { return resolve(a) === resolve(b); } };
+  let found;
+  if (o.home) {
+    found = matches.find((m) => sameHome(m.home, o.home));
+    if (!found) throw oatsError("E_HOME_MISMATCH", `instance "${name}" has no home at ${o.home} under this agents root (its home${matches.length === 1 ? " is" : "s are"} ${matches.map((m) => m.home).join(", ")})`);
+  } else if (matches.length > 1) {
+    throw oatsError("E_AMBIGUOUS_INSTANCE", `"${name}" names ${matches.length} instances under this agents root (${matches.map((m) => `${m.agent.name}: ${m.home}`).join("; ")}); retire with --home <path> to say which`);
+  } else {
+    found = matches[0];
+  }
   const metaPath = join(found.home, "instance.json");
   // A QUARANTINED home (spawn failed after a required hook and compensation did
   // not finish) has no instance.json — it never got that far. Its marker carries
@@ -6390,6 +6822,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 +6842,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 +6863,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 +6876,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 +6923,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 +7111,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 };