@awebai/oats 0.30.3 → 0.32.0

package/lib/core.mjs

@@ -33,6 +33,7 @@ import {
 } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { accessSync, constants as fsConstants } from "node:fs";
+import { recordLocalInput } from "./local-inputs.mjs";
 import { createHash, randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { initializeNativeHistory, prepareNativeStart } from "../packages/record/lib/native-history.mjs";
@@ -41,9 +42,8 @@ import { attachSessionTarget } from "./session-viewer.mjs";
 import { inspectSessionTarget, inputSessionTarget } from "./session-input.mjs";
 import { appendEvent } from "./instance-events.mjs";
 import { killGroup } from "./process-group.mjs";
-import { ensureHerdr, allocateHerdr, launchHerdr, inspectHerdr, stopHerdr, validHerdrTarget, herdrSnapshot, herdrCommand } from "./herdr.mjs";
 
-import { oatsError } from "./errors.mjs";
+import { oatsError, herdrInstanceBusy, herdrInstanceRemoved, herdrSettingRemoved, HERDR_REMOVED } from "./errors.mjs";
 import { envRows, recordedTeams, teamsEnv } from "./teams.mjs";
 import { harnessUnavailable, launchConfigUnknown, launchLayers, launchReport, selectionFrom } from "./launch-preference.mjs";
 async function materializePreparedDefault(prepared, home) { const m = await import("./instance-resolution.mjs"); return m.materializePrepared(prepared, home); }
@@ -126,7 +126,22 @@ export function legacyCapturedHomes(root) {
   return { code: "legacy-captured-home", instances: homes.map((h) => h.instance), homes: homes.map((h) => h.home),
     message: `${homes.length} captured home${one ? "" : "s"} (0.24–0.25; the captured/portable path was removed in 0.26) ${one ? "has" : "have"} no 0.26 runtime: start, inspect and in-home commands refuse ${one ? "it" : "them"}; retire ${one ? "it" : "them"} (\`oats retire\` still works) and re-spawn from the deployment (${homes.map((h) => h.instance).join(", ")})` };
 }
-export const DEFAULT_TMUX_SESSION = process.env.PI_AGENTS_TMUX_SESSION || "pi-agents";
+// The tmux session a new tmux instance opens its window in, when oats-local.yaml session.tmuxSession
+// names none (0.31). PI_AGENTS_TMUX_SESSION is the pre-0.31 variable, still honoured. The Desktop keeps
+// the same default in packages/desktop/server/tmux-status.mjs (it does not import lib/): change both.
+export const DEFAULT_TMUX_SESSION = process.env.OATS_TMUX_SESSION || process.env.PI_AGENTS_TMUX_SESSION || "oats-agents";
+/**
+ * The tmux session a NEW tmux launch opens its window in (0.31): the caller's, else the deployment's
+ * oats-local.yaml `session.tmuxSession`, else OATS_TMUX_SESSION, else PI_AGENTS_TMUX_SESSION, else
+ * oats-agents, read from `env` at call time. A launched home keeps the session it recorded: session
+ * start/restart never read this.
+ */
+export function sessionDefaults(dir, { tmuxSession } = {}, env = process.env) {
+  let local = null;
+  try { local = loadLocal(dir); } catch (e) { if (e?.code !== "E_LOCAL_MISSING") throw e; }
+  const declared = local?.local?.session ?? {};
+  return { tmuxSession: tmuxSession || declared.tmuxSession || env.OATS_TMUX_SESSION || env.PI_AGENTS_TMUX_SESSION || "oats-agents" };
+}
 /** Package root (this file lives in <pkg>/lib/). */
 export const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 export const OATS_VERSION = JSON.parse(readFileSync(join(PKG_ROOT, "package.json"), "utf8")).version;
@@ -169,7 +184,13 @@ export function slug(s) {
   const r = String(s).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
   return r || "agent";
 }
-function which(bin) { return shTry(`command -v ${shq(bin)}`); }
+/** `command -v <bin>`, once per (bin, PATH) in this process: the answer only changes with PATH. */
+const whichMemo = new Map();
+function which(bin) {
+  const key = `${bin}\0${process.env.PATH ?? ""}`;
+  if (!whichMemo.has(key)) whichMemo.set(key, shTry(`command -v ${shq(bin)}`));
+  return whichMemo.get(key);
+}
 
 // ---------- yaml-ish ----------
 /** `__proto__` is never data in a plain-object mapping: assigning it REWRITES
@@ -511,7 +532,7 @@ export const LAYERS = ["knowledge", "messaging", "tasks"];
 // deployment's oats-local.yaml (lead decision 2: a spawn-time HOST choice,
 // never a soul field). Selected at spawn or session start/restart by name.
 export const LAUNCH_HARNESSES = ["pi", "claude", "codex"];
-export const LAUNCH_CONFIG_KEYS = new Set(["harness", "runtime", "executable", "args", "env", "model", "yolo"]);
+export const LAUNCH_CONFIG_KEYS = new Set(["harness", "runtime", "executable", "args", "env", "model", "yolo", "default"]);
 /** A launch configuration's harness: `harness`, or `runtime`, its pre-0.27 name (0.26.0
  *  deployments wrote it) — read either (lead call 6). */
 export const launchConfigHarness = (entry) => (Object.hasOwn(entry, "harness") ? entry.harness : entry.runtime);
@@ -527,7 +548,7 @@ export function validateLaunchConfig(name, entry, where) {
   if (typeof name !== "string" || !LAUNCH_CONFIG_NAME.test(name)) bad("has an invalid name (letters, digits, dot, underscore, dash; up to 64 characters)");
   if (name === "none") bad("cannot be named none: that word selects no configuration");
   if (!entry || typeof entry !== "object" || Array.isArray(entry)) bad("must be a map");
-  for (const key of Object.keys(entry)) if (!LAUNCH_CONFIG_KEYS.has(key)) bad(`has an unsupported key ${JSON.stringify(key)} (harness, executable, args, env, model, yolo)`);
+  for (const key of Object.keys(entry)) if (!LAUNCH_CONFIG_KEYS.has(key)) bad(`has an unsupported key ${JSON.stringify(key)} (harness, executable, args, env, model, yolo, default)`);
   if (Object.hasOwn(entry, "harness") && Object.hasOwn(entry, "runtime") && entry.harness !== entry.runtime) bad(`names harness ${JSON.stringify(entry.harness)} and runtime ${JSON.stringify(entry.runtime)}: \`runtime\` is the pre-0.27 name of \`harness\` — keep one`);
   if (!LAUNCH_HARNESSES.includes(launchConfigHarness(entry))) bad(`needs harness: one of ${LAUNCH_HARNESSES.join(", ")}`);
   const text = (v, what) => { if (typeof v !== "string" || !v.trim() || v.includes("\0")) bad(`${what} must be non-empty text`); };
@@ -548,12 +569,25 @@ export function validateLaunchConfig(name, entry, where) {
   }
   if (entry.model !== undefined) text(entry.model, "model");
   if (entry.yolo !== undefined && typeof entry.yolo !== "boolean") bad("yolo must be true or false");
+  if (entry.default !== undefined && typeof entry.default !== "boolean") bad("default must be true or false");
   return entry;
 }
+/** At most one `default: true` per harness (0.32, feature launch-config-default): the host's baseline for
+ *  that harness has one source. `map` is name → entry; entries are validated first. */
+export function validateLaunchConfigDefaults(map, where) {
+  const byHarness = new Map();
+  for (const [name, entry] of Object.entries(map || {})) {
+    if (entry?.default !== true) continue;
+    const harness = launchConfigHarness(entry);
+    if (byHarness.has(harness)) throw Object.assign(oatsError("E_LAUNCH_CONFIG_INVALID", `launch configurations ${JSON.stringify(byHarness.get(harness))} and ${JSON.stringify(name)}${where ? ` in ${where}` : ""} are both default: true for ${harness}; keep one default per harness`), { details: { harness, configurations: [byHarness.get(harness), name] } });
+    byHarness.set(harness, name);
+  }
+}
 function validateLaunchConfigs(map, file) {
   if (map === undefined) return;
   if (!map || typeof map !== "object" || Array.isArray(map)) throw oatsError("E_LAUNCH_CONFIG_INVALID", `launch-configs in ${file} must be a map of name to configuration`);
   for (const [name, entry] of Object.entries(map)) validateLaunchConfig(name, entry, file);
+  validateLaunchConfigDefaults(map, file);
 }
 /** The launch configurations effective at `dir`: the `launch-configs:` of the
  *  oats-local.yaml found walking up from it (the deployment), validated. None
@@ -571,7 +605,7 @@ export function launchConfigsAt(dir) {
   const source = dirname(found.path);
   for (const [name, entry] of Object.entries(map || {})) {
     if (!Object.hasOwn(entry, "harness")) noteRuntimeName(`launch-configs.${name}.runtime in ${found.path}`);
-    out[name] = { name, harness: launchConfigHarness(entry), ...(entry.executable !== undefined ? { executable: entry.executable } : {}), args: [...(entry.args || [])], env: { ...(entry.env || {}) }, ...(entry.model !== undefined ? { model: entry.model } : {}), ...(entry.yolo !== undefined ? { yolo: entry.yolo } : {}), source, shadows: [] };
+    out[name] = { name, harness: launchConfigHarness(entry), ...(entry.executable !== undefined ? { executable: entry.executable } : {}), args: [...(entry.args || [])], env: { ...(entry.env || {}) }, ...(entry.model !== undefined ? { model: entry.model } : {}), ...(entry.yolo !== undefined ? { yolo: entry.yolo } : {}), ...(entry.default === true ? { default: true } : {}), source, shadows: [] };
   }
   return out;
 }
@@ -844,9 +878,14 @@ export function officialPackageCatalog() {
 function readCatalogFile() {
   const file = officialCatalogFile();
   const empty = { packages: Object.create(null), capabilities: Object.create(null), file };
-  if (!existsSync(file)) return empty;
+  // An OATS_PACKAGE_CATALOG override is local configuration (observation.localRevision); the bundled
+  // catalog belongs to the kernel install.
+  const override = !!process.env.OATS_PACKAGE_CATALOG;
+  if (!existsSync(file)) { if (override) recordLocalInput(file, null); return empty; }
   let doc;
-  try { doc = JSON.parse(readFileSync(file, "utf8")); }
+  const text = readFileSync(file, "utf8");
+  if (override) recordLocalInput(file, text);
+  try { doc = JSON.parse(text); }
   catch (e) { throw oatsError("invalid-source", `broken package catalog ${file}: ${e.message}`); }
   if (!doc || typeof doc !== "object" || Array.isArray(doc)) throw oatsError("invalid-source", `broken package catalog ${file}: root must be a JSON object`);
   const out = { packages: Object.create(null), capabilities: Object.create(null), file };
@@ -1233,7 +1272,7 @@ export const HARNESS_PACKAGE_MANAGERS = {
      * different marketplaces into one identity. */
     identity: (spec) => String(spec || "").trim(),
     safeSpec: (spec) => typeof spec === "string" && /^[a-z0-9][\w.-]*@[a-z0-9][\w.-]*$/i.test(spec),
-    /** The executable is CONTEXT-SELECTED (oats-claude-config may name a wrapper
+    /** The executable is SELECTED by the launch (a configuration may name a wrapper
      * such as `claude-personal`). Probing and installing through the literal
      * `claude` would inspect a DIFFERENT account's plugins than the session
      * actually launches with — passing preflight while the real harness lacks
@@ -1834,20 +1873,21 @@ export function tmuxWindows(session = DEFAULT_TMUX_SESSION) {
  * Spawn an instance of `agent` (as returned by findAgent/listAgents).
  * o: { instance?, purpose?, name?, repo?, work?, harness?, model?, task?, taskFile?, branch?, launch?, tmuxSession? }
  */
-/** The claude binary for a context: closest `oats-claude-config` (a one-line file
- * naming the binary, e.g. "claude-personal") walking up from contextDir wins; no
- * file → "claude". Local-only by design — a personal machine preference (account
- * selection), never committed config; keep it out of version control. */
-export function resolveClaudeBinary(contextDir) {
+/** `oats-claude-config` (a one-line file naming the claude binary, found walking up from the context) is no
+ *  longer read (0.32): a host names its claude executable in a default launch configuration. A file still in
+ *  reach of a new claude launch refuses it, naming the file and the configuration to declare instead. */
+export function legacyClaudeConfigRefusal(contextDir) {
   let d = resolve(contextDir);
   while (true) {
     const f = join(d, "oats-claude-config");
     if (existsSync(f)) {
-      const name = readFileSync(f, "utf8").split("\n").map((l) => l.trim()).find((l) => l && !l.startsWith("#"));
-      if (name) return name;
+      let name = null;
+      try { name = readFileSync(f, "utf8").split("\n").map((l) => l.trim()).find((l) => l && !l.startsWith("#")) || null; } catch {}
+      const exe = name ? `executable: ${name}, ` : "";
+      return Object.assign(oatsError("E_CLAUDE_CONFIG_REMOVED", `${f} is no longer read (OATS 0.32): declare this machine's claude default in oats-local.yaml instead — launch-configs: { <name>: { harness: claude, ${exe}default: true } } (oats launch-config set <name> --file <json>) — then delete ${f}`), { details: { file: f, executable: name, fix: `declare a claude default launch configuration (${exe}default: true), then delete ${f}` } });
     }
     const parent = dirname(d);
-    if (parent === d) return "claude";
+    if (parent === d) return null;
     d = parent;
   }
 }
@@ -1947,11 +1987,10 @@ function verifyHarnessPackages(harness, resolved, contextDir, { bin, env } = {})
   const found = [];
   const problems = [];
   // The session launches with the SELECTED executable (a configuration's,
-  // or the context-selected one: oats-claude-config may name
-  // `claude-personal`), so probing another binary would inspect a different
+  // the host's harness default included), so probing another binary would inspect a different
   // account's packages than the instance will actually use. The probe is the
   // manager's controlled list subcommand; no launch argument is added to it.
-  const probeOpts = { context: contextDir, ...(bin ? { bin } : harness === "claude" ? { bin: resolveClaudeBinary(contextDir) } : {}) };
+  const probeOpts = { context: contextDir, ...(bin ? { bin } : {}) };
   for (const cap of resolved.capabilities || []) {
     for (const raw of cap.manifest?.requires || []) {
       if (!raw || typeof raw !== "object") continue;
@@ -2045,8 +2084,10 @@ const LAUNCH_PROMPT = { kind: "task-file", file: "TASK.md" };
 
 /** The executable a launch uses: a configuration's declared one (a bare name
  *  on PATH; a path against the deployment directory when relative) or the
- *  harness's default (claude through oats-claude-config). Never executed. */
+ *  harness's name on PATH. Never executed. A new claude launch with a legacy `oats-claude-config` in reach
+ *  of its context is refused (E_CLAUDE_CONFIG_REMOVED, 0.32), whatever it declares. */
 export function resolveLaunchExecutable({ harness, declared, declaringDir, contextDir }) {
+  if (harness === "claude" && contextDir) { const refused = legacyClaudeConfigRefusal(contextDir); if (refused) throw refused; }
   if (declared) {
     if (declared.includes("/")) {
       const path = isAbsolute(declared) ? declared : resolve(declaringDir || contextDir, declared);
@@ -2055,10 +2096,8 @@ export function resolveLaunchExecutable({ harness, declared, declaringDir, conte
     const found = which(declared);
     return { path: found || null, declared, resolvedFrom: "PATH", missing: found ? undefined : `${declared} binary not found on PATH` };
   }
-  const claudeBin = harness === "claude" ? resolveClaudeBinary(contextDir) : undefined;
-  const name = harness === "claude" ? claudeBin : harness;
-  const found = which(name);
-  return { path: found || null, declared: null, resolvedFrom: harness === "claude" && claudeBin !== "claude" ? "oats-claude-config" : "PATH", missing: found ? undefined : `${name} binary not found on PATH${claudeBin && claudeBin !== "claude" ? " (named by oats-claude-config)" : ""}` };
+  const found = which(harness);
+  return { path: found || null, declared: null, resolvedFrom: "PATH", missing: found ? undefined : `${harness} binary not found on PATH` };
 }
 /** null when `path` is a regular executable file; otherwise why not. */
 export function checkLaunchExecutable(path) {
@@ -2093,7 +2132,7 @@ export function resolveLaunchSelection({ launchConfigs = {}, agent, frozen, sele
     // applies the current definition.
     // Named or not: the recorded executable (a saved wrapper, say), args and
     // env are what runs; later edits of the scope never change it.
-    config = { name: frozen.launchConfig || null, harness: frozen.harness, ...(frozen.executableDeclared ? { executable: frozen.executableDeclared } : {}), executablePath: frozen.executable, args: [...(frozen.args || [])], env: { ...(frozen.env || {}) }, ...(frozen.model ? { model: frozen.model } : {}), ...(frozen.yolo !== undefined ? { yolo: frozen.yolo } : {}), source: frozen.launchConfigSource || null, frozen: true };
+    config = { name: frozen.launchConfig || null, harness: frozen.harness, ...(frozen.executableDeclared ? { executable: frozen.executableDeclared } : {}), executablePath: frozen.executable, args: [...(frozen.args || [])], env: { ...(frozen.env || {}) }, ...(frozen.model ? { model: frozen.model } : {}), ...(frozen.yolo !== undefined ? { yolo: frozen.yolo } : {}), source: frozen.launchConfigSource || null, ...(frozen.launchConfigDefault === true ? { harnessDefault: true } : {}), frozen: true };
     wanted = "none";
   }
   if (wanted === undefined) wanted = frozen ? "none" : (agent?.["launch-config"] || "none");
@@ -2106,6 +2145,9 @@ export function resolveLaunchSelection({ launchConfigs = {}, agent, frozen, sele
   // host default would: below the flags and a selected configuration.
   const harness = config?.harness || selection.harness || (frozen ? frozen.harness : preference?.harness || agent?.harness || "pi");
   if (!LAUNCH_HARNESSES.includes(harness)) bad("E_UNSUPPORTED_HARNESS", `unknown harness "${harness}" (pi|claude|codex)`);
+  // 0.32 (feature launch-config-default): a launch that selected no configuration runs this host's default
+  // for its harness, if one is declared. An explicit `--launch-config none` asks for the bare harness.
+  const harnessDefault = !config && !(selection.launchConfig === "none" && !preference) ? harnessDefaultConfig(launchConfigs, harness) : null;
   let model, modelSource;
   // K6: an EXPLICIT "use the harness's native default" is distinct from an
   // omitted model (which inherits the configuration's or soul's preference).
@@ -2131,8 +2173,19 @@ export function resolveLaunchSelection({ launchConfigs = {}, agent, frozen, sele
     // is no proof it fits another one. Nothing is passed across.
     model = ""; modelSource = "native default (harness differs from the soul's)";
   } else { model = resolveModelPreference(agent?.model || "", harness); modelSource = model ? "soul default" : "native default"; }
+  // The harness default's model is the last fallback: below every layer that names one, above the harness's own.
+  if (harnessDefault?.model && !model && !nativeDefault) {
+    model = resolveModelPreference(harnessDefault.model, harness); modelSource = `launch-config ${harnessDefault.name}`;
+    if (!model) bad("E_MODEL_UNKNOWN", `launch configuration ${harnessDefault.name} (the ${harness} default) names model ${JSON.stringify(harnessDefault.model)}, which has no entry usable by harness ${harness}`);
+  }
+  if (harnessDefault) config = harnessDefault;
   return { config, harness, model, modelSource, configuredYolo: config?.yolo };
 }
+/** This host's default launch configuration for `harness` (`default: true`), marked `harnessDefault`, or null. */
+export function harnessDefaultConfig(launchConfigs, harness) {
+  const found = Object.values(launchConfigs || {}).find((c) => c?.default === true && c.harness === harness);
+  return found ? { ...found, harnessDefault: true } : null;
+}
 /** A home's launch layers now (feature launch-preference; --reselect-launch and inspect's launchCurrent): its
  *  RECORDED soul's launch (the soul copy it runs) and its deployment's oats-local.yaml souls.launch. */
 export function homeLaunchLayers(realHome, meta) {
@@ -2172,7 +2225,11 @@ export function launchReportFor({ layers, launchConfigs = {}, contextDir }) {
     if (!Object.hasOwn(launchConfigs, name)) { const e = launchConfigUnknown({ name, from: choice.from, at: choice.at }); return report("pi", null, null, { code: e.code, message: e.message, fix: `declare launch configuration ${name} (oats launch-config set), or change oats-local.yaml souls.launch` }); }
     config = launchConfigs[name]; harness = config.harness; model = typeof config.model === "string" && config.model ? config.model : null;
   } else if (choice.preference) { harness = choice.preference.harness; model = choice.preference.model ?? null; }
-  const exe = resolveLaunchExecutable({ harness, declared: config?.executable, declaringDir: config?.source, contextDir });
+  // As a spawn: a layer naming "none" asks for the bare harness; otherwise no configuration is the harness default.
+  if (!config && !(choice.selection.launchConfig === "none" && !choice.preference)) { config = harnessDefaultConfig(launchConfigs, harness); if (config && !model) model = typeof config.model === "string" && config.model ? config.model : null; }
+  let exe;
+  try { exe = resolveLaunchExecutable({ harness, declared: config?.executable, declaringDir: config?.source, contextDir }); }
+  catch (e) { if (e?.code !== "E_CLAUDE_CONFIG_REMOVED") throw e; return report(harness, model, config?.name, { code: e.code, message: e.message, fix: `declare a claude default launch configuration (oats launch-config set), then delete ${e.details.file}` }); }
   if (!exe.path && !config?.executable) { const e = harnessUnavailable({ harness, from: choice.from, at: choice.at, why: exe.missing }); return report(harness, model, config?.name, { code: e.code, message: e.message, fix: e.details.fix }); }
   if (!exe.path) return report(harness, model, config.name, { code: "E_LAUNCH_EXECUTABLE", message: `launch configuration ${config.name}: ${exe.missing}`, fix: `fix the executable of launch configuration ${config.name} (oats launch-config set)` });
   return report(harness, model, config?.name);
@@ -2182,14 +2239,13 @@ export function launchReportFor({ layers, launchConfigs = {}, contextDir }) {
  *  name: the command says NAME="$OATS_LAUNCH_REF_NAME", so no source
  *  variable is ever named in the command and no assignment in the same
  *  prefix can shadow it (zsh evaluates a prefix's assignments in order).
- *  Rendered as tmux `-e` flags or a shell export prefix. */
+ *  Rendered as tmux `-e` flags. */
 export function launchEnvRefs(recipe, env = process.env) {
   const out = [];
   for (const [name, v] of Object.entries(recipe.env || {})) if (v && typeof v === "object" && v.fromEnv && env[v.fromEnv] !== undefined) out.push({ name: `${LAUNCH_REF_PREFIX}${name}`, value: env[v.fromEnv], target: name, source: v.fromEnv });
   return out;
 }
 export function launchEnvTmuxFlags(recipe, env) { return launchEnvRefs(recipe, env).map((r) => ` -e ${shq(`${r.name}=${r.value}`)}`).join(""); }
-export function launchEnvExports(recipe, env) { return launchEnvRefs(recipe, env).map((r) => `export ${r.name}=${shq(r.value)}; `).join(""); }
 
 /** The canonical path of this kernel's CLI: what the home's shim points at, and OATS_CLI_BIN. */
 export function kernelBin() { return realpathSync(join(PKG_ROOT, "bin", "oats.mjs")); }
@@ -2351,7 +2407,10 @@ export function planLaunch({ home, instance, meta, contextDir, agentLike, select
     if (selection.launchConfig !== undefined || selection.harness !== undefined) launchChoice = { from: "flag", at: null, declared: meta?.launchDeclared ?? null };
   }
   const { config, harness, model, modelSource } = chosen;
-  const yolo = resolveYolo(selection.yolo ?? chosen.configuredYolo ?? (frozen ? frozen.yolo : agentLike?.yolo ?? resolvedCfg?.yolo));
+  // A recorded yolo that came from a harness default belongs to that default: it never carries into a launch
+  // the default no longer decides (a bare --launch-config none, another harness).
+  const frozenYolo = frozen && !(frozen.launchConfigDefault === true && !config?.frozen) ? frozen.yolo : undefined;
+  const yolo = resolveYolo(selection.yolo ?? chosen.configuredYolo ?? (frozen ? frozenYolo : agentLike?.yolo ?? resolvedCfg?.yolo));
   const executable = config?.frozen
     ? { path: config.executablePath, declared: frozen.executableDeclared ?? null, resolvedFrom: frozen.executableResolvedFrom || "recorded", missing: existsSync(config.executablePath) ? undefined : `${config.executablePath} (recorded) does not exist` }
     : resolveLaunchExecutable({ harness, declared: config?.executable, declaringDir: config?.source, contextDir });
@@ -2419,7 +2478,7 @@ export function planLaunch({ home, instance, meta, contextDir, agentLike, select
     } else problems.push({ check: "harness-packages", ok: true, detail: "no harness package requirement declared for this harness; nothing probed" });
   }
   const recipe = {
-    version: LAUNCH_RECIPE_VERSION, harness, launchConfig: config?.name || null, launchConfigSource: config?.source || null,
+    version: LAUNCH_RECIPE_VERSION, harness, launchConfig: config?.name || null, launchConfigSource: config?.source || null, ...(config?.harnessDefault ? { launchConfigDefault: true } : {}),
     executable: executable.path || executable.declared || harness, executableDeclared: executable.declared ?? null, executableResolvedFrom: executable.resolvedFrom,
     args: [...(config?.args || [])], env: { ...configEnv }, model: model || null, ...(yolo !== undefined ? { yolo } : {}),
     hooks: frozen ? { launch: hooks.launch, env: hooks.env, contributions: hooks.contributions } : hooks, prompt: LAUNCH_PROMPT, kernelBin: kernelBin(),
@@ -2510,10 +2569,11 @@ function* spawnBody(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`);
   if (o.launchConfig !== undefined && (typeof o.launchConfig !== "string" || !o.launchConfig.trim())) throw oatsError("E_BAD_ARGS", "launchConfig must be a configuration name or none");
-  const session = o.tmuxSession || DEFAULT_TMUX_SESSION;
+  const { tmuxSession: session } = sessionDefaults(root, { tmuxSession: o.tmuxSession });
   const backend = o.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");
+  if (backend === "herdr") throw herdrSettingRemoved("backend herdr was given");
+  if (o.herdrSocket !== undefined) throw herdrSettingRemoved("herdrSocket was given");
+  if (backend !== "tmux") throw new Error(`unknown session backend "${backend}" (tmux)`);
   const launch = o.launch !== false;
   // Workspace model (`o.prepared`) + work: workspace: ./work is the deployment
   // boundary — the directory holding oats-local.yaml (`prepared.deployment`), which
@@ -2592,8 +2652,8 @@ function* spawnBody(root, agent, o = {}) {
   }
 
   // An explicit name may not be a soul name (soul and instance references stay
-  // unambiguous) and is taken when any soul of this deployment holds it, or — on
-  // the tmux backend, launched or not — a live window of the session carries it:
+  // unambiguous) and is taken when any soul of this deployment holds it, or — launched
+  // or not — a live tmux window of the session carries it:
   // a typed refusal, never a silent `-2` (the operator typed it). Checked after
   // key recovery, so a retried keyed spawn still reaches its own receipt; the
   // placement below re-checks after its reservation (a concurrent spawn of
@@ -2602,7 +2662,7 @@ function* spawnBody(root, agent, o = {}) {
     if (deploymentSoulNames(root, o.prepared).has(instance)) throw oatsError("E_INSTANCE_NAME_INVALID", `instance name "${instance}" is a soul name in this deployment; an instance may not share a soul's name`);
     const holder = deploymentInstanceHomes(root).get(instance)?.[0];
     if (holder) throw Object.assign(oatsError("E_INSTANCE_NAME_TAKEN", `instance name "${instance}" is taken in this deployment (${holder}); instance names are unique across every soul — pick another --name`), { instance, home: holder });
-    if (backend === "tmux" && tmuxWindows(session).includes(instance)) throw Object.assign(oatsError("E_INSTANCE_NAME_TAKEN", `instance name "${instance}" is taken: a live tmux window of that name exists in session ${session} — pick another --name`), { instance, session });
+    if (tmuxWindows(session).includes(instance)) throw Object.assign(oatsError("E_INSTANCE_NAME_TAKEN", `instance name "${instance}" is taken: a live tmux window of that name exists in session ${session} — pick another --name`), { instance, session });
   }
 
   // Forward-only lineage: EXPLICIT only. Relations (child|sibling|parent|unrelated)
@@ -2903,10 +2963,6 @@ function* spawnBody(root, agent, o = {}) {
   // spawn hooks run, which happens after the home exists.
   if ((launchConfig?.args || []).length && applicableRequirements(harness, resolvedCfg.capabilities).length) throw oatsError("E_LAUNCH_PROBE_UNSUPPORTED", `${requirementsWithArgsMessage(harness, resolvedCfg.capabilities, launchConfig)}; nothing was created`);
   const harnessPackages = verifyHarnessPackages(harness, resolvedCfg, repoAbs, { ...(launchConfig?.executable ? { bin } : {}), env: launchEffectiveEnv({ base: process.env, configEnv: launchConfig?.env || {} }) });
-  // Backend presence/startup (ensureHerdr) happens AFTER the decision fence
-  // and the exclusive placement reservation below — a stale or losing apply
-  // must not start a daemon. Preview never starts one either.
-  let herdrBase;
   if (o.preview === true) { preflight = { status: previewPreflightBudget?.exhausted ? "timeout" : "complete", budgetMs: preflightBudgetMs, elapsedMs: Date.now() - preflightStarted }; previewPreflightBudget = null; }
   const task = o.task ?? (o.taskFile ? readFileSync(o.taskFile, "utf8") : "");
 
@@ -2974,7 +3030,7 @@ function* spawnBody(root, agent, o = {}) {
       subject: o.subject ?? { soul: agent.name, agentsRoot: root, context: null },
       decision, preflight,
       backendStatus: launch ? { name: backend, installed: !!which(backend), started: false } : null,
-      harness, model: model || null, modelSource: launchSelection.modelSource ?? null, launchConfig: launchConfig?.name ?? null, yolo, backend,
+      harness, model: model || null, modelSource: launchSelection.modelSource ?? null, launchConfig: launchConfig?.name ?? null, launchConfigDefault: launchConfig?.harnessDefault === true, yolo, backend,
       launch: launchReport({ declared: launchChoice.declared, harness, model, launchConfig: launchConfig?.name, from: launchChoice.from, at: launchChoice.at }),
       branch: plannedBranch, base: plannedBase, worktree: work === "worktree" ? join(home, "work") : null,
       relation: relation || null, parentInstance: parentInstance && parentInstance !== instance ? parentInstance : null,
@@ -2991,11 +3047,9 @@ function* spawnBody(root, agent, o = {}) {
     if (fresh.revision !== o.expectDecision) throw Object.assign(oatsError("E_DECISION_STALE", `the previewed decision changed (${o.expectDecision} → ${fresh.revision}): ${fresh.instance}${plannedBase ? ` from ${plannedBase.ref}@${plannedBase.oid.slice(0, 12)}` : ""}; preview again`), { decision: fresh });
   }
   // Backend PRESENCE is a prerequisite, checked before anything is placed (M1):
-  // an absent tmux/herdr binary must fail with nothing created, never after a
-  // populated home exists. Backend STARTUP (ensureHerdr) still waits for the
-  // bound decision and the exclusive placement below — a stale or losing apply
-  // must not start a daemon.
-  if (launch && !which(backend)) throw new Error(`${backend} not installed${backend === "tmux" ? " (brew install tmux)" : " (https://herdr.dev)"}; nothing was created`);
+  // an absent tmux binary must fail with nothing created, never after a
+  // populated home exists.
+  if (launch && !which(backend)) throw new Error(`${backend} not installed (brew install tmux); nothing was created`);
   // Exclusive placement reservation: the parent may be created, the home
   // itself never with `recursive` — EEXIST means another spawn (a concurrent
   // apply of the same decision, or anything else) got here first, and this one
@@ -3101,10 +3155,6 @@ function* spawnBody(root, agent, o = {}) {
       }
     } catch (e) { throw rollbackEmptyOrPreparedHome(e); }
   }
-  // Backend startup only now — the decision is bound and the placement is ours.
-  try { herdrBase = launch && backend === "herdr" ? ensureHerdr({ binary: which("herdr"), socket: o.herdrSocket }) : undefined; }
-  catch (e) { throw rollbackEmptyOrPreparedHome(e); }
-
   initializeNativeHistory(home);
 
   // Body: instructions are a generated instance-local view; the home carries no soul
@@ -3330,7 +3380,6 @@ function* spawnBody(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
@@ -3350,23 +3399,7 @@ function* spawnBody(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 harness may be using.
-    if (windowMayExist && spawnHerdr) {
-      try { stopHerdr(spawnHerdr); }
-      catch (e) {
-        incomplete.push(`Herdr session: ${e.message}`);
-        for (const cap of resolvedCfg.capabilities) if (cap.hooks?.retire) outstandingHooks.add(cap.id);
-        if (work === "worktree") { outstandingGit.add("worktree"); if (branch) outstandingGit.add("branch"); }
-        return quarantineInstanceHome({ home, instance, agent, soulDir: homeSoulTarget, soulId: preparedSoulId, incomplete, failed, outstandingHooks, outstandingGit,
-          repoAbs, work, branch, resolvedCfg, hookMeta: hookRes.meta || {},
-          launched: true, sessionTarget: spawnHerdr, directoryHome: homeReal, 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") {
+    if (windowMayExist) {
       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);
@@ -3536,7 +3569,7 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
     const shimTarget = writeKernelShim(home);
     const recipe = {
       version: LAUNCH_RECIPE_VERSION, harness,
-      launchConfig: launchConfig?.name || null, launchConfigSource: launchConfig?.source || null,
+      launchConfig: launchConfig?.name || null, launchConfigSource: launchConfig?.source || null, ...(launchConfig?.harnessDefault ? { launchConfigDefault: true } : {}),
       executable: bin, executableDeclared: executable.declared, executableResolvedFrom: executable.resolvedFrom,
       args: [...(launchConfig?.args || [])], env: { ...(launchConfig?.env || {}) },
       model: model || null, ...(yolo !== undefined ? { yolo } : {}),
@@ -3622,7 +3655,7 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
         missingRequires: cap.missingRequires, trust: cap.trust,
         executable: cap.executable,
       })),
-      ...(backend === "herdr" ? { backend } : { tmux: { session, window: instance } }),
+      tmux: { session, window: instance },
       launch: recipe, command: cmdline, createdAt: new Date().toISOString(),
     };
     // Workspace model: materialize recorded modules/providers (and the module
@@ -3644,16 +3677,7 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
     spawnTmux = meta.tmux;
     if (work === "directory") assertDirectoryRoots(home, homeReal);
     const executionCommand = launch ? nativeRecordCommand(cmdline, home, harness) : null;
-    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, resolvedCfg.capabilities, { launched: true, sessionTarget: spawnHerdr });
-      try { launchHerdr(spawnHerdr, `${launchEnvExports(recipe, process.env)}${executionCommand}`); }
-      catch (e) { throw oatsError("E_SPAWN_LAUNCH_FAILED", `Herdr could not run the launch command for ${instance} (${e.code === "ENOENT" ? "herdr unavailable" : "pane run failed"}); the command line is withheld from this message`); }
-    } else if (launch) {
+    if (launch) {
       if (!tmuxAlive(session)) {
         const hq = existsSync(root) ? root : workspaceOf(root);
         sh(`tmux new-session -d -s ${shq(session)} -n hq -c ${shq(hq)}`);
@@ -3715,7 +3739,7 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
       meta.spawnCompleted = true;
       writeFileSync(join(home, "instance.json"), JSON.stringify(meta, null, 2) + "\n"); // a kernel-owned field: the baseline fingerprint ignores it
     }
-    return deliver({ ...meta, ...(o.expectDecision !== undefined ? { replayed: false } : {}), launch: redactLaunchRecipe(recipe), command: redactLaunchCommand(cmdline), 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 });
+    return deliver({ ...meta, ...(o.expectDecision !== undefined ? { replayed: false } : {}), launch: redactLaunchRecipe(recipe), command: redactLaunchCommand(cmdline), attach: `tmux attach -t ${session}`, warnings: spawnWarnings.length ? spawnWarnings : undefined });
   } catch (error) {
     const note = compensateSpawn();
     error.message += note;
@@ -3742,8 +3766,29 @@ export function servedIdentityLine(identity) {
   if (identity.mode === "global" && identity.grant) return `acts as ${identity.address || identity.alias || identity.resident || "?"} via grant${identity.grant.expiresAt ? `, expires ${identity.grant.expiresAt}` : ""}`;
   return `alias ${identity.alias || "?"} on ${identity.team || "?"}`;
 }
+/** The window names of `session` on the tmux server at `socket`: `{ windows }`, empty when the server
+ *  or the session is gone; `{ error }` when the server could not be read. */
+function recordedTmuxWindows(socket, session) {
+  try { return { windows: tmuxOn(socket, ["list-windows", "-t", `=${session}`, "-F", "#{window_name}"]).split("\n").filter(Boolean) }; }
+  catch (e) {
+    if (tmuxServerLost(e) || /can't find session/i.test(String(e.stderr ?? ""))) return { windows: [] };
+    return { error: String(e.stderr ?? e.message ?? "").trim() || "tmux list-windows failed" };
+  }
+}
+/** A status row's liveness from its session's windows: unknown (not false) when the server could not be read. */
+function tmuxLiveness({ windows, error }, window) {
+  return error ? { running: null, runtimeState: "unreachable", runtimeError: error } : { running: windows.includes(window) };
+}
 export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION) {
-  const windows = tmuxWindows(tmuxSession);
+  // Liveness reads each home's RECORDED endpoint (a pre-0.31 home records pi-agents): the recorded
+  // socket, never the ambient $TMUX server, once per socket and session per call, so status costs no
+  // more child processes as homes grow. A home without a recorded socket reads the default server.
+  const tmuxByEndpoint = new Map();
+  const windowsOf = (session, socket) => {
+    const key = JSON.stringify([socket ?? null, session]);
+    if (!tmuxByEndpoint.has(key)) tmuxByEndpoint.set(key, socket ? recordedTmuxWindows(socket, session) : { windows: tmuxWindows(session) });
+    return tmuxByEndpoint.get(key);
+  };
   const readInstancesOf = (agentDir) => {
     const instancesDir = join(agentDir, "instances");
     // An instance name starts with a letter or digit (INSTANCE_NAME_RE); a
@@ -3775,11 +3820,10 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION) {
           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 }; }
-        }
+        // A home opened in Herdr (removed in 0.31.0) is listed, never observed: its row says so.
+        const liveness = recordsHerdr(meta, readJsonOrUndefined(retirementBaselinePath(home)))
+          ? { running: null, runtimeState: "unsupported", runtimeError: `E_HERDR_REMOVED: ${herdrInstanceRemoved(e.name).message}` }
+          : tmuxLiveness(windowsOf(meta.tmux?.session || tmuxSession, meta.tmux?.socket), meta.tmux?.window || meta.instance || e.name);
         const identity = servedIdentityOf(meta);
         // Feature desktop-facts: `startedAt` — the last session start or restart (the receipt's restarts[]),
         // else the spawn's own launch (createdAt), else null (never launched); `identityAddress` — the
@@ -3960,7 +4004,7 @@ function sessionDirectoryGuard(home) {
 
 /** 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, soulDir, soulId, incomplete, failed, outstandingHooks, outstandingGit, repoAbs, work, branch, resolvedCfg, hookMeta, compensationMeta, launched, tmux, sessionTarget, recordRetirementBaseline = false, reason, directoryPreservation = false, directoryHome = realPathOrNearest(home) }) {
+function quarantineInstanceHome({ home, instance, agent, soulDir, soulId, incomplete, failed, outstandingHooks, outstandingGit, repoAbs, work, branch, resolvedCfg, hookMeta, compensationMeta, launched, tmux, recordRetirementBaseline = false, reason, directoryPreservation = false, directoryHome = realPathOrNearest(home) }) {
   const marker = {
       // `reason` is optional and DEFAULTS to the spawn wording, so every existing
       // caller is byte-identical; only a caller that supplies one differs. The
@@ -3980,7 +4024,6 @@ function quarantineInstanceHome({ home, instance, agent, soulDir, soulId, incomp
         // instance.json may be only the pre-hook stub, which records neither.
         ...(typeof soulDir === "string" && soulDir ? { soulDir } : {}),
         ...(typeof soulId === "string" && soulId ? { soulId } : {}),
-        ...(sessionTarget ? { sessionTarget } : {}),
         outstanding: { hooks: [...outstandingHooks], git: [...outstandingGit], ...(directoryPreservation ? { directory: true } : {}) },
         capabilityRuntime: (resolvedCfg.capabilities || []).map((cap) => ({
           id: cap.id, layer: cap.layer, level: cap.level, settings: cap.settings, settingsOrigins: cap.settingsOrigins ?? {},
@@ -4014,7 +4057,7 @@ function quarantineInstanceHome({ home, instance, agent, soulDir, soulId, incomp
   if (recordRetirementBaseline) {
     try {
       if (work === "directory") assertDirectoryRoots(home, directoryHome);
-      writeRetirementBaseline(home, join(home, "work"), work, resolvedCfg.capabilities || [], { launched: launched === true, tmux, sessionTarget });
+      writeRetirementBaseline(home, join(home, "work"), work, resolvedCfg.capabilities || [], { launched: launched === true, tmux });
     } catch (e) {
       incomplete.push(`independent retirement authority: ${e.message}`);
     }
@@ -4243,7 +4286,6 @@ function writeRetirementBaseline(home, work, mode, capabilities, runtime, { excl
     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);
@@ -4286,23 +4328,40 @@ function branchOnlyCommits(repo, branch) {
   }
 }
 
+/** Herdr (removed in 0.31.0) is recognised in a home only to refuse: its instance.json records a
+ *  Herdr session target or `backend: "herdr"`, or its independent receipt records a session target
+ *  (a tmux receipt never does). Either source is enough. */
+function recordsHerdr(meta, baseline) {
+  return (isPlainObject(meta) && (meta.sessionTarget !== undefined || meta.backend === "herdr"))
+    || (isPlainObject(baseline?.runtime) && baseline.runtime.sessionTarget !== undefined);
+}
+function readJsonOrUndefined(path) { try { return JSON.parse(readFileSync(path, "utf8")); } catch { return undefined; } }
+/** Refuse any session operation on a home opened in Herdr, from its files as they are (either may be
+ *  missing or unreadable): before any receipt validation, so the refusal is never an endpoint error. */
+function refuseHerdrHome(home) {
+  if (recordsHerdr(readJsonOrUndefined(join(home, "instance.json")), readJsonOrUndefined(retirementBaselinePath(home)))) throw herdrInstanceRemoved(basename(home));
+}
+
 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 };
-  }
+  if (runtime.sessionTarget !== undefined) return undefined;
   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) } };
 }
 
+/** instance.json's tmux endpoint is the one the independent receipt authorises. */
+function tmuxEndpointAgrees(meta, authority) {
+  return meta.tmux?.session === authority.tmux?.session && meta.tmux?.window === authority.tmux?.window && resolve(meta.tmux?.socket || ".") === authority.tmux?.socket;
+}
+
 /** Session control uses the independent endpoint receipt. */
 function instanceSessionTarget(home) {
   if (typeof home !== "string" || !isAbsolute(home)) throw oatsError("E_BAD_ARGS", "session needs an absolute instance home");
   home = realPathOrNearest(home);
+  refuseHerdrHome(home);
   let baseline, meta;
   try {
     baseline = JSON.parse(readFileSync(retirementBaselinePath(home), "utf8"));
@@ -4310,11 +4369,8 @@ function instanceSessionTarget(home) {
   } 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 };
+  if (meta.launched !== authority.launched || (authority.launched && !tmuxEndpointAgrees(meta, authority))) throw oatsError("E_RUNTIME_AUTHORITY_MISMATCH", "instance metadata disagrees with independent session receipt");
+  return { home, target: authority.launched ? { backend: "tmux", ...authority.tmux } : undefined };
 }
 
 export function inspectInstanceSession(home) {
@@ -4371,7 +4427,7 @@ export function processesInHome(home, io) {
  * AND no live process on the host works in the home (a harness started by
  * hand on another server is invisible to the recorded endpoint).
  * Anything else (the window is there, a pane or a process works in the home,
- * the process scan cannot run, a Herdr target, a launch without an endpoint,
+ * the process scan cannot run, a launch without an endpoint,
  * tmux failing otherwise) is `{ absent: false, note }`: live or ambiguous,
  * never killed on mutable metadata.
  */
@@ -4385,7 +4441,6 @@ export function observeSessionWithoutReceipt(home, meta, io) {
 }
 function recordedSessionAbsence(home, meta, io) {
   const tmux = meta?.tmux;
-  if (meta?.sessionTarget) return { absent: false, backend: "herdr", note: "instance.json records a Herdr session, which cannot be observed without the receipt" };
   // A --no-launch home keeps its planned tmux names with `launched: false`: nothing was started there.
   if (meta?.launched !== true) return { absent: true, backend: null, note: "no session receipt (a home from before 0.25.9); instance.json records no launch" };
   if (!tmux) return { absent: false, backend: null, note: "instance.json records a launch but no session endpoint" };
@@ -4412,7 +4467,7 @@ export function stopInstanceSession(home, o = {}) {
   if (!s.target) return { home: s.home, backend: null, stopped: false, alreadyIdle: true, state: "not-launched", receipt: null };
   let before;
   try { before = inspectSessionTarget(s.target); }
-  catch (e) { if (s.target.backend === "tmux" && tmuxServerLost(e)) before = { present: false, state: "stopped" }; else throw oatsError("E_SESSION_UNAVAILABLE", `cannot establish whether ${basename(realHome)} is running, so nothing was stopped: ${e.message}`); }
+  catch (e) { if (tmuxServerLost(e)) before = { present: false, state: "stopped" }; else throw oatsError("E_SESSION_UNAVAILABLE", `cannot establish whether ${basename(realHome)} is running, so nothing was stopped: ${e.message}`); }
   if (!before.present || before.state === "shell" || before.state === "stopped") return { home: s.home, backend: s.target.backend, stopped: false, alreadyIdle: true, state: before.state, receipt: null };
   const receipt = stopHarness(s.target, { graceMs: o.graceMs ?? 20000, kill: o.io?.kill, sleep: o.io?.sleep });
   writeJsonAtomic(join(realHome, ".oats-stop.json"), { instance: basename(realHome), at: new Date().toISOString(), stop: receipt, retained: ["home", "work", "transcript", "launch"] });
@@ -4539,53 +4594,16 @@ function writeJsonAtomic(path, value, mode) {
 }
 
 // ---------- stopping a harness, selecting on an existing home ----------
-const SHELL_NAMES = new Set(["sh", "bash", "zsh", "fish", "dash", "ksh", "tcsh", "csh", "login"]);
-/** The harness processes under a session target: for tmux EVERY descendant
+/** The harness processes under a tmux session target: EVERY descendant
  *  of the pane's launcher process (the launcher shell itself is left so
  *  that, once its command ends, it becomes the fallback shell the start
  *  path recognizes); a wrapper that does not exec the harness, the harness
- *  and their children are all included, topmost first. For Herdr the
- *  pane's foreground processes. Each row: { pid, ppid, pgid, comm, depth }. */
+ *  and their children are all included, topmost first. Each row:
+ *  { pid, ppid, pgid, comm, depth }. */
 export function harnessProcesses(target, io) {
   const ps = () => ((io?.exec || execFileSync)("ps", ["-axo", "pid=,ppid=,pgid=,comm="], { encoding: "utf8", timeout: 10000, maxBuffer: 4 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] }))
     .split("\n").map((l) => l.trim().match(/^(\d+)\s+(\d+)\s+(\d+)\s+(.+)$/)).filter(Boolean)
     .map(([, pid, ppid, pgid, comm]) => ({ pid: Number(pid), ppid: Number(ppid), pgid: Number(pgid), comm: basename(comm).replace(/^-/, "") }));
-  if (target.backend === "herdr") {
-    // Herdr's PaneProcessInfo (installed schema: shell_pid, nullable;
-    // foreground_process_group_id; foreground_processes) names the pane's
-    // shell. That pid, verified against this host, is the root: OATS launched
-    // `exec /bin/sh -c <command>` in it, so the root is the launcher shell
-    // and the harness its child, exactly as under tmux; a root whose exec
-    // replaced it with a non-shell IS the harness and is included. Without a
-    // shell_pid, the verified non-shell foreground processes are the roots.
-    // Never a fabricated row: an unverifiable pid refuses before any signal.
-    const info = herdrCommand(target, ["pane", "process-info", "--pane", target.paneId], io).process_info;
-    if (!info || typeof info !== "object") throw oatsError("E_SESSION_UNKNOWN", "Herdr returned no process information for the pane");
-    const rows = ps();
-    const byParent = new Map();
-    for (const r of rows) { if (!byParent.has(r.ppid)) byParent.set(r.ppid, []); byParent.get(r.ppid).push(r); }
-    const out = [];
-    const walk = (pid, depth) => { for (const child of byParent.get(pid) || []) { if (!out.some((o) => o.pid === child.pid)) { out.push({ ...child, depth }); walk(child.pid, depth + 1); } } };
-    const verified = (pid, what) => {
-      if (!Number.isInteger(pid) || pid <= 0) throw oatsError("E_SESSION_UNKNOWN", `Herdr reported ${what} without a verifiable pid; nothing was signalled`);
-      const row = rows.find((r) => r.pid === pid);
-      if (!row) throw oatsError("E_SESSION_UNKNOWN", `Herdr reports ${what} pid ${pid} but this host has no such process; nothing was signalled`);
-      return row;
-    };
-    if (info.shell_pid !== null && info.shell_pid !== undefined) {
-      const root = verified(info.shell_pid, "the pane shell");
-      if (!SHELL_NAMES.has(root.comm)) out.push({ ...root, depth: 0 });
-      walk(root.pid, 1);
-      return out;
-    }
-    if (!Array.isArray(info.foreground_processes)) throw oatsError("E_SESSION_UNKNOWN", "Herdr returned neither a pane shell pid nor foreground processes");
-    for (const p of info.foreground_processes) {
-      const row = verified(p.pid, `foreground process ${p.name || "?"}`);
-      if (SHELL_NAMES.has(row.comm)) { walk(row.pid, 1); continue; }
-      if (!out.some((o) => o.pid === row.pid)) { out.push({ ...row, depth: 0 }); walk(row.pid, 1); }
-    }
-    return out;
-  }
   const row = tmuxOn(target.socket, ["list-panes", "-t", `=${target.session}:=${target.window}`, "-F", "#{pane_pid}"], io).trim().split("\n")[0];
   if (!/^\d+$/.test(row || "")) throw oatsError("E_SESSION_UNKNOWN", "tmux returned no pane process id");
   const panePid = Number(row);
@@ -4753,6 +4771,10 @@ export function preWorkspaceHome(home, what) {
 }
 export function startInstanceSession(home, o = {}) {
   if (typeof home !== "string" || !isAbsolute(home)) throw oatsError("E_BAD_ARGS", "session start needs an absolute instance home");
+  // A home opened in Herdr, or an earlier start that allocated a Herdr pane, is refused before any
+  // guard or receipt reads it.
+  refuseHerdrHome(realPathOrNearest(home));
+  if (readJsonOrUndefined(join(realPathOrNearest(home), ".oats-start-pending.json"))?.target?.backend === "herdr") throw herdrInstanceRemoved(basename(realPathOrNearest(home)));
   if (existsSync(directoryRollbackPath(home))) throw oatsError("E_INSTANCE_RETIRING", `${home} has retained directory cleanup; restore and retire it before starting anything there`);
   const directoryGuard = sessionDirectoryGuard(home);
   {
@@ -4777,25 +4799,23 @@ export function startInstanceSession(home, o = {}) {
   // re-resolve it against. Retire still works on it.
   if (!isWorkspaceHome(readMeta())) throw preWorkspaceHome(realHome, "nothing was started");
   const lostTmuxServer = tmuxServerLost;
-  const launchFailure = (backend, error) => {
+  const launchFailure = (error) => {
     // execFileSync errors embed argv (including capability environment) in
     // message; backend stderr can echo it too. Neither belongs in the API.
     const reason = error.code === "ENOENT" ? "backend executable unavailable"
       : error.code === "ETIMEDOUT" || error.signal === "SIGTERM" ? "backend command timed out" : "backend command failed";
-    return oatsError("E_SESSION_START_FAILED", `${backend} start of ${basename(realHome)} could not be confirmed (${reason}); inspect the recorded session before retrying. Launch evidence is retained in ${pendingPath}`);
+    return oatsError("E_SESSION_START_FAILED", `tmux start of ${basename(realHome)} could not be confirmed (${reason}); inspect the recorded session before retrying. Launch evidence is retained in ${pendingPath}`);
   };
   // The independent receipt first (retire and session consult it), then the
   // mutable metadata; both tmp+rename. A failure between them is what the
   // pending receipt exists for.
-  const record = (meta, { id, backend, target, model, command, startedAt, reused, launch, harness: newHarness, yolo: newYolo, stop, nativeRecordId, hookMeta, modelFrom, launchFrom, launchAt, launchDeclared }, clearPending = true) => {
+  const record = (meta, { id, target, model, command, startedAt, reused, launch, harness: newHarness, yolo: newYolo, stop, nativeRecordId, hookMeta, modelFrom, launchFrom, launchAt, launchDeclared }, clearPending = true) => {
     checkRoots();
     const baselinePath = retirementBaselinePath(realHome);
     let baseline;
     try { baseline = JSON.parse(readFileSync(baselinePath, "utf8")); } catch (e) { throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `independent session receipt is missing or unreadable for ${realHome}: ${e.message}`); }
     if (baseline.version !== RETIRE_BASELINE_VERSION || baseline.home !== realHome || !runtimeAuthorityOf(baseline)) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `independent session receipt is invalid for ${realHome}`);
-    baseline.runtime = backend === "herdr"
-      ? { launched: true, sessionTarget: target }
-      : { launched: true, tmux: { session: target.session, window: target.window, socket: resolve(target.socket) } };
+    baseline.runtime = { launched: true, tmux: { session: target.session, window: target.window, socket: resolve(target.socket) } };
     writeJsonAtomic(baselinePath, baseline, 0o600);
     if (o.io?.failBeforeMetadataWrite && reused !== "adopted") throw new Error("injected metadata write failure"); // the write after THIS start's allocation
     const recorded = meta.startId === id;
@@ -4807,11 +4827,10 @@ export function startInstanceSession(home, o = {}) {
       // Launch-hook meta lands per capability over the spawn's record; a hook
       // that answered without meta keeps its previous entry (retire reads it).
       ...(hookMeta ? { capabilityMeta: { ...(meta.capabilityMeta || {}), ...hookMeta } } : {}) };
-    if (backend === "herdr") { next.sessionTarget = target; delete next.tmux; }
-    else { next.tmux = { session: target.session, window: target.window, socket: resolve(target.socket) }; delete next.sessionTarget; }
+    next.tmux = { session: target.session, window: target.window, socket: resolve(target.socket) };
     writeJsonAtomic(metaPath, next);
     if (clearPending) { checkRoots(); rmSync(pendingPath, { force: true }); }
-    return { instance: meta.instance, agent: meta.agent, home: realHome, harness: next.harness, backend, model: model ?? null, launchConfig: next.launch?.launchConfig ?? null, yolo: next.yolo ?? null, target, startedAt, restartCount: next.restartCount, reused, warnings: [], ...(nativeRecordId ? { nativeRecordId } : {}), ...(stop ? { stop } : {}) };
+    return { instance: meta.instance, agent: meta.agent, home: realHome, harness: next.harness, backend: "tmux", model: model ?? null, launchConfig: next.launch?.launchConfig ?? null, yolo: next.yolo ?? null, target, startedAt, restartCount: next.restartCount, reused, warnings: [], ...(nativeRecordId ? { nativeRecordId } : {}), ...(stop ? { stop } : {}) };
   };
   try { mkdirSync(lock); }
   catch (e) {
@@ -4829,8 +4848,7 @@ export function startInstanceSession(home, o = {}) {
       let pending;
       try { pending = JSON.parse(readFileSync(pendingPath, "utf8")); } catch { pending = undefined; }
       const pt = pending?.target;
-      const validTarget = pt?.backend === "herdr" ? validHerdrTarget(pt)
-        : pt?.backend === "tmux" && [pt.session, pt.window, pt.socket].every((v) => typeof v === "string" && v.length > 0) && isAbsolute(pt.socket);
+      const validTarget = pt?.backend === "tmux" && [pt.session, pt.window, pt.socket].every((v) => typeof v === "string" && v.length > 0) && isAbsolute(pt.socket);
       let validCommand = false;
       try { parseLaunchCommand(pending?.command); validCommand = true; } catch { /* preserve invalid receipt below */ }
       let validLaunch = true;
@@ -4842,13 +4860,12 @@ export function startInstanceSession(home, o = {}) {
         && (pending.model === null || (typeof pending.model === "string" && !!pending.model.trim() && !pending.model.includes("\0")))
         && typeof pending.startedAt === "string" && Number.isFinite(Date.parse(pending.startedAt));
       if (!validReceipt) throw oatsError("E_SESSION_UNKNOWN", `an earlier start left an unreadable or invalid receipt at ${pendingPath}; inspect it before retrying; nothing was started`);
-      const pbackend = pending.target.backend === "herdr" ? "herdr" : "tmux";
       let st;
       checkRoots();
       try { st = inspectSessionTarget(pending.target, o.io); }
       catch (e) {
-        if (pbackend === "tmux" && lostTmuxServer(e)) st = { present: false, state: "stopped" };
-        else throw oatsError("E_SESSION_UNKNOWN", `an earlier start of ${basename(realHome)} recorded a session (${pbackend === "herdr" ? `Herdr pane ${pending.target.paneId}` : `tmux ${pending.target.session}:${pending.target.window} on ${pending.target.socket}`}) that cannot be observed now: ${String(e.stderr ?? e.message ?? "").trim() || e.message}; the receipt ${pendingPath} is kept and nothing was started`);
+        if (lostTmuxServer(e)) st = { present: false, state: "stopped" };
+        else throw oatsError("E_SESSION_UNKNOWN", `an earlier start of ${basename(realHome)} recorded a session (tmux ${pending.target.session}:${pending.target.window} on ${pending.target.socket}) that cannot be observed now: ${String(e.stderr ?? e.message ?? "").trim() || e.message}; the receipt ${pendingPath} is kept and nothing was started`);
       }
       // A launch may still consist entirely of shells (startup files, a
       // shell-script harness). Only its own completion marker proves this
@@ -4860,7 +4877,7 @@ export function startInstanceSession(home, o = {}) {
       // Reconcile even an exited target: the independent baseline may
       // already name it while metadata still names the old allocation.
       const meta = readMeta();
-      const done = record(meta, { ...pending, backend: pbackend, model: pending.model ?? undefined, reused: "adopted" }, !st.present || st.state === "shell");
+      const done = record(meta, { ...pending, model: pending.model ?? undefined, reused: "adopted" }, !st.present || st.state === "shell");
       if (st.present && st.state !== "shell") {
         if (o.restart) { rmSync(pendingPath, { force: true }); }
         else {
@@ -4878,7 +4895,6 @@ export function startInstanceSession(home, o = {}) {
     const meta = readMeta();
     const harness = meta.harness;
     if (!["pi", "claude", "codex"].includes(harness)) throw oatsError("E_LAUNCH_COMMAND_UNSUPPORTED", `instance ${meta.instance || realHome} records harness ${JSON.stringify(harness)}, which this kernel cannot relaunch`);
-    const backend = meta.sessionTarget || meta.backend === "herdr" ? "herdr" : "tmux";
     let command = meta.command;
     let model = meta.model || undefined;
     // What this start launches: the frozen command (optionally with another
@@ -4922,7 +4938,6 @@ export function startInstanceSession(home, o = {}) {
     if (recipeForEnv) { const missing = missingLaunchEnvRefs(recipeForEnv.env, o.env || process.env); if (missing.length) throw oatsError("E_LAUNCH_ENV_MISSING", `this home's launch references ${missing.join(", ")}, not set on this host; nothing was started`); }
     const paneEnv = recipeForEnv ? launchEnvRefs(recipeForEnv, o.env || process.env) : [];
     const paneEnvFlags = paneEnv.flatMap((r) => ["-e", `${r.name}=${r.value}`]);
-    const paneEnvExports = paneEnv.map((r) => `export ${r.name}=${shq(r.value)}; `).join("");
     checkRoots(); // launch hooks/preparation have run; no backend has been observed
     const planExtra = launchPlan ? { launch: launchPlan.recipe, harness: launchPlan.harness, yolo: launchPlan.yolo, ...(launchPlan.modelFrom ? { modelFrom: launchPlan.modelFrom } : {}),
       ...(launchPlan.launchFrom ? { launchFrom: launchPlan.launchFrom, launchAt: launchPlan.launchAt, launchDeclared: launchPlan.launchDeclared } : {}),
@@ -4933,7 +4948,7 @@ export function startInstanceSession(home, o = {}) {
     if (target) {
       try { state = inspectSessionTarget(target, o.io); }
       catch (e) {
-        if (backend === "tmux" && lostTmuxServer(e)) { serverGone = true; state = { present: false, state: "stopped" }; }
+        if (lostTmuxServer(e)) { serverGone = true; state = { present: false, state: "stopped" }; }
         else throw oatsError("E_SESSION_UNKNOWN", `cannot establish whether ${meta.instance} is running, so nothing was started: ${String(e.stderr ?? e.message ?? "").trim() || e.message}`);
       }
     }
@@ -4947,7 +4962,7 @@ export function startInstanceSession(home, o = {}) {
       writeJsonAtomic(join(realHome, ".oats-restart.json"), { instance: meta.instance, at: new Date().toISOString(), stop: stopReceipt, next: { harness: launchPlan?.harness || harness, launchConfig: launchPlan?.recipe?.launchConfig ?? meta.launch?.launchConfig ?? null, model: model ?? null } }, 0o600);
       appendEvent(realHome, { kind: stopReceipt.exited ? "restarted" : "stop-refused", data: { phase: "restart-stop", signal: stopReceipt.signal, waitedMs: stopReceipt.waitedMs, stillRunning: stopReceipt.stillRunning ?? [] } });
       if (!stopReceipt.exited) throw oatsError("E_SESSION_STOP_FAILED", `${meta.instance} was asked to stop (${stopReceipt.signal} to ${stopReceipt.requested.map((r) => `${r.comm} pid ${r.pid}`).join(", ")} at ${stopReceipt.sentAt}) and was still running after ${stopReceipt.waitedMs} ms (${stopReceipt.state}); nothing was escalated and nothing was started; stop it yourself, or retry with a longer --stop-grace. Receipt: ${join(realHome, ".oats-restart.json")}`);
-      try { state = inspectSessionTarget(target, o.io); } catch (e) { if (backend === "tmux" && lostTmuxServer(e)) { serverGone = true; state = { present: false, state: "stopped" }; } else throw oatsError("E_SESSION_UNKNOWN", `after the stop, cannot establish the state of ${meta.instance}: ${String(e.stderr ?? e.message ?? "").trim() || e.message}`); }
+      try { state = inspectSessionTarget(target, o.io); } catch (e) { if (lostTmuxServer(e)) { serverGone = true; state = { present: false, state: "stopped" }; } else throw oatsError("E_SESSION_UNKNOWN", `after the stop, cannot establish the state of ${meta.instance}: ${String(e.stderr ?? e.message ?? "").trim() || e.message}`); }
       if (state.present && state.state !== "shell") throw oatsError("E_SESSION_UNKNOWN", `${meta.instance} read as stopped and then as ${state.state} again; nothing was started`);
     }
     // The kernel that launches the harness is the one the agent's plain `oats` runs.
@@ -4959,79 +4974,64 @@ export function startInstanceSession(home, o = {}) {
     const executionCommand = nativeRecordCommand(command, realHome, launchPlan?.harness || harness);
     const completedCommand = `${executionCommand}; oats_start_status=$?; printf '%s\\n' ${shq(id)} > ${shq(exitedPath)}`;
     let reused = "new";
-    if (backend === "herdr") {
-      if (!target) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `this never-launched Herdr home has no saved server endpoint; no tmux fallback was started`);
-      const base = { backend: "herdr", binary: target.binary, socket: target.socket, protocol: target.protocol };
-      if (state.present) { reused = "pane"; }
-      else {
-        try { herdrSnapshot(base, o.io); }
-        catch (e) { throw oatsError("E_SESSION_UNKNOWN", `Herdr server on ${base.socket} is not reachable, so nothing was started: ${e.message}`); }
-        target = allocateHerdr(base, { home: realHome, instance: meta.instance }, o.io);
-      }
+    const session = target?.session || meta.tmux?.session || DEFAULT_TMUX_SESSION;
+    const window = target?.window || meta.tmux?.window || meta.instance;
+    let socket = target?.socket || meta.tmux?.socket;
+    const windowCmd = `${completedCommand}; exec "\${SHELL:-/bin/zsh}"`;
+    // A fallback shell (no harness descendant) or a retained dead pane is
+    // the agent's own pane: the command runs there, no other window touched.
+    const inPlace = state.paneId && (state.present || state.state === "stopped");
+    if (inPlace) {
       checkRoots();
       writeJsonAtomic(pendingPath, { id, target, command, model: model ?? null, startedAt, ...planExtra }, 0o600);
-      try { launchHerdr(target, `${paneEnvExports}cd ${shq(realHome)} && ${completedCommand}; exit "$oats_start_status"`, o.io); }
-      catch (e) { throw launchFailure("Herdr", e); }
+      try { tmuxOn(socket, ["respawn-pane", "-k", "-t", state.paneId, "-c", realHome, ...paneEnvFlags, windowCmd], o.io); }
+      catch (e) { throw launchFailure(e); }
+      reused = "pane";
     } else {
-      const session = target?.session || meta.tmux?.session || DEFAULT_TMUX_SESSION;
-      const window = target?.window || meta.tmux?.window || meta.instance;
-      let socket = target?.socket || meta.tmux?.socket;
-      const windowCmd = `${completedCommand}; exec "\${SHELL:-/bin/zsh}"`;
-      // A fallback shell (no harness descendant) or a retained dead pane is
-      // the agent's own pane: the command runs there, no other window touched.
-      const inPlace = state.paneId && (state.present || state.state === "stopped");
-      if (inPlace) {
-        checkRoots();
-        writeJsonAtomic(pendingPath, { id, target, command, model: model ?? null, startedAt, ...planExtra }, 0o600);
-        try { tmuxOn(socket, ["respawn-pane", "-k", "-t", state.paneId, "-c", realHome, ...paneEnvFlags, windowCmd], o.io); }
-        catch (e) { throw launchFailure("tmux", e); }
-        reused = "pane";
-      } else {
-        const instancesRoot = dirname(realHome);
-        const hq = existsSync(dirname(dirname(instancesRoot))) ? dirname(dirname(instancesRoot)) : realHome;
-        checkRoots();
-        if (!socket) {
-          // Never launched (--no-launch): the default server, as spawn uses.
-          const defaultTmux = args => guardedExec("tmux", args, { encoding: "utf8", timeout: 10000, stdio: ["ignore", "pipe", "pipe"] }).trim();
-          let alive = false;
-          try { defaultTmux(["has-session", "-t", session]); alive = true; } catch (e) { checkRoots(); }
-          if (!alive) {
-            defaultTmux(["new-session", "-d", "-s", session, "-n", "hq", "-c", hq]);
-            for (const option of [["window-size", "latest"], ["aggressive-resize", "on"]]) {
-              try { defaultTmux(["set-option", "-t", session, "-g", ...option]); } catch (e) { checkRoots(); }
-            }
+      const instancesRoot = dirname(realHome);
+      const hq = existsSync(dirname(dirname(instancesRoot))) ? dirname(dirname(instancesRoot)) : realHome;
+      checkRoots();
+      if (!socket) {
+        // Never launched (--no-launch): the default server, as spawn uses.
+        const defaultTmux = args => guardedExec("tmux", args, { encoding: "utf8", timeout: 10000, stdio: ["ignore", "pipe", "pipe"] }).trim();
+        let alive = false;
+        try { defaultTmux(["has-session", "-t", session]); alive = true; } catch (e) { checkRoots(); }
+        if (!alive) {
+          defaultTmux(["new-session", "-d", "-s", session, "-n", "hq", "-c", hq]);
+          for (const option of [["window-size", "latest"], ["aggressive-resize", "on"]]) {
+            try { defaultTmux(["set-option", "-t", session, "-g", ...option]); } catch (e) { checkRoots(); }
           }
-          socket = defaultTmux(["display-message", "-p", "-t", session, "#{socket_path}"]);
-          if (!socket) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", "tmux did not report its socket");
-        } else if (serverGone) {
-          // The recorded server is gone (a reboot): the same socket path again.
-          mkdirSync(dirname(socket), { recursive: true });
-          tmuxOn(socket, ["new-session", "-d", "-s", session, "-n", "hq", "-c", hq], o.io);
-          tmuxOn(socket, ["set-option", "-t", session, "-g", "window-size", "latest"], o.io);
-          tmuxOn(socket, ["set-option", "-t", session, "-g", "aggressive-resize", "on"], o.io);
         }
-        let names = [];
-        try { names = tmuxOn(socket, ["list-windows", "-t", `=${session}`, "-F", "#{window_name}"], o.io).split("\n").filter(Boolean); }
-        catch (e) {
-          if (!/can't find session/i.test(String(e.stderr ?? e.message ?? "")) && !lostTmuxServer(e)) throw oatsError("E_SESSION_UNKNOWN", `cannot list tmux windows on ${socket}: ${String(e.stderr ?? e.message ?? "").trim()}`);
-          tmuxOn(socket, ["new-session", "-d", "-s", session, "-n", "hq", "-c", hq], o.io);
-        }
-        if (names.includes(window)) throw oatsError("E_SESSION_RUNNING", `tmux window ${session}:${window} appeared on ${socket} during the start; nothing was started`);
-        target = { backend: "tmux", session, window, socket: resolve(socket) };
-        checkRoots();
-        writeJsonAtomic(pendingPath, { id, target, command, model: model ?? null, startedAt, ...planExtra }, 0o600);
-        try { tmuxOn(socket, ["new-window", "-t", `=${session}:`, "-n", window, "-c", realHome, ...paneEnvFlags, windowCmd], o.io); }
-        catch (e) { throw launchFailure("tmux", e); }
+        socket = defaultTmux(["display-message", "-p", "-t", session, "#{socket_path}"]);
+        if (!socket) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", "tmux did not report its socket");
+      } else if (serverGone) {
+        // The recorded server is gone (a reboot): the same socket path again.
+        mkdirSync(dirname(socket), { recursive: true });
+        tmuxOn(socket, ["new-session", "-d", "-s", session, "-n", "hq", "-c", hq], o.io);
+        tmuxOn(socket, ["set-option", "-t", session, "-g", "window-size", "latest"], o.io);
+        tmuxOn(socket, ["set-option", "-t", session, "-g", "aggressive-resize", "on"], o.io);
+      }
+      let names = [];
+      try { names = tmuxOn(socket, ["list-windows", "-t", `=${session}`, "-F", "#{window_name}"], o.io).split("\n").filter(Boolean); }
+      catch (e) {
+        if (!/can't find session/i.test(String(e.stderr ?? e.message ?? "")) && !lostTmuxServer(e)) throw oatsError("E_SESSION_UNKNOWN", `cannot list tmux windows on ${socket}: ${String(e.stderr ?? e.message ?? "").trim()}`);
+        tmuxOn(socket, ["new-session", "-d", "-s", session, "-n", "hq", "-c", hq], o.io);
       }
+      if (names.includes(window)) throw oatsError("E_SESSION_RUNNING", `tmux window ${session}:${window} appeared on ${socket} during the start; nothing was started`);
       target = { backend: "tmux", session, window, socket: resolve(socket) };
+      checkRoots();
+      writeJsonAtomic(pendingPath, { id, target, command, model: model ?? null, startedAt, ...planExtra }, 0o600);
+      try { tmuxOn(socket, ["new-window", "-t", `=${session}:`, "-n", window, "-c", realHome, ...paneEnvFlags, windowCmd], o.io); }
+      catch (e) { throw launchFailure(e); }
     }
+    target = { backend: "tmux", session, window, socket: resolve(socket) };
     // Keep launch evidence until the command exits or the target disappears.
     // A transient child (for example cat TASK.md) is not proof that startup
     // has finished. A later start reconciles the receipt without a watcher.
-    try { return { ...record(meta, { id, backend, target, model, command, startedAt, reused, ...planExtra, ...(stopReceipt ? { stop: stopReceipt } : {}) }, false), warnings }; }
+    try { return { ...record(meta, { id, target, model, command, startedAt, reused, ...planExtra, ...(stopReceipt ? { stop: stopReceipt } : {}) }, false), warnings }; }
     catch (e) {
       if (e.code && String(e.code).startsWith("E_")) throw e;
-      throw oatsError("E_SESSION_START_INCOMPLETE", `${meta.instance} was started (${backend === "herdr" ? `Herdr pane ${target.paneId}` : `tmux ${target.session}:${target.window} on ${target.socket}`}) but its metadata could not be recorded: ${e.message}; the actual target is kept in ${pendingPath} and the next start adopts it instead of allocating another`);
+      throw oatsError("E_SESSION_START_INCOMPLETE", `${meta.instance} was started (tmux ${target.session}:${target.window} on ${target.socket}) but its metadata could not be recorded: ${e.message}; the actual target is kept in ${pendingPath} and the next start adopts it instead of allocating another`);
     }
   } finally {
     // A hook may have replaced the home itself. Never follow that replacement
@@ -5589,7 +5589,10 @@ export function retireInstance(root, name, o = {}) {
   // persists the intent and hands the whole retirement to a detached process
   // that runs it as an ordinary EXTERNAL retirement once the harness is gone
   // (aweb-abep). `--keep-dir` keeps the old in-process path: nothing to inspect.
-  if (self && (!o.keepDir || meta.sessionTarget)) {
+  // A home opened in Herdr (removed in 0.31.0) has no endpoint OATS can quiesce in-process. A
+  // quarantined home's cleanup descriptor overrides the live record's endpoint: either may name it.
+  const herdrHome = recordsHerdr(meta, readJsonOrUndefined(retirementBaselinePath(found.home))) || recordsHerdr(liveMeta);
+  if (self && (!o.keepDir || herdrHome)) {
     return scheduleDeferredSelfRetirement(root, found, name, o, session);
   }
   // First inspection is non-destructive. Only after it succeeds may OATS quiesce
@@ -5600,7 +5603,13 @@ export function retireInstance(root, name, o = {}) {
   // describe it for humans, but only the independent baseline can authorize the
   // endpoint that proves quiescence.
   let runtimeAuthority;
-  if (liveMeta || quarantine) {
+  if (herdrHome) {
+    // Nothing to quiesce without Herdr: the retirement goes on only when no process works in the
+    // home, exactly as for a session observed absent.
+    const scan = processesInHome(found.home);
+    if (!scan.ok) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `cannot retire ${name}: it was opened in Herdr (${HERDR_REMOVED}), and whether a process still works in its home could not be established (${scan.error}); nothing was removed`);
+    if (scan.processes.length) throw herdrInstanceBusy(name, scan.processes.map((p) => p.pid));
+  } else if (liveMeta || quarantine) {
     runtimeAuthority = initialObservation.runtimeAuthority;
     // A home without its receipt (spawned before 0.25.9) has nothing OATS may
     // quiesce; when its session is observably absent, quiescing is vacuous and
@@ -5613,12 +5622,7 @@ export function retireInstance(root, name, o = {}) {
     }
   }
   if (runtimeAuthority) {
-    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);
+    const metaAgrees = meta.launched === runtimeAuthority.launched && (!runtimeAuthority.launched || tmuxEndpointAgrees(meta, runtimeAuthority));
     if (!metaAgrees) {
       throw oatsError("E_RUNTIME_AUTHORITY_MISMATCH", `cannot quiesce ${name}: mutable instance metadata disagrees with independent runtime endpoint authority`);
     }
@@ -5626,11 +5630,7 @@ 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 && 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) {
+  if (!self && runtimeAuthority?.launched) {
     const runtimeSession = runtimeAuthority.tmux.session;
     const runtimeWindow = runtimeAuthority.tmux.window;
     const runtimeSocket = runtimeAuthority.tmux.socket;
@@ -5930,7 +5930,10 @@ export function retireInstance(root, name, o = {}) {
     // The caller is the instance: its process lives in the window we are about to
     // kill. Detach the kill so this function can return and the caller can report
     // before dying. The delay is the caller's window to print its last words.
-    shTry(`tmux run-shell -b 'sleep ${o.selfKillDelaySec ?? 8}; tmux kill-window -t ${shq(`=${session}:=${name}`)} 2>/dev/null || true'`);
+    // The window the home RECORDED (a pre-0.31 home lives in pi-agents), never the default for new ones.
+    const killSession = runtimeAuthority?.tmux?.session || meta?.tmux?.session || session;
+    const killWindow = runtimeAuthority?.tmux?.window || meta?.tmux?.window || name;
+    shTry(`tmux run-shell -b 'sleep ${o.selfKillDelaySec ?? 8}; tmux kill-window -t ${shq(`=${killSession}:=${killWindow}`)} 2>/dev/null || true'`);
     result.selfKillScheduled = true;
   }
   return result;