@awebai/oats 0.40.1 → 0.41.0

package/lib/core.mjs

@@ -68,6 +68,7 @@ export { fingerprintTree };
 import { canonicalJson, lineAt, parseStrictJson } from "./canonical-json.mjs";
 import { readPortableBytes } from "./bounded-read.mjs";
 import { copyTreeSafe } from "./tree-copy.mjs";
+import { assertSameWorktreeHead, worktreeCommitUnreached, worktreeHead } from "./instance-git.mjs";
 /** The package and capability id grammar (namespaced, lowercase): an id names a
  *  directory (a home's module copy), so no path spelling fits it. */
 const PACKAGE_ID_RE = /^[a-z0-9][a-z0-9._-]*$/;
@@ -206,6 +207,11 @@ function shIn(cwd, cmdline, timeout = 45000) {
 }
 function shInTry(cwd, cmdline, timeout) { try { return shIn(cwd, cmdline, timeout); } catch { return undefined; } }
 export function shq(s) { return `'${String(s).replace(/'/g, `'\\''`)}'`; }
+/** One word of a command line that a person or an agent pastes into a shell: as it is when it holds
+ *  only letters, digits and `_./:-`, single-quoted otherwise (an empty string too). The safe set is
+ *  deliberately small: no `~` (an unquoted leading one expands), no `=` (zsh expands a leading
+ *  `=word`). */
+export function shellWord(s) { const word = String(s); return /^[A-Za-z0-9_.\/:-]+$/.test(word) ? word : shq(word); }
 export function slug(s) {
   const r = String(s).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
   return r || "agent";
@@ -1898,20 +1904,340 @@ export function explicitInstanceName(name) {
 }
 
 function tmuxAlive(session) { return !!shTry(`tmux has-session -t ${shq(session)} 2>/dev/null && echo yes`); }
-function tmuxSocket(session) {
-  let socket;
+/** The window names of `session` on the user's DEFAULT tmux server: only for a home that records no
+ *  socket (listInstances). OATS creates nothing there: new sessions live on the OATS server below. */
+export function tmuxWindows(session = DEFAULT_TMUX_SESSION) {
+  if (!tmuxAlive(session)) return [];
+  return (shTry(`tmux list-windows -t ${shq(session)} -F '#{window_name}'`) || "").split("\n").filter(Boolean);
+}
+
+// ---------- the OATS tmux server ----------
+/** The tmux server OATS creates its sessions on, selected by name (`tmux -L oats`): one per host user,
+ *  in tmux's own per-user socket directory, with the user's tmux configuration loaded (no `-f`). A
+ *  tool that restyles the default server does not reach it. Not configurable. The name selects the
+ *  server only while a session is ensured (ensureOatsTmuxSession); every later step, and every record,
+ *  uses the absolute socket that step returned, through tmuxOn. docs/execution-targets.md owns the rule. */
+const OATS_TMUX_SERVER = "oats";
+/** What OATS sets, always at WINDOW scope and by window id, on a window it created: nothing is ever
+ *  set server-global or on a session, on any server. Sizing goes on every window OATS creates (the
+ *  session's `hq` window and each agent window): viewers attach at their own size and depend on both
+ *  options, and a viewer links the window itself, so the window's options travel with it. A sizing
+ *  command that tmux refuses is ignored, as it always was (tmux 3.0 has no `window-size latest`).
+ *  Colours go on the agent window only: it shows the viewer's colours whatever the server's global
+ *  styles are, and a refused colour command fails the launch. */
+const OATS_WINDOW_SIZING = [["window-size", "latest"], ["aggressive-resize", "on"]];
+const OATS_WINDOW_COLOURS = [["window-style", "default"], ["window-active-style", "default"]];
+function tmuxOatsServer(args, io, options = {}) {
+  return (io?.exec || execFileSync)("tmux", ["-u", "-L", OATS_TMUX_SERVER, ...args], { encoding: "utf8", timeout: 10000, maxBuffer: 1024 * 1024, stdio: ["ignore", "pipe", "pipe"], ...options });
+}
+const tmuxFailure = (e, fallback) => String(e?.stderr ?? e?.message ?? "").trim() || fallback;
+/** An error OATS raised itself (a root guard under an injected exec), never one a tolerant read may absorb. */
+const oatsCoded = (e) => typeof e?.code === "string" && e.code.startsWith("E_");
+/** A failed call that ran to its own exit: it has a status, no signal ended it, and Node reports no
+ *  failure of its own. A timeout and an output overflow carry a code and keep what the call had
+ *  printed until then, so that text is not the call's answer. Anything else is not a completed call. */
+const exitedByItself = (e) => Number.isInteger(e?.status) && e.signal == null && e.code == null;
+/** What the OATS server holds, as `list-sessions` answers: whether it runs, its socket (any session
+ *  names it), and whether a session named exactly `session` is there. No server and no such session
+ *  are the only answers that mean absent, and "no server" is read only from a call that exited by
+ *  itself: a line a cut-off call left behind is not tmux's answer. Any other failure is not absence. */
+function oatsTmuxSessionSocket(session, io) {
+  let listed;
+  try { listed = tmuxOatsServer(["list-sessions", "-F", "#{session_name}\t#{socket_path}"], io); }
+  catch (e) {
+    if (oatsCoded(e)) throw e;
+    // A tmux that could not be run at all is the one failure a person can act on: say so.
+    if (e?.code === "ENOENT") throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `could not read the OATS tmux server for session ${session}: tmux was not found through this process's PATH. Run this command with a PATH that holds tmux`);
+    if (!exitedByItself(e)) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `could not read the OATS tmux server for session ${session}: tmux list-sessions did not exit by itself (${typeof e?.code === "string" ? e.code : e?.signal || "no exit status"})`);
+    if (tmuxServerLost(e)) return { server: null, present: false };
+    throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `could not read the OATS tmux server for session ${session}: ${tmuxFailure(e, "tmux list-sessions failed")}`);
+  }
+  let server = null, present = false;
+  for (const line of listed.split("\n")) {
+    const tab = line.indexOf("\t");
+    if (tab <= 0) continue;
+    server ??= line.slice(tab + 1).trim() || null;
+    if (line.slice(0, tab) === session) { server = line.slice(tab + 1).trim() || null; present = true; break; }
+  }
+  return { server, present };
+}
+/** The names that mark a process as an OATS instance: the launch identity, and what older kernels
+ *  called it. One of them in the environment, even empty, is evidence of an instance. */
+const INSTANCE_IDENTITY_ENV = ["OATS_INSTANCE", "OATS_INSTANCE_HOME", "OATS_HOME", "PI_AGENT_INSTANCE", "PI_AGENT_HOME"];
+/** Every name the kernel itself generates into a launch or a hook environment, and the three that
+ *  tie a process to its own terminal. None of them is part of an environment OATS starts a tmux
+ *  server, a session or a window with. Not the whole OATS_ prefix: operators export configuration
+ *  under it (OATS_HOME_DIR, OATS_TMUX_SESSION). The inventory: RESERVED_LAUNCH_ENV; what
+ *  runLifecycleHooks adds for a hook (capability, layer, level, meta, the spawn and launch facts in
+ *  its extraEnv, the team and workspace names of teamEnv); what operator dispatch, retire and a
+ *  trigger add. Launch references (OATS_LAUNCH_REF_<NAME>, and the NAME each stands for) are
+ *  removed by prefix in withoutKernelEnvironment. No harness's name is here. */
+const KERNEL_ENV_NAMES = new Set([...RESERVED_LAUNCH_ENV, "COLORFGBG", "TMUX", "TMUX_PANE",
+  "OATS_CAPABILITY", "OATS_LAYER", "OATS_LEVEL", "OATS_META", "OATS_DEPLOYMENT", "OATS_RESOLUTION", "OATS_OPERATION",
+  "OATS_REPO", "OATS_BRANCH", "OATS_WORK", "OATS_KIND", "OATS_TASK", "OATS_HARNESS", "OATS_PREVIOUS_HARNESS", "OATS_RUNTIME", "OATS_PREVIOUS_RUNTIME",
+  "OATS_LAUNCH_PREVIEW", "OATS_RETIRE_INTENT", "OATS_TRIGGER_EVENT_FILE",
+  "OATS_TEAM_NAME", "OATS_TEAM_SCOPE", "OATS_TEAM_ID", "OATS_TEAM_LABEL", "OATS_TEAM_LABELS", "OATS_TEAMS", "OATS_TEAMS_SOURCE",
+  "OATS_DEFAULT_TEAM", "OATS_DEFAULT_TEAM_ID", "OATS_DEFAULT_TEAM_FROM", "OATS_WORKSPACE_NAME", "OATS_WORKSPACE_KEY"]);
+function withoutKernelEnvironment(source) {
+  const env = { ...source };
+  for (const name of Object.keys(env)) {
+    if (name.startsWith(LAUNCH_REF_PREFIX)) { delete env[name]; delete env[name.slice(LAUNCH_REF_PREFIX.length)]; }
+  }
+  for (const name of KERNEL_ENV_NAMES) delete env[name];
+  return env;
+}
+/**
+ * What `tmux show-environment -g -s` printed, as bytes, read strictly and never executed: the whole
+ * text or nothing. tmux (cmd-show-environment.c) prints one entry per variable, each ending in a
+ * line feed: `NAME="VALUE"; export NAME;` with `"`, `$`, a backtick and `\` in VALUE each preceded
+ * by a backslash, or `unset NAME;` for a removed one. VALUE is read to its closing unescaped quote
+ * (a backslash escapes the character after it), so a line feed inside a value stays inside it.
+ *
+ * Not every value can be known the same way on every tmux. tmux 3.4 and 3.5 write each printed
+ * line through vis(3) (server-client.c server_client_print): a control character or a byte that is
+ * not UTF-8 arrives as `\a`, `\b`, `\f`, `\r`, `\v` or three octal digits, and tmux 3.4 puts one
+ * more backslash before a `$` that a letter, `_` or `{` follows (utf8.c utf8_strvis). Neither
+ * changes where a value ends. So nothing is decoded: a variable is left out whole when its VALUE
+ * holds a line feed, a `$` (escaped or bare, on every version), or a vis-encoded sequence. A
+ * backtick, a quote and a backslash are written the same by every version read, and are carried.
+ *
+ * Kept: an entry whose NAME is a plain identifier and whose VALUE is none of the above; an `unset`
+ * entry carries nothing. An entry is left out only once it is framed whole (its name, its value to
+ * the closing quote, the exact `; export NAME;` tail); its name is added to `omitted` when the
+ * caller passes one. null for bytes that are not valid UTF-8 or that this grammar does not consume
+ * to the end: a caller refuses, it never uses a partial result.
+ */
+export function parseTmuxShellEnvironment(bytes, omitted) {
+  let text;
+  try { text = new TextDecoder("utf-8", { fatal: true }).decode(bytes); } catch { return null; }
+  const env = {};
+  let i = 0;
+  const take = (word) => { if (!text.startsWith(word, i)) return false; i += word.length; return true; };
+  while (i < text.length) {
+    if (take("unset ")) {
+      const end = text.indexOf(";", i);
+      if (end <= i || /[\s"=]/.test(text.slice(i, end))) return null;
+      i = end + 1;
+    } else {
+      const assign = text.indexOf("=\"", i);
+      if (assign <= i) return null;
+      const name = text.slice(i, assign);
+      i = assign + 2;
+      let value = "", closed = false, carried = true;
+      while (i < text.length) {
+        const c = text[i++];
+        if (c === "\"") { closed = true; break; }
+        if (c === "$") { carried = false; continue; }
+        if (c === "`") return null; // tmux never writes a bare backtick
+        if (c !== "\\") { value += c; continue; }
+        const next = text[i];
+        if (next === "$") { carried = false; i += 1; }
+        else if (next !== undefined && "\"`\\".includes(next)) { value += next; i += 1; }
+        else if (/^(?:[abfrv]|[0-7]{3})/.test(text.slice(i, i + 3))) { carried = false; i += /[0-7]/.test(next) ? 3 : 1; }
+        else return null;
+      }
+      if (!closed || !take(`; export ${name};`)) return null;
+      if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+        if (carried && !value.includes("\n")) env[name] = value; else omitted?.push(name);
+      }
+    }
+    if (!take("\n")) return null;
+  }
+  return env;
+}
+/** Whether this process runs inside an OATS instance, as the CLI resolves an in-home command:
+ *  `{ home }` for the home OATS_INSTANCE_HOME names when it is one, else the instance home enclosing
+ *  the working directory (a harness may strip the session environment). `{ evidence }` when neither
+ *  gives a home and yet the environment carries an instance identity name: an instance's environment
+ *  without an identified home is not "outside an instance". undefined otherwise. */
+function callerInstance() {
+  const named = process.env.OATS_INSTANCE_HOME;
+  if (named && isAbsolute(named)) {
+    try { if (isPlainObject(JSON.parse(readFileSync(join(named, "instance.json"), "utf8")))) return { home: named }; }
+    catch { /* names no home */ }
+  }
+  const enclosing = enclosingInstanceHome(logicalCwd());
+  if (enclosing) return { home: enclosing };
+  const evidence = INSTANCE_IDENTITY_ENV.find((name) => process.env[name] !== undefined);
+  return evidence ? { evidence } : undefined;
+}
+/** `tmux` as this process's own PATH finds it, always absolute: the creator chooses the tmux that
+ *  runs, whatever environment the server it starts is given. A bare name is never run: an exec
+ *  looks one up in the PATH of the environment it is passed, which here is the selected one.
+ *  Entries in PATH order; a relative entry, and an empty one (an empty PATH is one empty entry),
+ *  are this process's working directory, as an exec of `tmux` reads them. With no PATH, or none
+ *  that holds a tmux, the creation of `session` is refused, for every creator: no default search
+ *  path is assumed. Of the two, only "no PATH" is met in a run: the lookup before this runs the
+ *  bare name with this process's own environment, so a PATH that holds no tmux is refused there
+ *  first (oatsTmuxSessionSocket), session or no session. The no-match refusal here is the guard
+ *  that the creation never runs a bare name, whatever the lookup did. */
+function creatorTmux(session) {
+  const refuse = (why) => oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `cannot create tmux session ${session} on the OATS tmux server: ${why}, and the tmux that creates a session is the one this process's own PATH finds; the session was not created. Run this command with a PATH that holds tmux`);
+  if (process.env.PATH === undefined) throw refuse("PATH is not set in this process");
+  for (const dir of process.env.PATH.split(":")) {
+    const candidate = resolve(dir || ".", "tmux");
+    try { accessSync(candidate, fsConstants.X_OK); if (statSync(candidate).isFile()) return candidate; } catch { /* not here */ }
+  }
+  throw refuse("no tmux was found on this process's PATH");
+}
+/**
+ * The environment a `new-session` on the OATS server runs with: the only tmux call that can start
+ * a server, so every one of them gets this, whether or not a server was seen a moment earlier. A
+ * tmux server keeps the environment of the client that started it as its global environment, which
+ * every pane created on it later inherits, and a new session takes the client's variables that
+ * `update-environment` names.
+ *
+ * A process inside an OATS instance never passes its own environment (its harness's variables, its
+ * credentials, its identity). It passes the global environment of the tmux server its home
+ * records: an existing baseline, chosen because a window that instance opened on that server got
+ * exactly it; not proof that it holds nothing old. The home's receipt is checked against
+ * instance.json first, as every session verb checks its endpoint, and the text is read with the
+ * strict reader above. When any of that fails, or no home is identified, the session is not
+ * created: no fallback to the caller's environment, to another server or to a built-in list. Any
+ * other creator (an operator's shell, a schedule runner, the Desktop) passes its own environment.
+ * In every case the kernel's names are removed from the final set.
+ *
+ * Environment and endpoint are chosen separately: which server is reached depends only on the
+ * creator (its TMUX_TMPDIR, kept or absent as the creator has it; its tmux); what the server
+ * process gets (HOME and so its configuration file, PATH, everything else) comes from the selected
+ * environment, with no ambient value filling in. Values travel only as the environment of that
+ * tmux process: never in an argument, a message, an event or a file. docs/execution-targets.md
+ * owns the rule.
+ */
+const TMUX_SERVER_START_ENV = ["HOME", "XDG_CONFIG_HOME", "PATH", "SHELL"];
+function oatsSessionEnvironment(session, io) {
+  const caller = callerInstance();
+  if (!caller) return withoutKernelEnvironment(process.env);
+  const refuse = (why) => oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `cannot create tmux session ${session} on the OATS tmux server from inside an OATS instance: ${why}. A tmux server and its sessions keep the environment of the process that creates them, and an instance's own environment must not become theirs; the session was not created. Create it from your own shell, outside every instance home (tmux -L ${OATS_TMUX_SERVER} new-session -d -s ${shellWord(session)} -n hq), or run this command there. tmux resolves -L ${OATS_TMUX_SERVER} with TMUX_TMPDIR: use the same TMUX_TMPDIR as this process, if it has one`);
+  if (!caller.home) throw refuse(`this process carries an instance's identity (${caller.evidence}) and neither OATS_INSTANCE_HOME nor the working directory names its home`);
+  let target;
+  try { target = instanceSessionTarget(caller.home).target; }
+  catch (e) { if (!oatsCoded(e)) throw e; throw refuse(`the session receipt of ${basename(caller.home)} could not be used (${e.code})`); }
+  if (!target?.socket) throw refuse(`the home of ${basename(caller.home)} records no tmux server`);
+  // Bytes, not text; and nothing of a failed read (tmux's output, its error) goes into the refusal.
+  let recorded = null;
+  const omitted = [];
   try {
-    socket = execFileSync("tmux", ["display-message", "-p", "-t", session, "#{socket_path}"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
-  } catch (e) {
-    throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `could not identify the tmux endpoint for session ${session}: ${String(e.stderr ?? e.message ?? "").trim() || "tmux display-message failed"}`);
+    const printed = (io?.exec || execFileSync)("tmux", ["-u", "-S", target.socket, "show-environment", "-g", "-s"], { timeout: 10000, maxBuffer: 4 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] });
+    recorded = parseTmuxShellEnvironment(Buffer.isBuffer(printed) ? printed : Buffer.from(String(printed)), omitted);
+  } catch (e) { if (oatsCoded(e)) throw e; }
+  if (recorded === null) throw refuse(`the environment of the tmux server that ${basename(caller.home)} is recorded on (${target.socket}) could not be read`);
+  // A variable the reader left out is never filled in from this process, and a server is never
+  // started when the one left out decides which configuration it loads or which programs it runs.
+  // (A recorded server that simply has none of them is copied as it is.)
+  const undecided = TMUX_SERVER_START_ENV.find((name) => omitted.includes(name));
+  if (undecided) throw refuse(`the tmux server that ${basename(caller.home)} is recorded on has a ${undecided} that cannot be carried over (its value holds a $, a line break or a character tmux prints encoded), and a tmux server's configuration and programs are chosen by it`);
+  const env = withoutKernelEnvironment(recorded);
+  if (process.env.TMUX_TMPDIR === undefined) delete env.TMUX_TMPDIR; else env.TMUX_TMPDIR = process.env.TMUX_TMPDIR;
+  return env;
+}
+/** The environment a `new-window` client runs with, and the `respawn-pane` client of a restart in
+ *  place. tmux gives a pane the PATH of the client that creates its window or respawns it, and
+ *  nothing else of that client (spawn.c). A process inside an instance
+ *  passes PATH, without any home's kernel shim directory (the launch command puts the new home's
+ *  own first), and the three names tmux's client reads its locale from: it does not start without
+ *  a UTF-8 locale, and on a host that has neither en_US.UTF-8 nor C.UTF-8 only these name one.
+ *  Nothing else of the instance travels by any route. When it has no PATH to give (none is set, or
+ *  only shim directories were in it) no PATH is passed: an empty one would be one empty entry, the
+ *  working directory, for the lookup of `tmux` and for the pane. A PATH that is set and empty is
+ *  passed as it is. Any other creator passes its environment without the kernel's names. */
+const TMUX_CLIENT_LOCALE_ENV = ["LANG", "LC_ALL", "LC_CTYPE"];
+function oatsWindowEnvironment() {
+  if (!callerInstance()) return withoutKernelEnvironment(process.env);
+  const env = {};
+  const dirs = process.env.PATH === undefined ? [] : process.env.PATH.split(":").filter((dir) => !/(?:^|\/)instances\/[^/]+\/\.oats\/bin\/?$/.test(dir));
+  if (dirs.length) env.PATH = dirs.join(":");
+  for (const name of TMUX_CLIENT_LOCALE_ENV) if (process.env[name] !== undefined) env[name] = process.env[name];
+  return env;
+}
+/**
+ * An optimisation for a spawn or a start, to call BEFORE it creates, stops or writes anything: when
+ * this process is inside an instance and `session` is not on the OATS server, the environment its
+ * creation needs is read now, so that a caller that cannot create it is refused with nothing left
+ * behind; the answer goes to ensureOatsTmuxSession. undefined when there is nothing to read (the
+ * session exists, or the caller is no instance: no tmux is run for it). Not the guarantee:
+ * ensureOatsTmuxSession decides by what it finds when it creates.
+ */
+function planOatsTmuxSession(session, io) {
+  if (!callerInstance() || oatsTmuxSessionSocket(session, io).present) return undefined;
+  return { env: oatsSessionEnvironment(session, io) };
+}
+/**
+ * Make sure `session` exists on the OATS server and return that server's absolute socket: the one
+ * endpoint the caller then creates its window on, records and compensates on. `hq` is the directory
+ * of the session's first window; `io.exec` replaces execFileSync (session start guards its roots there).
+ * This `new-session`, the one that creates an agents' session, runs with oatsSessionEnvironment
+ * (`plan`, when planOatsTmuxSession read it earlier), by the creator's own tmux, on the socket the
+ * lookup named when the server runs. (The viewer's temporary session, lib/session-viewer.mjs, is
+ * created with the attaching process's environment: awebai/oats#623.)
+ * Two creators racing both succeed on one socket: the loser's `duplicate session` is answered by a
+ * second lookup. tmux starts a server once: the first successful creator determines its initial
+ * environment, and nothing here changes a running server's. E_RUNTIME_ENDPOINT_UNKNOWN when the
+ * server cannot be read or names no socket, when this caller may not create the session, or when
+ * its own PATH names no tmux to create it with (creatorTmux).
+ */
+export function ensureOatsTmuxSession(session, hq, io, plan) {
+  let { server: socket, present } = oatsTmuxSessionSocket(session, io);
+  if (!present) {
+    // The executable is chosen here, where the creation is about to run, and nowhere earlier: a
+    // session that exists needs none, so nothing is refused for it.
+    const tmux = creatorTmux(session);
+    const env = plan?.env ?? oatsSessionEnvironment(session, io);
+    const address = socket ? ["-S", socket] : ["-L", OATS_TMUX_SERVER];
+    let created;
+    try { created = (io?.exec || execFileSync)(tmux, ["-u", ...address, "new-session", "-d", "-s", session, "-n", "hq", "-c", hq, "-P", "-F", "#{socket_path}\t#{window_id}"], { encoding: "utf8", timeout: 10000, maxBuffer: 1024 * 1024, stdio: ["ignore", "pipe", "pipe"], env }).trim(); }
+    catch (e) {
+      if (oatsCoded(e)) throw e;
+      const again = oatsTmuxSessionSocket(session, io);
+      if (!again.present) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `could not create tmux session ${session} on the OATS tmux server: ${tmuxFailure(e, "tmux new-session failed")}`);
+      socket = again.server;
+    }
+    if (created !== undefined) {
+      const [path, hqWindow] = created.split("\t");
+      if (!path) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `tmux returned no endpoint for session ${session}`);
+      socket = path;
+      // The session's first window, which this call created: sized like every window OATS creates.
+      // A dead server shows in the caller's next step on this socket.
+      sizeWindow(socket, hqWindow, io);
+    }
   }
   if (!socket) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `tmux returned no endpoint for session ${session}`);
   return resolve(socket);
 }
