@awebai/oats 0.30.3 → 0.31.0

package/lib/core.mjs

@@ -41,9 +41,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 +125,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;
@@ -2182,14 +2196,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")); }
@@ -2510,10 +2523,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 +2606,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 +2616,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 +2917,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") : "");
 
@@ -2991,11 +3001,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 +3109,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 +3334,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 +3353,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);
@@ -3622,7 +3609,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 +3631,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 +3693,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 +3720,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 +3774,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 +3958,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 +3978,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 +4011,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 +4240,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 +4282,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 +4323,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 +4381,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 +4395,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 +4421,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 +4548,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 +4725,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 +4753,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 +4781,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 +4802,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 +4814,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 +4831,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 +4849,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 +4892,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 +4902,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 +4916,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 +4928,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 +5543,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 +5557,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 +5576,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 +5584,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 +5884,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;