-export function tmuxWindows(session = DEFAULT_TMUX_SESSION) {
-  if (!tmuxAlive(session)) return [];
-  return (shTry(`tmux list-windows -t ${shq(session)} -F '#{window_name}'`) || "").split("\n").filter(Boolean);
-}
+/** The window names of `session` on the OATS server, creating neither a server nor a session: none is
+ *  an empty list. An early read only (an explicit name's refusal); the collision check that counts
+ *  lists the socket ensureOatsTmuxSession returned. */
+function oatsTmuxWindows(session) {
+  try { return tmuxOatsServer(["list-windows", "-t", `=${session}`, "-F", "#{window_name}"]).split("\n").filter(Boolean); }
+  catch { return []; }
+}
+/** The harness's window command: no COLORFGBG in the pane, whatever the server's global environment
+ *  holds. tmux runs the command with the server's `default-shell -c` (the user's shell: sh, bash and
+ *  zsh all take `unset NAME;`), and the fallback shell it execs inherits the result. */
+const paneCommand = (command) => `unset COLORFGBG; ${command}; exec "\${SHELL:-/bin/zsh}"`;
+/** The sizing options on one window, each best effort: this command's failure is ignored, nothing is
+ *  retried elsewhere and nothing global is written. */
+function sizeWindow(socket, windowId, io) {
+  if (!/^@\d+$/.test(windowId || "")) return;
+  for (const [option, value] of OATS_WINDOW_SIZING) {
+    try { tmuxOn(socket, ["set-option", "-w", "-t", windowId, option, value], io); } catch (e) { if (oatsCoded(e)) throw e; }
+  }
+}
+/** The agent window OATS just created, by the id new-window returned: showing the viewer's colours and
+ *  sized for its viewers. Never a global option, another window or another server. The colour
+ *  commands come first and are strict, so a lost server, a permission or a transport failure surfaces
+ *  there and the tolerant sizing after them cannot mask it. The palette (`pane-colours`) is left
+ *  alone: a local reset did not neutralise inherited entries. */
+function prepareAgentWindow(socket, windowId, io) {
+  if (!/^@\d+$/.test(windowId || "")) throw new Error("tmux new-window returned no window id");
+  for (const [option, value] of OATS_WINDOW_COLOURS) tmuxOn(socket, ["set-option", "-w", "-t", windowId, option, value], io);
+  // cursor-colour exists from tmux 3.3: -q makes an unknown option exit 0. -q also hides a missing
+  // target, so only this command has it, and only after the two above succeeded on the same window.
+  tmuxOn(socket, ["set-option", "-q", "-w", "-t", windowId, "cursor-colour", "default"], io);
+  sizeWindow(socket, windowId, io);
+}
+/** One line for a start that opened its window on another server than the home recorded. */
+const sessionMovedWarning = (instance, from, to) => `${instance} was recorded on the tmux server ${JSON.stringify(from)}; its window had to be created again, and new windows open on the OATS tmux server: it now runs on ${JSON.stringify(to)}, and that socket is recorded`;
 
 /**
  * Spawn an instance of `agent` (as returned by findAgent/listAgents).
@@ -2297,13 +2623,12 @@ 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. */
+ *  Each goes to the pane as a tmux `-e NAME=value` argument. */
 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(""); }
 
 /** 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")); }
@@ -2668,6 +2993,12 @@ export async function spawnInstanceAsync(root, agent, o = {}) {
   }
   return step.value;
 }
+/** The producer sets this only when dispatched effects or their compensation
+ * cannot be confirmed. A diagnostic's wording or home path is not evidence. */
+function unconfirmedSpawn(error) {
+  error.details = { ...error.details, unconfirmed: true };
+  return error;
+}
 function* spawnBody(root, agent, o = {}) {
   if (!o.prepared) throw localMissingForSpawn(agent);
   const deliver = (r) => r;
@@ -2756,14 +3087,15 @@ function* spawnBody(root, agent, o = {}) {
       // Completion custody: the home exists from the first metadata write, but
       // the launch/lineage/events that make it a finished spawn may not have
       // happened (crash in the interval). Say which, never replay a half-spawn.
-      if (prior.spawnCompleted !== true) throw Object.assign(oatsError("E_SPAWN_INCOMPLETE", `${prior.instance} was created for this key but its spawn did not complete (launch or lineage unfinished); inspect it with oats session inspect --home ${prior.home} — do not spawn again`), { instance: prior.instance, home: prior.home, launched: prior.launched === true ? "unknown" : false });
+      if (prior.spawnCompleted !== true) throw unconfirmedSpawn(Object.assign(oatsError("E_SPAWN_INCOMPLETE", `${prior.instance} was created for this key but its spawn did not complete (launch or lineage unfinished); inspect it with oats session inspect --home ${prior.home} — do not spawn again`), { instance: prior.instance, home: prior.home, launched: prior.launched === true ? "unknown" : false }));
       return { ...prior, replayed: true, launch: undefined, command: undefined, wake: prior.wake ?? { requested: null, saved: null, error: null } };
     }
   }
 
   // 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 — launched
-  // or not — a live tmux window of the session carries it:
+  // or not — a live window of the session on the OATS tmux server carries it (an early read that
+  // creates no server; the launch below checks again on the socket it resolved):
   // 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
@@ -2772,8 +3104,12 @@ 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 (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 (oatsTmuxWindows(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 });
   }
+  // A caller inside an instance that will have to create the tmux session reads the environment
+  // for it here, before any scaffold, work tree, identity or hook, so that one that cannot is
+  // refused with nothing left behind. A caller outside every instance runs no tmux for it.
+  const tmuxSessionPlan = launch && o.preview !== true ? planOatsTmuxSession(session) : undefined;
 
   // Forward-only lineage: EXPLICIT only. Relations (child|sibling|parent|unrelated)
   // anchor the new instance to an EXISTING instance (o.relativeTo). o.parent
@@ -3218,7 +3554,7 @@ function* spawnBody(root, agent, o = {}) {
   // name taken (M1). Nothing of a classic home exists at this point either.
   const rollbackEmptyOrPreparedHome = (e) => {
     try { rmSync(home, { recursive: true, force: true }); }
-    catch (x) { e.message += ` — rollback INCOMPLETE, remove ${home} manually: ${x.message}`; }
+    catch (x) { e.message += ` — rollback INCOMPLETE, remove ${home} manually: ${x.message}`; unconfirmedSpawn(e); }
     return e;
   };
   // Workspace model: copy every resolved capability WHOLE into the new home
@@ -3386,9 +3722,10 @@ function* spawnBody(root, agent, o = {}) {
   if (incomplete.length) {
     // Nothing outside the home exists yet (no worktree, no hooks, no window), so
     // removing the scaffold is the whole rollback.
-    let removal = "";
-    try { rmSync(home, { recursive: true, force: true }); } catch (e) { removal = ` — rollback INCOMPLETE, remove ${home} manually: ${e.message}`; }
-    throw oatsError("E_COMPOSITION_INCOMPLETE", `the instance composition did not materialize completely:\n${incomplete.map((m) => `  ${m}`).join("\n")}${removal}`);
+    let removal = "", removalFailed = false;
+    try { rmSync(home, { recursive: true, force: true }); } catch (e) { removalFailed = true; removal = ` — rollback INCOMPLETE, remove ${home} manually: ${e.message}`; }
+    const error = oatsError("E_COMPOSITION_INCOMPLETE", `the instance composition did not materialize completely:\n${incomplete.map((m) => `  ${m}`).join("\n")}${removal}`);
+    throw removalFailed ? unconfirmedSpawn(error) : error;
   }
 
   // Work tree.
@@ -3433,7 +3770,8 @@ function* spawnBody(root, agent, o = {}) {
       }
       try { rmSync(home, { recursive: true, force: true }); } catch (e2) { incomplete.push(`instance home ${home}: ${e2.message}`); }
       const note = incomplete.length ? ` — rollback INCOMPLETE — clean up manually: ${incomplete.join("; ")}` : "";
-      throw new Error(`git worktree add/canonicalization failed: ${original}${note}`);
+      const error = new Error(`git worktree add/canonicalization failed: ${original}${note}`);
+      throw incomplete.length ? unconfirmedSpawn(error) : error;
     }
   } else if (work === "directory") {
     // An owned execution directory, not a link to the source or a fake Git repo.
@@ -3516,9 +3854,11 @@ 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.
+    // On the socket recorded for this spawn: windowMayExist is only set once it is.
     if (windowMayExist) {
-      shTry(`tmux kill-window -t ${shq(`=${session}:=${instance}`)}`);
-      const winProbe = probe(["tmux", "list-windows", "-t", session, "-F", "#{window_name}"]);
+      const socket = spawnTmux.socket;
+      try { tmuxOn(socket, ["kill-window", "-t", `=${session}:=${instance}`]); } catch { /* verify the effect below */ }
+      const winProbe = probe(["tmux", "-u", "-S", socket, "list-windows", "-t", `=${session}`, "-F", "#{window_name}"]);
       const unresolved = !winProbe.ok || winProbe.out.split("\n").includes(instance);
       if (unresolved) {
         incomplete.push(!winProbe.ok
@@ -3529,11 +3869,11 @@ function* spawnBody(root, agent, o = {}) {
           outstandingGit.add("worktree");
           if (branch) outstandingGit.add("branch");
         }
-        return quarantineInstanceHome({
+        return { unconfirmed: true, note: quarantineInstanceHome({
           home, instance, agent, soulDir: homeSoulTarget, soulId: preparedSoulId, incomplete, failed, outstandingHooks, outstandingGit,
           repoAbs, work, branch, resolvedCfg, hookMeta: hookRes.meta || {},
           launched: true, tmux: spawnTmux, directoryHome: homeReal, recordRetirementBaseline: true,
-        });
+        }) };
       }
     }
     // Once hooks ran, directory execution may already hold authored results.
@@ -3555,7 +3895,7 @@ function* spawnBody(root, agent, o = {}) {
         launched: false, directoryPreservation: true, directoryHome: homeReal,
         recordRetirementBaseline: true,
       });
-      return `${note}${directoryRecoveries.length ? `; prior work recovery: ${directoryRecoveries.join(", ")}` : ""}`;
+      return { unconfirmed: true, note: `${note}${directoryRecoveries.length ? `; prior work recovery: ${directoryRecoveries.join(", ")}` : ""}` };
     };
     const preserveDirectory = () => {
       if (work !== "directory") return;
@@ -3639,7 +3979,7 @@ function* spawnBody(root, agent, o = {}) {
       if (existsSync(home) && !incomplete.some((m) => m.startsWith("instance home"))) incomplete.push(`instance home ${home}: still present`);
       note = incomplete.length ? ` — rollback INCOMPLETE, clean up manually: ${incomplete.join("; ")}` : " — spawn rolled back";
     }
-    return `${note}${directoryRecoveries.length ? `; directory work preserved at ${directoryRecoveries.join(", ")}` : ""}`;
+    return { unconfirmed: incomplete.length > 0, note: `${note}${directoryRecoveries.length ? `; directory work preserved at ${directoryRecoveries.join(", ")}` : ""}` };
   };
 
   try {
@@ -3795,14 +4135,14 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
     if (work === "directory") assertDirectoryRoots(home, homeReal);
     const executionCommand = launch ? nativeRecordCommand(cmdline, home, harness) : null;
     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)}`);
-        shTry(`tmux set-option -t ${shq(session)} -g window-size latest`);
-        shTry(`tmux set-option -t ${shq(session)} -g aggressive-resize on`);
-      }
-      if (tmuxWindows(session).includes(instance)) throw new Error(`tmux window "${instance}" already exists in session ${session}`);
-      meta.tmux.socket = tmuxSocket(session);
+      // The session on the OATS server, then everything on the one socket that answered: the collision
+      // check, the records, the window and (in compensateSpawn) its removal.
+      const socket = ensureOatsTmuxSession(session, existsSync(root) ? root : workspaceOf(root), undefined, tmuxSessionPlan);
+      let present;
+      try { present = tmuxOn(socket, ["list-windows", "-t", `=${session}`, "-F", "#{window_name}"]).split("\n").filter(Boolean); }
+      catch (e) { throw new Error(`could not list the windows of tmux session ${session} on ${socket}: ${tmuxFailure(e, "tmux list-windows failed")}`); }
+      if (present.includes(instance)) throw new Error(`tmux window "${instance}" already exists in session ${session}`);
+      meta.tmux.socket = socket;
       meta.launched = true;
       // Commit the final child metadata and its independent byte authority before
       // the managed harness can write. No child-home transition follows launch.
@@ -3810,10 +4150,15 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
       writeRetirementBaseline(home, join(home, "work"), work, resolvedCfg.capabilities, { launched: true, tmux: meta.tmux });
       // Wrap the command so the window drops into an interactive shell when the
       // agent exits (e.g. Ctrl-C) instead of tmux killing the window.
-      const windowCmd = `${executionCommand}; exec "\${SHELL:-/bin/zsh}"`;
+      const windowCmd = paneCommand(executionCommand);
+      const paneEnvFlags = launchEnvRefs(recipe, process.env).flatMap((r) => ["-e", `${r.name}=${r.value}`]);
+      const launchFailed = (step, refused, e) => oatsError("E_SPAWN_LAUNCH_FAILED", `tmux ${step} failed for ${instance} (${e.code === "ENOENT" ? "tmux unavailable" : refused}); the command line and tmux's output are withheld from this message because they can carry reference values; run tmux -S ${shellWord(socket)} list-windows -t ${shellWord(session)} to inspect`);
       windowMayExist = true;
-      try { sh(`tmux new-window -t ${shq(session)} -n ${shq(instance)} -c ${shq(home)}${launchEnvTmuxFlags(recipe, process.env)} ${shq(windowCmd)}`); }
-      catch (e) { throw oatsError("E_SPAWN_LAUNCH_FAILED", `tmux new-window failed for ${instance} (${e.code === "ENOENT" ? "tmux unavailable" : "the window command was refused"}); the command line and tmux's output are withheld from this message because they can carry reference values; run tmux list-windows on the session to inspect`); }
+      let windowId;
+      try { windowId = tmuxOn(socket, ["new-window", "-P", "-F", "#{window_id}", "-t", `=${session}:`, "-n", instance, "-c", home, ...paneEnvFlags, windowCmd], undefined, oatsWindowEnvironment()).trim(); }
+      catch (e) { throw launchFailed("new-window", "the window command was refused", e); }
+      try { prepareAgentWindow(socket, windowId); }
+      catch (e) { throw launchFailed("set-option", "the new window's options were refused", e); }
     } else {
       meta.launched = false;
       writeFileSync(join(home, "instance.json"), JSON.stringify(meta, null, 2) + "\n");
@@ -3856,10 +4201,17 @@ ${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: `tmux attach -t ${session}`, warnings: spawnWarnings.length ? spawnWarnings : undefined });
+    return deliver({ ...meta, ...(o.expectDecision !== undefined ? { replayed: false } : {}), launch: redactLaunchRecipe(recipe), command: redactLaunchCommand(cmdline), attach: launch ? `tmux -S ${shellWord(meta.tmux.socket)} attach -t ${shellWord(session)}` : `oats session attach --home ${shellWord(home)}`, warnings: spawnWarnings.length ? spawnWarnings : undefined });
   } catch (error) {
-    const note = compensateSpawn();
-    error.message += note;
+    try {
+      const compensation = compensateSpawn();
+      error.message += compensation.note;
+      if (compensation.unconfirmed) unconfirmedSpawn(error);
+    } catch (cleanupError) {
+      // An interrupted compensation pass cannot establish that effects ended.
+      error.message += ` — rollback INCOMPLETE: cleanup could not be completed: ${cleanupError.message}`;
+      unconfirmedSpawn(error);
+    }
     throw error;
   }
 }
@@ -4378,15 +4730,6 @@ function fingerprintTree(root, { excludeRoot = new Set(), excludeGitMetadata = f
   return `sha256:${hash.digest("hex")}`;
 }
 
-/** The ref a worktree actually has checked out: `{branch, oid}` with
- *  `branch === null` when HEAD is detached. Recovery derives truth from the
- *  object, never from spawn-time metadata. */
-function worktreeRef(work) {
-  const oid = execFileSync("git", ["-C", work, "rev-parse", "HEAD"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER }).trim();
-  let branch = null;
-  try { branch = execFileSync("git", ["-C", work, "symbolic-ref", "--quiet", "--short", "HEAD"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER }).trim() || null; } catch { branch = null; }
-  return { branch, oid };
-}
 /** A worktree directory whose git admin entry is gone: no `.git`, an unreadable one, or a gitfile naming an
  *  admin directory that no longer exists. Read from the gitfile, not asked of git, which would walk up into
  *  whatever repository encloses the home. A `.git` directory is a repository of its own, not this case. */
@@ -4525,25 +4868,16 @@ function nestedGitRoots(root) {
   return out;
 }
 
-function branchOnlyCommits(repo, branch) {
-  if (!repo || !branch) return [];
-  const target = `refs/heads/${branch}`;
-  try {
-    execFileSync("git", ["-C", repo, "rev-parse", "--verify", "--quiet", target], { stdio: ["ignore", "pipe", "pipe"] , maxBuffer: GIT_MAX_BUFFER });
-  } catch (e) {
-    const detail = String(e.stderr ?? "").trim();
-    // A quarantine retry may follow a successful rollback-owned branch removal.
-    // Git's quiet exit 1 is authoritative absence, not an inspection failure.
-    if (e.status === 1 && !detail) return null;
-    throw oatsError("E_WORK_INSPECTION_FAILED", `could not inspect local branch reachability: ${detail || String(e.message ?? "").trim() || "git ref probe failed"}`);
-  }
-  try {
-    const refs = execFileSync("git", ["-C", repo, "for-each-ref", "--format=%(refname)"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] , maxBuffer: GIT_MAX_BUFFER })
-      .split("\n").filter((ref) => ref && ref !== target);
-    return execFileSync("git", ["-C", repo, "rev-list", target, ...(refs.length ? ["--not", ...refs] : [])], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER }).trim().split("\n").filter(Boolean);
-  } catch (e) {
-    throw oatsError("E_WORK_INSPECTION_FAILED", `could not inspect local branch reachability: ${String(e.stderr ?? e.message ?? "").trim() || "git ref probe failed"}`);
-  }
+/** Whether the recovery can copy the branch recorded at spawn: only when Git
+ *  shows it (exit 0). Asked by a quarantine retry for a worktree that is gone:
+ *  a failed spawn's rollback may have deleted the branch. A branch Git cannot
+ *  show (absent, or a damaged ref) is not copied; no retire deletes it, so it
+ *  stays in the repository, and the quarantine's own check of the branch says
+ *  whether it could be shown gone. */
+function recordedBranchExists(repo, branch) {
+  if (!repo || !branch) return true;
+  const r = spawnSync("git", ["-C", repo, "rev-parse", "--verify", "--quiet", `refs/heads/${branch}`], { stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER });
+  return !r.error && r.status === 0;
 }
 
 /** Herdr (removed in 0.31.0) is recognised in a home only to refuse: its instance.json records a
@@ -4616,16 +4950,28 @@ function tmuxServerLost(e) { return /no server running on |(?:error connecting t
  * The live processes (other than this one and its children) whose working
  * directory is inside `home`: `lsof -a -d cwd` over the host, one call.
  * → { ok: true, processes: [{pid, command}] } | { ok: false, error } (the scan
- * could not run: a caller must treat that as unknown, never as none).
+ * could not run, did not complete or listed no process: a caller must treat
+ * that as unknown, never as none).
  */
 export function processesInHome(home, io) {
   let out;
   try { out = (io?.exec || execFileSync)("lsof", ["-a", "-d", "cwd", "-F", "pRcn", "-w"], { encoding: "utf8", timeout: 20000, maxBuffer: 16 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] }); }
   catch (e) {
-    // lsof exits 1 with a full listing when some process could not be read; only no output is a failed scan.
-    if (typeof e?.stdout === "string" && /^p\d+$/m.test(e.stdout)) out = e.stdout;
-    else return { ok: false, error: e?.code === "ENOENT" ? "lsof is not on PATH" : String(e?.stderr || e?.message || "lsof failed").trim().split("\n")[0] };
-  }
+    // lsof exits 1 with a full listing when some process could not be read. That is the one failure
+    // whose output is a scan: lsof ended by itself with status 1 (no signal, and no error code, which
+    // Node sets when the capture itself failed: a timeout, too much output). A scan that was cut off
+    // is a failed scan whatever it printed first. The error says what happened, never a line of the
+    // listing.
+    const completed = e?.status === 1 && e.signal == null && e.code === undefined;
+    if (completed && typeof e.stdout === "string") out = e.stdout;
+    else return { ok: false, error: e?.code === "ENOENT" ? "lsof is not on PATH"
+      : e?.code === "ETIMEDOUT" ? "lsof timed out"
+      : e?.code === "ENOBUFS" ? "lsof printed more output than the scan reads"
+      : e?.signal ? `lsof was ended by ${e.signal}`
+      : String(e?.stderr || e?.message || "lsof failed").trim().split("\n")[0] };
+  }
+  // A listing holds at least one process (lsof and its caller are always in it), whichever exit it came with.
+  if (!/^p\d+$/m.test(String(out))) return { ok: false, error: "lsof listed no process" };
   const realHome = realPathOrNearest(home);
   const processes = [];
   let cur = {};
@@ -4817,8 +5163,8 @@ export function withLaunchModel(command, model) {
   return renderLaunchCommand(tokens);
 }
 
-function tmuxOn(socket, args, io) {
-  return (io?.exec || execFileSync)("tmux", ["-u", "-S", socket, ...args], { encoding: "utf8", timeout: 10000, maxBuffer: 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] });
+function tmuxOn(socket, args, io, env) {
+  return (io?.exec || execFileSync)("tmux", ["-u", "-S", socket, ...args], { encoding: "utf8", timeout: 10000, maxBuffer: 1024 * 1024, stdio: ["ignore", "pipe", "pipe"], ...(env ? { env } : {}) });
 }
 
 function writeJsonAtomic(path, value, mode) {
@@ -5123,6 +5469,9 @@ export function startInstanceSession(home, o = {}) {
     // A self-retirement leaves this marker while its detached teardown runs:
     // the home is about to disappear, so nothing is relaunched into it.
     if (existsSync(retirePendingMarkerPath(realHome))) throw oatsError("E_INSTANCE_RETIRING", `${basename(realHome)} is being retired (${retirePendingMarkerPath(realHome)} is present); nothing was started`);
+    // A start that leaves the server the home recorded says so: one line per move (see the docs'
+    // "Existing instances"), in the answer and as a launch-warning event.
+    const movedWarnings = [];
     // 1. Reconcile a pending receipt before the equality gate: it may be the
     //    only record of a session an earlier start allocated.
     if (existsSync(pendingPath)) {
@@ -5162,6 +5511,14 @@ export function startInstanceSession(home, o = {}) {
       // in whichever log the interrupted start did not record it.
       recordStartBoundary(realHome, { startId: pending.id, startedAt: pending.startedAt, harness: pending.harness ?? meta.harness ?? null, backend: "tmux", launchConfig: pending.launch?.launchConfig ?? meta.launch?.launchConfig ?? null, phase: "recovered" });
       const done = record(meta, { ...pending, model: pending.model ?? undefined, reused: "adopted" }, !st.present || st.state === "shell");
+      // The adopted target is on another server than the home recorded (the start that allocated it
+      // could not record it): this adoption records it, and says so once, here.
+      const recordedSocket = typeof meta.tmux?.socket === "string" && meta.tmux.socket ? resolve(meta.tmux.socket) : null;
+      if (recordedSocket && recordedSocket !== resolve(pending.target.socket)) {
+        const message = sessionMovedWarning(meta.instance, recordedSocket, resolve(pending.target.socket));
+        appendEvent(realHome, { kind: "launch-warning", data: { message } });
+        movedWarnings.push(message);
+      }
       if (st.present && st.state !== "shell") {
         if (o.restart) { rmSync(pendingPath, { force: true }); }
         else {
@@ -5170,7 +5527,7 @@ export function startInstanceSession(home, o = {}) {
           if (o.model != null && String(o.model).trim() && resolveModelPreference(String(o.model), done.harness || meta.harness) !== done.model) throw oatsError("E_SESSION_RUNNING", `${meta.instance} is already running with its previously requested model; its target was recovered, but the new model was not applied`);
           if (o.launchConfig !== undefined || o.harness !== undefined || o.yolo !== undefined) throw oatsError("E_SESSION_RUNNING", `${meta.instance} is already running (its pending start was recovered); the requested launch configuration, harness or yolo was not applied; stop it, or use session restart`);
           if (meta.startId === pending.id) throw oatsError("E_SESSION_RUNNING", `${meta.instance} is already running; nothing was started`);
-          return done;
+          return { ...done, warnings: [...done.warnings, ...movedWarnings] };
         }
       }
     }
@@ -5231,15 +5588,26 @@ export function startInstanceSession(home, o = {}) {
     checkRoots(); // preparation has run; no backend has been observed
     let target = receipt.target;
     let state = { present: false, state: "not-launched" };
-    let serverGone = false;
     if (target) {
       try { state = inspectSessionTarget(target, o.io); }
       catch (e) {
-        if (lostTmuxServer(e)) { serverGone = true; state = { present: false, state: "stopped" }; }
+        if (lostTmuxServer(e)) 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}`);
       }
     }
     if (state.present && state.state !== "shell" && !o.restart) throw oatsError("E_SESSION_RUNNING", `${meta.instance} is running (${state.state}); nothing was started`);
+    // A caller inside an instance that will have to create the tmux session reads the environment
+    // for it here (anyone else runs no tmux here): after the start's preflights and its planning,
+    // so each of their refusals still answers first, and before the real run of preview-aware
+    // launch hooks, a stop and any write of the home's launch state (record, receipt, pending
+    // start). A launch hook that does not declare launchPreview has already run and its warnings
+    // are already events (above), as before any other late refusal of a start (E_SESSION_RUNNING,
+    // E_LAUNCH_ENV_MISSING); nothing undoes what it did, and the hook contract (above
+    // prepareLaunchHooks) allows such a hook idempotent provider registration, which the next
+    // start repeats. Only when this start will have to create a window: a retained pane is reused
+    // where it is. A restart whose window goes away during its stop is decided at the creation.
+    const tmuxSessionPlan = callerInstance() && !(state.paneId && (state.present || state.state === "stopped"))
+      ? planOatsTmuxSession(target?.session || meta.tmux?.session || DEFAULT_TMUX_SESSION, o.io) : undefined;
     // Every preflight has passed: the preview-aware launch hooks run for real
     // (they may register the home with their provider), before a restart's
     // stop, and must contribute exactly what they contributed as a preview,
@@ -5278,7 +5646,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 (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)) 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.
@@ -5293,52 +5661,39 @@ export function startInstanceSession(home, o = {}) {
     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}"`;
+    const windowCmd = paneCommand(completedCommand);
+    let moved = null;
     // 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.
+    // the agent's own pane: the command runs there, on the server the home
+    // recorded, no other window touched and no option set.
     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); }
+      try { tmuxOn(socket, ["respawn-pane", "-k", "-t", state.paneId, "-c", realHome, ...paneEnvFlags, windowCmd], o.io, oatsWindowEnvironment()); }
       catch (e) { throw launchFailure(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(); }
-          }
-        }
-        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 = [];
+      // A replacement window (never launched, recorded window gone, recorded server gone) is created
+      // on the OATS server, wherever the home was recorded: one socket from here to the record.
+      const recordedSocket = socket ? resolve(socket) : null;
+      socket = ensureOatsTmuxSession(session, hq, o.io, tmuxSessionPlan);
+      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 (oatsCoded(e)) throw e;
+        throw oatsError("E_SESSION_UNKNOWN", `cannot list tmux windows on ${socket}: ${tmuxFailure(e, "tmux list-windows failed")}`);
       }
       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) };
+      target = { backend: "tmux", session, window, 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); }
+      try { prepareAgentWindow(socket, tmuxOn(socket, ["new-window", "-P", "-F", "#{window_id}", "-t", `=${session}:`, "-n", window, "-c", realHome, ...paneEnvFlags, windowCmd], o.io, oatsWindowEnvironment()).trim(), o.io); }
       catch (e) { throw launchFailure(e); }
+      if (recordedSocket && recordedSocket !== socket) moved = sessionMovedWarning(meta.instance, recordedSocket, socket);
     }
     target = { backend: "tmux", session, window, socket: resolve(socket) };
     // The session exists: its boundary (lib/instance-events.mjs) is recorded
@@ -5348,11 +5703,15 @@ export function startInstanceSession(home, o = {}) {
     // Keep launch evidence until the command exits or the target disappears.
     // A transient child (for example the native-start recorder) is not proof that startup
     // has finished. A later start reconciles the receipt without a watcher.
-    try { return { ...record(meta, { id, target, model, command, startedAt, reused, ...planExtra, ...(stopReceipt ? { stop: stopReceipt } : {}) }, false), warnings }; }
+    let done;
+    try { done = record(meta, { id, target, model, command, startedAt, reused, ...planExtra, ...(stopReceipt ? { stop: stopReceipt } : {}) }, false); }
     catch (e) {
       if (e.code && String(e.code).startsWith("E_")) throw e;
       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`);
     }
+    // Said once the new socket is recorded: a start that could not record leaves it to the adoption.
+    if (moved) { appendEvent(realHome, { kind: "launch-warning", data: { message: moved } }); movedWarnings.push(moved); }
+    return { ...done, warnings: [...warnings, ...movedWarnings] };
   } finally {
     // A hook may have replaced the home itself. Never follow that replacement
     // to remove a target's lock; keep the original retry state with its home.
@@ -5363,7 +5722,7 @@ export function startInstanceSession(home, o = {}) {
   }
 }
 
-function inspectRetirementWork(home, work, isWorktree, { branchDeletion, directory = false, orphanedWork = false } = {}) {
+function inspectRetirementWork(home, work, isWorktree, { recordedBranch, worktreeRemoval, directory = false, orphanedWork = false } = {}) {
   if (directory) assertDirectoryRoots(home);
   const classes = [];
   let baseline;
@@ -5390,8 +5749,13 @@ function inspectRetirementWork(home, work, isWorktree, { branchDeletion, directo
     // Never stamp hook-created or authored execution bytes as disposable.
     if (readdirSync(work).length) classes.push("directory work bytes");
   }
-  const branchCommits = !directory && branchDeletion?.delete ? branchOnlyCommits(branchDeletion.repo, branchDeletion.branch) : undefined;
-  if (branchCommits?.length) classes.push("branch-only local commits");
+  // For a quarantine retry whose worktree is gone, whether the recorded branch
+  // is still there to copy. Every other retire takes it to be there.
+  const branchExists = !directory && recordedBranch && !existsSync(work) ? recordedBranchExists(recordedBranch.repo, recordedBranch.branch) : true;
+  // A retire that will remove the worktree asks whether a ref that outlives it
+  // reaches its commit. `head` is kept for the check before the removal.
+  const unreached = worktreeRemoval?.removes && worktreeRemoval.repo && !directory && isWorktree && existsSync(work) ? worktreeCommitUnreached(worktreeRemoval.repo, work) : undefined;
+  if (unreached?.unreached) classes.push("worktree commits no ref reaches");
   if (isWorktree && existsSync(work)) {
     const status = worktreeStatus(work);
     const rows = status.split("\0").filter(Boolean);
@@ -5400,11 +5764,16 @@ function inspectRetirementWork(home, work, isWorktree, { branchDeletion, directo
     if (!baseline || baseline.generatedWorkFingerprint !== generatedWorkFingerprint(work, status, disposableRoots)) classes.push("untracked or ignored worktree bytes");
     if (nestedGitRoots(work).length) classes.push("nested repository state");
   }
+  // When the worktree will be removed, its HEAD and whether a ref reaches it are part of the state: a hook
+  // that commits on a detached HEAD, or deletes the ref that reached it, changes neither the home nor the
+  // status, and the commit must still be preserved again after it.
   const stateFingerprint = createHash("sha256")
     .update(fingerprintTree(home, { excludeRoot: new Set(["work"]), instanceHome: true }))
     .update("\0").update(directory ? (directoryFingerprint || "missing") : isWorktree && existsSync(work) ? worktreeStatus(work) : "")
+    .update("\0").update(unreached ? `${unreached.head.commit}\0${unreached.unreached ? "unreached" : "reached"}\0` : "")
+    .update(unreached?.head.ref ?? "")
     .digest("hex");
-  return { classes: [...new Set(classes)], home, work, directory, orphanedWork, directoryFingerprint, stateFingerprint, branchExists: branchCommits !== null, runtimeAuthority: baselineValid ? runtimeAuthorityOf(baseline) : undefined };
+  return { classes: [...new Set(classes)], home, work, directory, orphanedWork, directoryFingerprint, stateFingerprint, branchExists, head: unreached?.head, runtimeAuthority: baselineValid ? runtimeAuthorityOf(baseline) : undefined };
 }
 
 function copyRecoveryTree(src, dest, { excludeRoot = new Set() } = {}) {
@@ -5604,6 +5973,7 @@ function preserveRetirementWork(observation, meta, instance) {
   }
   const staging = mkdtempSync(join(recoveryRoot, `.${instance}-`));
   const recovery = join(recoveryRoot, basename(staging).slice(1));
+  let headUnreadable;
   try {
     // A home-only change (notes, harness files, credentials) needs a home
     // snapshot, not another copy of an otherwise disposable clean worktree.
@@ -5628,14 +5998,18 @@ function preserveRetirementWork(observation, meta, instance) {
       // The branch is derived from the worktree while it exists: an instance
       // that legitimately switched branches during its task must still be
       // recoverable, and the recorded spawn-time branch is only the fallback
-      // when the worktree is gone. Detached HEADs recover at their exact OID.
-      const ref = existsSync(observation.work) ? worktreeRef(observation.work) : { branch: meta.branch, oid: null };
-      if (ref.branch !== meta.branch) branchDrift = { recordedBranch: meta.branch, worktreeBranch: ref.branch, detachedAt: ref.branch === null ? ref.oid : null };
+      // when the worktree is gone. A HEAD that is detached, or on a ref OATS
+      // carries no name for, recovers detached at its exact commit. A HEAD
+      // that cannot be read is an inspection failure, not a failed copy.
+      let ref;
+      try { ref = existsSync(observation.work) ? worktreeHead(observation.work) : { branch: meta.branch, commit: null }; }
+      catch (e) { headUnreadable = e; throw e; }
+      if (ref.branch !== meta.branch) branchDrift = { recordedBranch: meta.branch, worktreeBranch: ref.branch, detachedAt: ref.branch === null ? ref.commit : null };
       if (ref.branch !== null) execFileSync("git", ["clone", "--no-local", "--quiet", "--branch", ref.branch, meta.repo, recoveredRepo], { stdio: ["ignore", "pipe", "pipe"] , maxBuffer: GIT_MAX_BUFFER });
       else {
         execFileSync("git", ["clone", "--no-local", "--quiet", "--no-checkout", meta.repo, recoveredRepo], { stdio: ["ignore", "pipe", "pipe"] , maxBuffer: GIT_MAX_BUFFER });
-        execFileSync("git", ["-C", recoveredRepo, "fetch", "--quiet", observation.work, ref.oid], { stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER });
-        execFileSync("git", ["-C", recoveredRepo, "checkout", "--quiet", "--detach", ref.oid], { stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER });
+        execFileSync("git", ["-C", recoveredRepo, "fetch", "--quiet", observation.work, ref.commit], { stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER });
+        execFileSync("git", ["-C", recoveredRepo, "checkout", "--quiet", "--detach", ref.commit], { stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER });
       }
       const sourceGitContext = existsSync(observation.work) ? observation.work : meta.repo;
       detachRecoveryClone(sourceGitContext, recoveredRepo);
@@ -5657,10 +6031,15 @@ function preserveRetirementWork(observation, meta, instance) {
         if (fingerprintTree(observation.work, { excludeRoot: new Set([".git"]), excludeGitMetadata: true }) !== fingerprintTree(recoveredRepo, { excludeRoot: new Set([".git"]), excludeGitMetadata: true })) throw new Error("worktree recovery verification disagreed with the source");
         assertStatusAgrees(observation.work, recoveredRepo, "recovered Git index/status disagreed with the source", ".");
       }
+      // The proof of the copy: its HEAD is the commit the worktree has checked
+      // out. A branch of the repository can be at another commit with the
+      // same files, so the branch's tip there proves nothing about the copy.
+      // With the worktree gone there is no such commit to read, and the copy
+      // is the recorded branch as the repository has it.
       const recoveredHead = execFileSync("git", ["-C", recoveredRepo, "rev-parse", "HEAD"], { encoding: "utf8" , maxBuffer: GIT_MAX_BUFFER }).trim();
-      const sourceHead = ref.branch === null ? ref.oid
-        : execFileSync("git", ["-C", meta.repo, "rev-parse", `refs/heads/${ref.branch}`], { encoding: "utf8" , maxBuffer: GIT_MAX_BUFFER }).trim();
-      if (recoveredHead !== sourceHead) throw new Error("recovery clone does not retain the instance branch tip");
+      const sourceHead = ref.commit
+        ?? execFileSync("git", ["-C", meta.repo, "rev-parse", `refs/heads/${ref.branch}`], { encoding: "utf8" , maxBuffer: GIT_MAX_BUFFER }).trim();
+      if (recoveredHead !== sourceHead) throw new Error(ref.commit ? "recovery clone is not at the commit the worktree has checked out" : "recovery clone does not retain the instance branch tip");
     }
     if (observation.directory && observation.directoryFingerprint) {
       const recoveredWork = join(staging, "work");
@@ -5680,6 +6059,7 @@ function preserveRetirementWork(observation, meta, instance) {
     return { path: recovery, classes: observation.classes, bytes, ...(outputs ? { outputs } : {}), ...(repoCopy ? { repoCopy } : {}) };
   } catch (e) {
     rmSync(staging, { recursive: true, force: true });
+    if (e === headUnreadable) throw e;
     const details = e.statusDisagreement ? { home: observation.home, statusDisagreement: e.statusDisagreement } : undefined;
     throw Object.assign(oatsError("E_WORK_PRESERVATION_FAILED", `retirement work remains at ${observation.home}; recovery could not be verified: ${e.message}`, details), details ? { details } : {});
   }
@@ -5729,7 +6109,7 @@ function scheduleDeferredSelfRetirement(root, found, name, o, session) {
   const intent = {
     instance: name, agent: found.agent.name, root: resolve(root),
     requestedAt: new Date().toISOString(), requestedByPid: process.pid, delaySec,
-    options: { home: found.home, deleteBranch: !!o.deleteBranch, ...(o.keepDir ? { keepDir: true } : {}), tmuxSession: session }, resultPath,
+    options: { home: found.home, ...(o.keepDir ? { keepDir: true } : {}), tmuxSession: session }, resultPath,
   };
   const env = { ...process.env, OATS_RETIRE_INTENT: JSON.stringify(intent) };
   for (const k of CORE_LAUNCH_ENV) delete env[k];
@@ -5771,6 +6151,16 @@ function scheduleDeferredSelfRetirement(root, found, name, o, session) {
  *  (and, after hooks ran, the usual quarantine) in place, so `oats status`
  *  shows the debt and `oats retire <name>` retries and clears it. Accepts the
  *  intent object (the child gets it in its env) or a marker path. */
+/** The item a quarantine retry reports while the branch its failed spawn created is still there. It
+ *  names no branch: the name is the receipt's `retention.recordedBranch`, or the retained home's
+ *  instance.json `branch`. */
+export const FAILED_SPAWN_BRANCH_LEFT = "the branch the failed spawn created is left: OATS does not delete it. Inspect it and delete it with Git if it is not wanted, then retry";
+const OBSOLETE_DELETE_BRANCH_SENTENCE = "this self-retire was requested with --delete-branch by an older OATS; retirement no longer deletes branches, so the branch and the worktree were left";
+/** The one internal option that says the retirement completes such an intent.
+ *  A symbol, so no caller can set it from parsed arguments or JSON. */
+const OBSOLETE_DELETE_BRANCH = Symbol("an older self-retire intent with --delete-branch");
+export const RETIRE_DELETE_BRANCH_REFUSED = "oats retire no longer deletes branches: --delete-branch is not accepted. Retire without it; the branch is left in the repository. Inspect it there and delete it with Git if it is no longer wanted.";
+
 export function completeDeferredRetirement(intentOrMarkerPath, opts = {}) {
   let intent = intentOrMarkerPath;
   if (typeof intentOrMarkerPath === "string") {
@@ -5787,18 +6177,24 @@ export function completeDeferredRetirement(intentOrMarkerPath, opts = {}) {
       }, null, 2) + "\n");
     } catch (e) { console.error(`deferred retirement: cannot write ${intent.resultPath}: ${e.message}`); }
   };
+  // An intent an older OATS recorded for `--self --delete-branch`. The
+  // retirement it owes is completed; the obsolete option authorizes nothing:
+  // the branch and the worktree are left, and the retire says so.
+  const obsoleteDeleteBranch = intent.options?.deleteBranch === true;
   const delayMs = Math.max(0, Number(opts.delaySec ?? intent.delaySec ?? 8) * 1000);
   if (delayMs) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, delayMs);
   let result;
   try {
     result = retireInstance(intent.root, intent.instance, {
-      home: intent.options?.home, deleteBranch: !!intent.options?.deleteBranch, keepDir: !!intent.options?.keepDir, tmuxSession: intent.options?.tmuxSession,
+      home: intent.options?.home, keepDir: !!intent.options?.keepDir, tmuxSession: intent.options?.tmuxSession,
+      ...(obsoleteDeleteBranch ? { [OBSOLETE_DELETE_BRANCH]: true } : {}),
     });
   } catch (e) {
-    record({ ok: false, error: { code: e.code, message: e.message }, retry: `oats retire ${intent.instance}${intent.options?.home ? ` --home ${intent.options.home}` : ""}` });
+    record({ ok: false, error: { code: e.code, message: e.message }, ...(obsoleteDeleteBranch ? { warnings: [OBSOLETE_DELETE_BRANCH_SENTENCE] } : {}), retry: `oats retire ${intent.instance}${intent.options?.home ? ` --home ${intent.options.home}` : ""}` });
     console.error(`deferred retirement of ${intent.instance} failed: ${e.message}`);
     return false;
   }
+  if (obsoleteDeleteBranch) console.log(OBSOLETE_DELETE_BRANCH_SENTENCE);
   if (result.rollbackIncomplete) {
     record({ ok: false, result, retry: `oats retire ${intent.instance}${intent.options?.home ? ` --home ${intent.options.home}` : ""}` });
     console.error(`deferred retirement of ${intent.instance} is INCOMPLETE; the home is retained:\n  ${result.rollbackIncomplete.join("\n  ")}`);
@@ -5818,6 +6214,7 @@ export function completeDeferredRetirement(intentOrMarkerPath, opts = {}) {
 }
 
 export function retireInstance(root, name, o = {}) {
+  if (o.deleteBranch) throw oatsError("E_BAD_ARGS", RETIRE_DELETE_BRANCH_REFUSED);
   const session = o.tmuxSession || DEFAULT_TMUX_SESSION;
   // self-retire: the caller IS the instance. Without --keep-dir the whole
   // retirement is deferred to a detached external completion (below); with
@@ -5929,8 +6326,10 @@ export function retireInstance(root, name, o = {}) {
   // First inspection is non-destructive. Only after it succeeds may OATS quiesce
   // the managed harness; recovery copying never races a live managed Pi.
   const owesWorktree = !!quarantine && (quarantine.cleanup.outstanding?.git || []).includes("worktree");
-  const branchDeletion = { delete: !!(o.deleteBranch || quarantine), repo: meta.repo, branch: meta.branch };
-  const initialObservation = inspectRetirementWork(found.home, workPath, inspectableWorktree, { branchDeletion, directory, orphanedWork });
+  const recordedBranch = quarantine ? { repo: meta.repo, branch: meta.branch } : undefined;
+  // Whether this retire removes the worktree, when it gets to that step.
+  const worktreeRemoval = { removes: !!(o.discardWorktree || owesWorktree), repo: meta.repo };
+  const initialObservation = inspectRetirementWork(found.home, workPath, inspectableWorktree, { recordedBranch, worktreeRemoval, directory, orphanedWork });
   // Harness identity is destructive authority. The mutable child metadata may
   // describe it for humans, but only the independent baseline can authorize the
   // endpoint that proves quiescence.
@@ -5973,10 +6372,20 @@ export function retireInstance(root, name, o = {}) {
       if (windows.includes(runtimeWindow)) throw new Error(`tmux window ${runtimeSession}:${runtimeWindow} is still running`);
     } catch (e) {
       const detail = String(e.stderr ?? e.message ?? "").trim();
-      if (!/no server running|failed to connect|can't find session|no sessions/i.test(detail)) throw oatsError("E_RUNTIME_QUIESCE_FAILED", `could not establish that ${runtimeSession}:${runtimeWindow} stopped on ${runtimeSocket}: ${detail || "tmux inspection failed"}`);
+      const unestablished = (why) => oatsError("E_RUNTIME_QUIESCE_FAILED", `could not establish that ${runtimeSession}:${runtimeWindow} stopped on ${runtimeSocket}: ${why}`);
+      if (!/no server running|failed to connect|can't find session|no sessions/i.test(detail)) {
+        if (!tmuxServerLost(e)) throw unestablished(detail || "tmux inspection failed");
+        // A server that cannot be reached, typically because its socket file is missing (a reboot clears
+        // tmux's socket directory). A server outlives its socket file, so that alone does not say the
+        // window is gone: it is taken as gone only when no process works in the home, as for a home
+        // without its receipt.
+        const scan = processesInHome(found.home);
+        if (!scan.ok) throw unestablished(`${detail}; whether a process still works in this home could not be established (${scan.error})`);
+        if (scan.processes.length) throw unestablished(`${detail}; a process still works in this home (${scan.processes.slice(0, 5).map((p) => `pid ${p.pid} ${p.command}`).join(", ")}${scan.processes.length > 5 ? `, and ${scan.processes.length - 5} more` : ""})`);
+      }
     }
   }
-  const stableObservation = inspectRetirementWork(found.home, workPath, inspectableWorktree, { branchDeletion, directory, orphanedWork });
+  const stableObservation = inspectRetirementWork(found.home, workPath, inspectableWorktree, { recordedBranch, worktreeRemoval, directory, orphanedWork });
   const workRecoveries = [];
   if (stableObservation.classes.length) workRecoveries.push(preserveRetirementWork(stableObservation, meta, name));
   let workRecovery = workRecoveries.at(-1);
@@ -6055,7 +6464,7 @@ export function retireInstance(root, name, o = {}) {
 
   // Hooks are allowed to mutate the inspected tree, so inspect again after
   // them and preserve a separately verified post-hook snapshot when needed.
-  const finalObservation = inspectRetirementWork(found.home, workPath, inspectableWorktree, { branchDeletion, directory, orphanedWork });
+  const finalObservation = inspectRetirementWork(found.home, workPath, inspectableWorktree, { recordedBranch, worktreeRemoval, directory, orphanedWork });
   if (finalObservation.classes.length && finalObservation.stateFingerprint !== stableObservation.stateFingerprint) {
     workRecoveries.push(preserveRetirementWork(finalObservation, meta, name));
     workRecovery = workRecoveries.at(-1);
@@ -6117,32 +6526,39 @@ export function retireInstance(root, name, o = {}) {
   // branch and any PR outlive the home. The worktree cannot stay under
   // <home>/work once the home is removed, so it is RE-HOMED with
   // `git worktree move` to the deployment-level worktrees root and the move is
-  // recorded in the receipt. `discardWorktree` restores removal; branch
-  // deletion uses the VERIFIED current ref of the worktree, never the
-  // spawn-time recorded name. A failed move keeps the home (fail closed).
+  // recorded in the receipt. `discardWorktree` restores removal. No retire
+  // deletes a branch. A failed move keeps the home (fail closed).
   // The worktree step runs only once nothing else is outstanding (awebai/oats#444): a hook that did not finish
   // may need the worktree, and its retry needs the home, the worktree and its admin entry exactly as they
   // were. --force removes the home regardless, so the step runs first and no admin entry is left dangling.
   // A failed spawn's quarantine that owes the worktree removes it; any other retire retains it unless
-  // --discard-worktree or --delete-branch. An orphaned work directory is never touched.
+  // --discard-worktree. An orphaned work directory is never touched.
   const outstandingBeforeWorktree = quarantine ? retryFailures : ordinaryIncomplete;
   const worktreeStep = isWorktree && !!meta.repo && !orphanedWork;
   const worktreeDeferred = worktreeStep && existsSync(workPath) && outstandingBeforeWorktree.length > 0 && !o.force;
   const keptForRetry = worktreeDeferred ? `git worktree ${workPath}: kept for the retry; outstanding: ${outstandingBeforeWorktree.join("; ")}` : null;
   let retention = null;
   if (worktreeStep && !worktreeDeferred) {
-    const ref = existsSync(workPath) ? (() => { try { return worktreeRef(workPath); } catch { return { branch: null, oid: null }; } })() : { branch: meta.branch ?? null, oid: null };
+    // A HEAD that cannot be read here is recorded as no branch and no commit, and the worktree is retained.
+    const ref = existsSync(workPath) ? (() => { try { return worktreeHead(workPath); } catch { return { branch: null, commit: null }; } })() : { branch: meta.branch ?? null, commit: null };
     const verifiedBranch = ref.branch;
-    // A branch cannot be deleted while a worktree has it checked out, so
-    // --delete-branch implies discarding the worktree (which is what every
-    // caller of it meant: clean up everything). Plain retire retains.
-    if (o.discardWorktree || o.deleteBranch || owesWorktree) {
+    // --discard-worktree, or a quarantine that owes the worktree, removes it. Plain retire retains.
+    if (worktreeRemoval.removes) {
+      // HEAD as it is now against HEAD as the final inspection read it: a
+      // worktree whose HEAD moved since is not removed, and nothing else is
+      // done. Whatever moved it may have made a commit only it reaches.
+      if (existsSync(workPath)) {
+        let now;
+        try { now = worktreeHead(workPath); }
+        catch (e) { throw oatsError("E_WORK_INSPECTION_FAILED", `${e.message}. The worktree was not removed. The home and the worktree are kept, and so is any recovery the retire wrote; retry the retire.`); }
+        assertSameWorktreeHead(finalObservation.head, now);
+      }
       shTry(`git -C ${shq(meta.repo)} worktree remove --force ${shq(workPath)}`);
       shTry(`git -C ${shq(meta.repo)} worktree prune`);
       retention = { worktree: "removed", branch: verifiedBranch, recordedBranch: meta.branch ?? null };
     } else if (existsSync(workPath)) {
       const repoName = basename(realPathOrNearest(meta.repo)).replace(/\.git$/, "") || "repo";
-      const leaf = (verifiedBranch ?? `detached-${(ref.oid || "unknown").slice(0, 12)}`).replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "work";
+      const leaf = (verifiedBranch ?? `detached-${(ref.commit || "unknown").slice(0, 12)}`).replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "work";
       const retainedRoot = join(workspaceOf(root), ".agents", "worktrees", repoName);
       mkdirSync(retainedRoot, { recursive: true });
       let dest = join(retainedRoot, leaf);
@@ -6152,32 +6568,18 @@ export function retireInstance(root, name, o = {}) {
       } catch (e) {
         throw oatsError("E_WORK_PRESERVATION_FAILED", `${name}: the worktree at ${workPath} could not be re-homed to ${dest} (${String(e.stderr ?? e.message ?? "").trim()}); the home is kept so nothing is lost — resolve and retry, or pass --discard-worktree to remove the worktree instead`);
       }
-      retention = { worktree: "retained", movedTo: dest, branch: verifiedBranch, detachedAt: verifiedBranch === null ? ref.oid : null, recordedBranch: meta.branch ?? null };
+      retention = { worktree: "retained", movedTo: dest, branch: verifiedBranch, detachedAt: verifiedBranch === null ? ref.commit : null, recordedBranch: meta.branch ?? null };
     } else retention = { worktree: "absent", branch: verifiedBranch, recordedBranch: meta.branch ?? null };
-    if (o.deleteBranch && verifiedBranch) {
-      // A plan-driven caller passes the branch it CONFIRMED. Hooks may mutate
-      // the tree during retirement, so the branch is re-verified here, at the
-      // moment of deletion; a mismatch deletes nothing and says so.
-      if (o.expectedBranch !== undefined && o.expectedBranch !== verifiedBranch) {
-        retention.branchDeletionSkipped = { expected: o.expectedBranch, actual: verifiedBranch, reason: "the worktree's branch changed between confirmation and deletion; nothing was deleted" };
-      } else {
-        shTry(`git -C ${shq(meta.repo)} branch -D ${shq(verifiedBranch)}`);
-        retention.branchDeleted = verifiedBranch;
-      }
-    } else if (o.deleteBranch && !verifiedBranch && o.expectedBranch !== undefined) {
-      retention.branchDeletionSkipped = { expected: o.expectedBranch, actual: null, reason: "the worktree was detached or absent at deletion time; nothing was deleted" };
-    }
   }
   if (retention) {
     if (retention.worktree === "retained") appendEvent(found.home, { kind: "worktree-retained", data: { movedTo: retention.movedTo, branch: retention.branch, recordedBranch: retention.recordedBranch } }, { workspaceOnly: true });
     else if (retention.worktree === "removed") appendEvent(found.home, { kind: "worktree-removed", data: { branch: retention.branch } }, { workspaceOnly: true });
-    if (retention.branchDeleted) appendEvent(found.home, { kind: "branch-deleted", data: { branch: retention.branchDeleted } }, { workspaceOnly: true });
   }
   // `hooks`: which retire hooks ran (in order) and how each ended — the same
   // receipt `spawned` carries, so the workspace log shows both halves of a
   // capability's lifecycle after the home is gone.
   const retireHookReceipt = (() => { const res = hookResults || {}; const failedBy = new Map((res.failures || []).map((f) => [f.capability, f])); return (res.order || []).map((id) => ({ capability: id, ok: !failedBy.has(id), meta: Object.hasOwn(res.meta || {}, id) })); })();
-  appendEvent(found.home, { kind: "retired", data: { agent: found.agent.name, keepDir: !!o.keepDir, self, quarantine: !!quarantine, workRecovery: workRecovery?.path ?? null, hooks: retireHookReceipt } }, { workspaceOnly: true });
+  appendEvent(found.home, { kind: "retired", data: { agent: found.agent.name, keepDir: !!o.keepDir, self, quarantine: !!quarantine, workRecovery: workRecovery?.path ?? null, hooks: retireHookReceipt, ...(o[OBSOLETE_DELETE_BRANCH] ? { reason: OBSOLETE_DELETE_BRANCH_SENTENCE } : {}) } }, { workspaceOnly: true });
   // Retrying a quarantine only clears it if compensation ACTUALLY completed.
   // Otherwise the home — and the credentials in it — must survive again, or the
   // retry becomes the deletion the quarantine was preventing.
@@ -6209,18 +6611,18 @@ export function retireInstance(root, name, o = {}) {
     const failures = [...retryFailures];
     if (keptForRetry) failures.push(keptForRetry);
     // The quarantine may exist BECAUSE Git cleanup failed, so a retry has to
-    // redo those steps and verify them — not just rerun hooks. A branch is never
-    // deleted here: only --delete-branch deletes one (the verified branch, above).
+    // redo those steps and verify them — not just rerun hooks. No retire deletes a branch.
     if (meta.work === "worktree" && meta.repo) {
       const gitProbe = (argv) => {
         try { return { ok: true, out: execFileSync(argv[0], argv.slice(1), { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }) }; }
         catch (e2) { return { ok: false, status: e2.status, err: String(e2.stderr ?? e2.message ?? "").trim() }; }
       };
       // A worktree this retry removed (the step above ran) must be verified gone; one it retained or kept for
-      // the next retry stays registered by design.
+      // the next retry stays registered by design. The removal is not attempted a second time here: only the
+      // worktree step removes, after its check of HEAD, so a worktree it failed to remove is still registered
+      // and the next retry goes through that step again.
       if (retention?.worktree === "removed") {
         const wtCanonical = realPathOrNearest(workPath);
-        gitProbe(["git", "-C", meta.repo, "worktree", "remove", "--force", workPath]);
         gitProbe(["git", "-C", meta.repo, "worktree", "prune"]);
         const wtProbe = gitProbe(["git", "-C", meta.repo, "worktree", "list", "--porcelain", "-z"]);
         if (!wtProbe.ok) failures.push(`git worktree ${wtCanonical}: could not verify removal (${wtProbe.err || "worktree list failed"})`);
@@ -6229,25 +6631,16 @@ export function retireInstance(root, name, o = {}) {
           if (registered.includes(wtCanonical)) failures.push(`git worktree ${wtCanonical}: still registered`);
         }
       }
-      // The branch is a debt only when the failed spawn's rollback still owes its deletion, or when the
-      // operator asked for it (--delete-branch); then it must be verified gone, and a branch kept is said.
-      // --delete-branch: the branch the documented path deleted (the verified one) must be gone. A failed
-      // spawn's quarantine that owes its recorded branch keeps it unless that branch was the one deleted.
-      const verify = (branch) => {
-        const br = gitProbe(["git", "-C", meta.repo, "rev-parse", "--verify", "--quiet", `refs/heads/${branch}`]);
-        if (br.ok) return "exists";
-        if (br.status !== 1 || br.err) { failures.push(`git branch ${branch}: could not verify whether it still exists (${br.err || `rev-parse exit ${br.status}`})`); return "unknown"; }
-        return "gone";
-      };
-      const deleted = retention?.branchDeleted;
-      if (deleted && verify(deleted) === "exists") failures.push(`git branch ${deleted}: still exists`);
+      // The branch is a debt only when the failed spawn's rollback still owes its deletion. A retry never
+      // deletes it: the debt is cleared only when the branch is shown to be gone. Git's quiet exit 1 is
+      // "gone"; any other answer, or any text on standard error (a damaged ref file warns there), is
+      // "could not verify", and the debt stays. The text is never matched: this read can only err
+      // toward keeping the debt.
       const owesBranch = (quarantine.cleanup.outstanding?.git || []).includes("branch");
-      if (owesBranch && meta.branch && meta.branch !== deleted && verify(meta.branch) === "exists") {
-        // Without a home left to retry from (--force), or when --delete-branch verified another branch, the
-        // recorded branch is the operator's to delete by hand.
-        failures.push(o.force || o.deleteBranch
-          ? `git branch ${meta.branch}: kept; the failed spawn created it; delete it with git branch -D ${meta.branch} if unwanted`
-          : `git branch ${meta.branch}: kept; the failed spawn created it; pass --delete-branch to delete it`);
+      if (owesBranch && meta.branch) {
+        const br = spawnSync("git", ["-C", meta.repo, "rev-parse", "--verify", "--quiet", `refs/heads/${meta.branch}`], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+        if (!br.error && br.status === 0) failures.push(FAILED_SPAWN_BRANCH_LEFT);
+        else if (br.error || br.status !== 1 || br.stderr.length) failures.push(`git branch ${meta.branch}: could not verify whether it still exists (${String(br.stderr ?? "").trim() || br.error?.message || `rev-parse exit ${br.status}`})`);
       }
     }
     // Git debt is proven by the verification block above, which only runs for a
@@ -6280,8 +6673,9 @@ export function retireInstance(root, name, o = {}) {
     rmSync(deferredRetireResultPath(found.home).replace(/\.json$/, ".log"), { force: true });
   }
 
-  const result = { retired: name, agent: found.agent.name, workRecovery, workRecoveries: workRecoveries.length > 1 ? workRecoveries : undefined, retention, worktreeRemoved: isWorktree && !!retention && retention.worktree !== "retained", branchDeleted: !!(retention?.branchDeleted), removedDir: !o.keepDir && (!stillIncomplete || forced), rollbackIncomplete: forced ? undefined : stillIncomplete, forcedIncomplete: forced ? stillIncomplete : undefined, retainedHome: stillIncomplete && !forced ? found.home : undefined, relinked: relinked.length ? relinked : undefined, capabilityMeta: hookResults?.meta, warnings: (() => {
+  const result = { retired: name, agent: found.agent.name, workRecovery, workRecoveries: workRecoveries.length > 1 ? workRecoveries : undefined, retention, worktreeRemoved: isWorktree && !!retention && retention.worktree !== "retained", branchDeleted: false, removedDir: !o.keepDir && (!stillIncomplete || forced), rollbackIncomplete: forced ? undefined : stillIncomplete, forcedIncomplete: forced ? stillIncomplete : undefined, retainedHome: stillIncomplete && !forced ? found.home : undefined, relinked: relinked.length ? relinked : undefined, capabilityMeta: hookResults?.meta, warnings: (() => {
     const w = [...(hookResults?.warnings || [])];
+    if (o[OBSOLETE_DELETE_BRANCH]) w.push(OBSOLETE_DELETE_BRANCH_SENTENCE);
     if (isCapturedHome(meta) && !quarantine) {
       // A captured home retires through the workspace path; its captured retire hooks do not
       // run (lead decisions on (e), D1), so each capability whose spawn hook ran is named.
@@ -6298,7 +6692,15 @@ export function retireInstance(root, name, o = {}) {
     // 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'`);
+    // On the socket the receipt (else instance.json) records, both the scheduling and the kill; a home
+    // that records none keeps the ambient server. run-shell expands its command as a format: a
+    // literal # in the socket path is written ##.
+    const killSocket = runtimeAuthority?.tmux?.socket || meta?.tmux?.socket;
+    const killTarget = shq(`=${killSession}:=${killWindow}`);
+    if (typeof killSocket === "string" && killSocket) {
+      const kill = `sleep ${o.selfKillDelaySec ?? 8}; tmux -u -S ${shq(killSocket)} kill-window -t ${killTarget} 2>/dev/null || true`;
+      shTry(`tmux -u -S ${shq(killSocket)} run-shell -b ${shq(kill.replace(/#/g, "##"))}`);
+    } else shTry(`tmux run-shell -b 'sleep ${o.selfKillDelaySec ?? 8}; tmux kill-window -t ${killTarget} 2>/dev/null || true'`);
     result.selfKillScheduled = true;
   }
   return result;