@awebai/oats 0.41.1 → 0.42.0

package/lib/core.mjs

@@ -43,10 +43,11 @@ import { attachSessionTarget } from "./session-viewer.mjs";
 import { inspectSessionTarget, inputSessionTarget } from "./session-input.mjs";
 import { appendEvent, liveWaiting, recordStartBoundary } from "./instance-events.mjs";
 import { killGroup } from "./process-group.mjs";
+import { captureLoginEnvironment } from "./login-environment.mjs";
 
 import { oatsError, herdrInstanceBusy, herdrInstanceRemoved, herdrSettingRemoved, HERDR_REMOVED } from "./errors.mjs";
 import { envRows, recordedTeams, teamsEnv } from "./teams.mjs";
-import { harnessUnavailable, launchConfigUnknown, launchLayers, launchReport, selectionFrom } from "./launch-preference.mjs";
+import { PANE_PATH_FIX, harnessNotOnPanePath, harnessUnavailable, launchConfigUnknown, launchLayers, launchReport, selectionFrom } from "./launch-preference.mjs";
 import { claudeTrusts, codexTrustsRoot, harnessTrustWarning } from "./harness-trust.mjs";
 async function materializePreparedDefault(prepared, home) { const m = await import("./instance-resolution.mjs"); return m.materializePrepared(prepared, home); }
 // Capability rows for a PREPARED spawn (workspace model): the one function that
@@ -60,15 +61,17 @@ import { GIT_FETCH_TIMEOUT_MS, GIT_TIMEOUT_MS, gitEnv } from "./remote.mjs";
 import { loadLocal } from "./workspace.mjs";
 import { parseConfigData } from "./config-data.mjs";
 import { renderInstructionText } from "./instruction-composition.mjs";
-import { APPROVED_HOOKS, PORTABLE_ENV_NAME_RE, CORE_LAUNCH_ENV, PROCESS_BOOTSTRAP_ENV, PROCESS_BOOTSTRAP_PREFIXES, manifestContractProblems } from "./capability-contract.mjs";
+import { APPROVED_HOOKS, PORTABLE_ENV_NAME_RE, CORE_LAUNCH_ENV, PROCESS_BOOTSTRAP_ENV, PROCESS_BOOTSTRAP_PREFIXES, manifestContractProblems, disposableHomeRootProblem, disposableHomeRootMatches } from "./capability-contract.mjs";
 import { validateBindingInterface } from "./provider-binding.mjs";
-/** Retirement/rollback tree fingerprint (exported for scope tests: kernel-field neutrality is opt-in per instance home). */
-export { fingerprintTree };
+/** Retirement/rollback tree fingerprint (exported for scope tests: kernel-field neutrality is opt-in per instance home),
+ *  the exact digest a copied path is compared with (exported so a test holds it to the copier),
+ *  and the receipts the stored digest passes over in a home (exported so a test holds the manifest grammar to refusing each of them). */
+export { exactTreeDigest, fingerprintTree, KERNEL_HOME_RECEIPTS };
 
 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";
+import { assertSameWorktreeHead, headName, 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._-]*$/;
@@ -572,7 +575,9 @@ const LAUNCH_CONFIG_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
 const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 /** Environment the kernel sets for every launch (identity, home, roots) and
  *  its reference aliases: a configuration may not name them. */
-export const RESERVED_LAUNCH_ENV = new Set(["OATS_INSTANCE", "OATS_INSTANCE_HOME", "OATS_HOME", "OATS_AGENT", "OATS_SOUL", "OATS_SOUL_ID", "OATS_ROOT", "OATS_CONTEXT", "OATS_WORKSPACE", "OATS_EVENT", "OATS_SETTINGS", "OATS_SETTINGS_ORIGINS", "OATS_CLI_BIN", "PI_AGENT_INSTANCE", "PI_AGENT_HOME", "PI_AGENTS_ROOT"]);
+export const RESERVED_LAUNCH_ENV = new Set(["OATS_INSTANCE", "OATS_INSTANCE_HOME", "OATS_HOME", "OATS_AGENT", "OATS_SOUL", "OATS_SOUL_ID", "OATS_ROOT", "OATS_CONTEXT", "OATS_WORKSPACE", "OATS_EVENT", "OATS_SETTINGS", "OATS_SETTINGS_ORIGINS", "OATS_CLI_BIN", "PI_AGENT_INSTANCE", "PI_AGENT_HOME", "PI_AGENTS_ROOT",
+  // The test seam that replaces the login shell (lib/login-environment.mjs): never a launch's to set.
+  "OATS_TEST_LOGIN_SHELL"]);
 export const LAUNCH_REF_PREFIX = "OATS_LAUNCH_REF_";
 const reservedLaunchEnv = (n) => RESERVED_LAUNCH_ENV.has(n) || n.startsWith(LAUNCH_REF_PREFIX);
 export function validateLaunchConfig(name, entry, where) {
@@ -681,19 +686,10 @@ function validateCapabilityManifest(m, mf) {
   // has one flat name space per organisation instead (duplicate → E_CAPABILITY_AMBIGUOUS
   // at resolution), so the grammar is the only requirement.
   if (!/^[a-z0-9][a-z0-9._-]*$/.test(id)) throw new Error(`capability ID must match ^[a-z0-9][a-z0-9._-]*$: "${id}" (${mf})`);
-  if (m.retirement !== undefined) {
-    if (!isPlainObject(m.retirement) || !isPlainObject(m.retirement.disposable)) throw new Error(`capability ${id} manifest retirement must contain a disposable map`);
-    const unknown = Object.keys(m.retirement).filter((key) => key !== "disposable");
-    const scopes = Object.keys(m.retirement.disposable).filter((key) => !["home", "work"].includes(key));
-    if (unknown.length || scopes.length) throw new Error(`capability ${id} manifest retirement has unsupported keys: ${[...unknown, ...scopes].join(", ")}`);
-    for (const scope of ["home", "work"]) {
-      const roots = m.retirement.disposable[scope];
-      if (roots !== undefined && (!Array.isArray(roots) || roots.some((root) => typeof root !== "string"))) throw new Error(`capability ${id} manifest retirement.disposable.${scope} must be an array of relative roots`);
-    }
-  }
-  // Launch environment and hooks: the shared manifest contract (lib/capability-contract.mjs).
+  // Launch environment, hooks and retirement: the shared manifest contract
+  // (lib/capability-contract.mjs). The error carries the problem's JSON pointer.
   const problem = manifestContractProblems(m)[0];
-  if (problem) throw new Error(problem.message);
+  if (problem) throw Object.assign(new Error(problem.message), { pointer: problem.pointer });
   return id;
 }
 
@@ -2002,12 +1998,15 @@ function withoutKernelEnvironment(source) {
  * 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.
+ * entry carries nothing, and its name is added to `cleared` when the caller passes one (tmux keeps
+ * such an entry, and it masks the variable: a session's `unset PATH;` gives its panes no PATH). 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. So a
+ * name is in the result, in `cleared`, in `omitted`, or absent from the text. 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) {
+export function parseTmuxShellEnvironment(bytes, omitted, cleared) {
   let text;
   try { text = new TextDecoder("utf-8", { fatal: true }).decode(bytes); } catch { return null; }
   const env = {};
@@ -2017,6 +2016,7 @@ export function parseTmuxShellEnvironment(bytes, omitted) {
     if (take("unset ")) {
       const end = text.indexOf(";", i);
       if (end <= i || /[\s"=]/.test(text.slice(i, end))) return null;
+      if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(text.slice(i, end))) cleared?.push(text.slice(i, end));
       i = end + 1;
     } else {
       const assign = text.indexOf("=\"", i);
@@ -2074,11 +2074,19 @@ function callerInstance() {
 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");
+  const found = lookupOnPath("tmux", process.env.PATH);
+  if (found) return found;
+  throw refuse("no tmux was found on this process's PATH");
+}
+/** `name` as an exec looks it up on `path`: the first entry, in order, that holds a regular
+ *  executable file of that name, as an absolute path; null when none does. A relative entry, and
+ *  an empty one (an empty PATH is one empty entry), are `cwd`. Nothing is run. */
+function lookupOnPath(name, path, cwd = process.cwd()) {
+  for (const dir of path.split(":")) {
+    const candidate = resolve(cwd, dir || ".", name);
     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");
+  return null;
 }
 /**
  * The environment a `new-session` on the OATS server runs with: the only tmux call that can start
@@ -2087,80 +2095,188 @@ function creatorTmux(session) {
  * 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.
+ * When no server answered the lookup (`startsServer`), so that this new-session starts it, the
+ * environment is the user's login environment (lib/login-environment.mjs), for every creator: what
+ * the login shell from the password database sets up, from a seed that holds nothing of the creator
+ * but its locale and, when it is no instance, its session variables (an instance's come from the
+ * server its home records, then from the platform's user session). The kernel's names and the
+ * instance-identity names are removed from what it answers, and the operator's OATS configuration
+ * (OATS_ and PI_AGENTS_ names that are not the kernel's) is the creator's (an instance's: its recorded
+ * server's). When it cannot be read (a creator whose HOME is not the user's home directory, a
+ * timeout, a non-zero exit, a partial or malformed answer, no HOME or PATH, a shell that is not bash,
+ * zsh or fish), one line on stderr says so and names the fallback, never a value, and the creator falls
+ * back to what follows. That fallback is degraded: neither a login environment nor a working agent
+ * socket is assured.
+ *
+ * Otherwise (the server runs, or the login environment could not be read): 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, which can
+ * leave values out. 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.
+ * creator (its TMUX_TMPDIR, kept or absent as the creator has it, whatever the selected environment
+ * says; 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) {
+/** The operator's configuration names, carried into a server started with the login environment
+ *  (the kernel's own names among them are removed first). */
+const OPERATOR_CONFIG_ENV = /^(OATS_|PI_AGENTS_)/;
+function oatsSessionEnvironment(session, io, { startsServer = false } = {}) {
   const caller = callerInstance();
+  let recorded;
+  const recordedServer = () => (recorded ??= recordedServerEnvironment(caller, session, io));
+  const creatorsTmpdir = (env) => { if (process.env.TMUX_TMPDIR === undefined) delete env.TMUX_TMPDIR; else env.TMUX_TMPDIR = process.env.TMUX_TMPDIR; return env; };
+  if (startsServer) {
+    const login = captureLoginEnvironment({ creatorEnv: process.env, instance: !!caller, recorded: caller ? recordedServer().read : null, shell: process.env.OATS_TEST_LOGIN_SHELL || undefined });
+    if (login.env) {
+      for (const note of login.notes) process.stderr.write(`oats: warning: ${note}\n`);
+      const env = withoutKernelEnvironment(login.env);
+      for (const name of INSTANCE_IDENTITY_ENV) delete env[name];
+      // The operator's own OATS configuration (OATS_HOME_DIR, OATS_TMUX_SESSION, OATS_PACKAGE_CATALOG,
+      // any other OATS_ or PI_AGENTS_ name that is not the kernel's) stays the creator's, over what
+      // the login shell set: a creator outside every instance gives its own; an instance, what the
+      // server its home records has, never its own.
+      const configured = caller ? recordedServer().read : process.env;
+      for (const [name, value] of Object.entries(withoutKernelEnvironment(configured ?? {}))) if (OPERATOR_CONFIG_ENV.test(name)) env[name] = value;
+      return creatorsTmpdir(env);
+    }
+    const fallback = !caller ? "this process's own environment" : recordedServer().error ? null : "a copy of the environment of the tmux server this instance's home records";
+    process.stderr.write(`oats: warning: could not read your login environment (${login.failure}); ${fallback ? `the OATS tmux server is started with ${fallback} instead: a fallback, neither a login environment nor a working agent socket is assured` : "and there is no fallback from inside an instance"}\n`);
+  }
   if (!caller) return withoutKernelEnvironment(process.env);
+  const { env, error } = recordedServer();
+  if (error) throw error;
+  return creatorsTmpdir(env);
+}
+/** The global environment of the tmux server an instance's home records, read strictly: `read` (what
+ *  the reader kept, or null), and `env` (a copy without the kernel's names) or `error` (the refusal
+ *  a creation from inside an instance gets when it cannot use it). */
+function recordedServerEnvironment(caller, session, io) {
   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`);
+  if (!caller.home) return { read: null, error: 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`);
+  catch (e) { if (!oatsCoded(e)) throw e; return { read: null, error: refuse(`the session receipt of ${basename(caller.home)} could not be used (${e.code})`) }; }
+  if (!target?.socket) return { read: null, error: 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;
+  let read = null;
   const omitted = [];
   try {
     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);
+    read = 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`);
+  if (read === null) return { read, error: 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;
+  if (undecided) return { read, error: 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`) };
+  return { read, env: withoutKernelEnvironment(read) };
 }
 /** 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. */
+ *  place, for every creator (an instance, the Desktop, an operator's shell): the three names tmux's
+ *  client reads its locale from, and nothing else. tmux's client 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; tmux gives
+ *  the pane none of them. A pane's environment is its session's over the server's global one
+ *  (spawn.c environ_for_session), PATH included: tmux puts the client's PATH in its place only when
+ *  the client has one, and this client has none. So a PATH and the state that interprets it (a
+ *  version manager's bookkeeping, `__MISE_DIFF`, nvm's) come from one environment, the server's or
+ *  the session's; OATS no longer overlays a creator's PATH onto it. That does not make an existing
+ *  or external server's environment, a session override or a launch configuration's PATH coherent:
+ *  OATS uses them as they are. The client is run by an absolute tmux (tmuxOn), since it has no PATH
+ *  to look one up with. docs/execution-targets.md owns the rule. */
 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.
+ * What a spawn or a start knows, BEFORE it creates, stops or writes anything, about the session it
+ * will open a window in: `{ server, present }` from the lookup and, when `session` is not on the
+ * OATS server and this is no preview, `env`: the environment its creation needs, read now, so that a
+ * caller that cannot create it is refused with nothing left behind; the answer goes to
+ * ensureOatsTmuxSession. It is also where the harness is first looked up (expectedPanePath). Not the
+ * guarantee: ensureOatsTmuxSession decides by what it finds when it creates, and the harness is
+ * looked up again on the session it returns; and an environment read for a running server is read
+ * again there when that server has gone. undefined when this process has no tmux to run: the
+ * caller's backend check refuses that.
+ */
+function planOatsTmuxSession(session, io, { preview = false } = {}) {
+  if (!io?.exec && !which("tmux")) return undefined;
+  let server, present;
+  try { ({ server, present } = oatsTmuxSessionSocket(session, io)); }
+  catch (e) { if (preview) return undefined; throw e; } // a preview reports, it does not refuse on a read
+  if (present || preview) return { server, present };
+  return { server, present, env: oatsSessionEnvironment(session, io, { startsServer: !server }), startsServer: !server };
+}
+/**
+ * The PATH a pane created in `session` on `socket` starts with, read as tmux decides it (spawn.c,
+ * environ.c), never computed from this process: the session's own entry when it has one, otherwise
+ * the server's global PATH. `session` null reads the global one only (a session about to be created
+ * on a running server). Both are read with the strict reader, as bytes.
+ * → `{ path, source }`, or `{ source, problem }` when the pane's PATH cannot be established: the
+ * session entry is an explicit clear (`unset PATH;`: the pane has no PATH at all; never substituted
+ * by the global one or this process's), a value the strict reader leaves out (unknown), a read that
+ * failed, or a server with no PATH (tmux would fall back to a compiled-in default, which OATS does not
+ * assume). `source` names where the PATH comes from; no value is ever in it or in `problem`.
  */
-function planOatsTmuxSession(session, io) {
-  if (!callerInstance() || oatsTmuxSessionSocket(session, io).present) return undefined;
-  return { env: oatsSessionEnvironment(session, io) };
+function panePath(socket, session, io, cwd) {
+  const read = (scope) => {
+    const omitted = [], cleared = [];
+    let env = null;
+    try {
+      const printed = (io?.exec || execFileSync)("tmux", ["-u", "-S", socket, "show-environment", ...scope, "-s"], { timeout: 10000, maxBuffer: 4 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] });
+      env = parseTmuxShellEnvironment(Buffer.isBuffer(printed) ? printed : Buffer.from(String(printed)), omitted, cleared);
+    } catch (e) { if (oatsCoded(e)) throw e; }
+    return { env, omitted, cleared };
+  };
+  const decide = ({ env, omitted, cleared }, source, unset) => {
+    if (env === null) return { source, problem: `${source} could not be read` };
+    if (Object.hasOwn(env, "PATH")) return { path: env.PATH, source, cwd };
+    if (cleared.includes("PATH")) return { source, problem: unset };
+    if (omitted.includes("PATH")) return { source, problem: `${source} cannot be read as data (its value holds a $, a line break or a character tmux prints encoded)` };
+    return null;
+  };
+  if (session) {
+    const own = decide(read(["-t", `=${session}`]), `the PATH of tmux session ${session}`, `tmux session ${session} clears PATH (unset PATH), so its panes start with no PATH at all`);
+    if (own) return own;
+  }
+  const source = `the global PATH of the OATS tmux server (${socket})`;
+  return decide(read(["-g"]), source, `the OATS tmux server (${socket}) clears PATH (unset PATH), so its panes start with no PATH at all`)
+    ?? { source, problem: `the OATS tmux server (${socket}) has no PATH, and tmux then gives a pane a compiled-in default that OATS does not assume` };
+}
+/** Where a launch's pane is expected to look its harness up, from a plan (planOatsTmuxSession): the
+ *  session's or the server's PATH when a server runs, else the PATH of the environment the server
+ *  will be created with. undefined when that is not known (no plan, or a preview with no server: a
+ *  preview reads no creation environment); the lookup then uses this process's PATH, and the launch
+ *  looks again on the session it actually gets. */
+function expectedPanePath(plan, session, io, cwd) {
+  if (!plan) return undefined;
+  if (plan.server) return panePath(plan.server, plan.present ? session : null, io, cwd);
+  if (!plan.env) return undefined;
+  const source = "the PATH the OATS tmux server is created with";
+  return plan.env.PATH === undefined ? { source, problem: `${source} is not set, and tmux then gives a pane a compiled-in default that OATS does not assume` } : { path: plan.env.PATH, source, cwd };
+}
+/** The PATH a launch's harness is looked up on, by precedence: a PATH set in the launch
+ *  configuration (a literal, or a reference resolved from `env`) is what the pane's command line
+ *  applies, so the lookup uses it; otherwise the pane's own PATH (`pane`, from panePath or
+ *  expectedPanePath; a function is called only when it is needed). A declared absolute or relative
+ *  executable is never looked up (resolveLaunchExecutable). undefined: look up on this process's PATH. */
+function launchLookup(configEnv, env, pane, configName, cwd) {
+  const own = configEnv?.PATH;
+  if (typeof own === "string") return { path: own, source: `the PATH of launch configuration ${configName}`, cwd };
+  if (own && typeof own === "object" && own.fromEnv) return env[own.fromEnv] === undefined ? undefined : { path: env[own.fromEnv], source: `the PATH of launch configuration ${configName} (from ${own.fromEnv})`, cwd };
+  return typeof pane === "function" ? pane() : pane;
 }
 /**
  * Make sure `session` exists on the OATS server and return that server's absolute socket: the one
@@ -2182,7 +2298,9 @@ export function ensureOatsTmuxSession(session, hq, io, plan) {
     // 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);
+    // The plan's environment, unless it was read for a running server that has gone since: a server
+    // this call starts gets what a server start gets.
+    const env = plan?.env && (plan.startsServer || socket) ? plan.env : oatsSessionEnvironment(session, io, { startsServer: !socket });
     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(); }
@@ -2469,19 +2587,31 @@ const TASK_PROMPT = Object.freeze({ claude: "@TASK.md", codex: CODEX_TASK_PROMPT
 /** The executable a launch uses: a configuration's declared one (a bare name
  *  on PATH; a path against the deployment directory when relative) or the
  *  harness's name on PATH. Never executed. A new claude launch with a legacy `oats-claude-config` in reach
- *  of its context is refused (E_CLAUDE_CONFIG_REMOVED, 0.32), whatever it declares. */
-export function resolveLaunchExecutable({ harness, declared, declaringDir, contextDir }) {
+ *  of its context is refused (E_CLAUDE_CONFIG_REMOVED, 0.32), whatever it declares.
+ *  `lookup` (launchLookup: `{ path, source, cwd }` or `{ source, problem }`) is the PATH a bare name is
+ *  looked up on, the one the pane runs it with; without one, this process's PATH. A result looked up
+ *  there carries `lookup`, so a refusal can name where it looked. */
+export function resolveLaunchExecutable({ harness, declared, declaringDir, contextDir, lookup }) {
   if (harness === "claude" && contextDir) { const refused = legacyClaudeConfigRefusal(contextDir); if (refused) throw refused; }
-  if (declared) {
-    if (declared.includes("/")) {
-      const path = isAbsolute(declared) ? declared : resolve(declaringDir || contextDir, declared);
-      return { path, declared, resolvedFrom: isAbsolute(declared) ? "absolute" : `relative to ${declaringDir || contextDir}`, missing: existsSync(path) ? undefined : `${declared} (${path}) does not exist` };
-    }
-    const found = which(declared);
-    return { path: found || null, declared, resolvedFrom: "PATH", missing: found ? undefined : `${declared} binary not found on PATH` };
-  }
-  const found = which(harness);
-  return { path: found || null, declared: null, resolvedFrom: "PATH", missing: found ? undefined : `${harness} binary not found on PATH` };
+  if (declared?.includes("/")) {
+    const path = isAbsolute(declared) ? declared : resolve(declaringDir || contextDir, declared);
+    return { path, declared, resolvedFrom: isAbsolute(declared) ? "absolute" : `relative to ${declaringDir || contextDir}`, missing: existsSync(path) ? undefined : `${declared} (${path}) does not exist` };
+  }
+  const name = declared || harness;
+  if (lookup) {
+    const found = lookup.problem ? null : lookupOnPath(name, lookup.path, lookup.cwd);
+    return { path: found, declared: declared || null, resolvedFrom: "PATH", lookup, missing: found ? undefined : lookup.problem ?? `${name} was not found on ${lookup.source}` };
+  }
+  const found = which(name);
+  return { path: found || null, declared: declared || null, resolvedFrom: "PATH", missing: found ? undefined : `${name} binary not found on PATH` };
+}
+/** The refusal for an executable a launch looked up where its pane looks it up (`executable.lookup`)
+ *  and did not find, or could not look up: E_HARNESS_UNAVAILABLE for the harness's own name,
+ *  E_LAUNCH_EXECUTABLE for a configuration's declared name. Names the source and the remedies, never
+ *  the PATH's contents. */
+function executableNotOnPanePath(executable, { harness, config, from, at }) {
+  if (!executable.declared) return harnessNotOnPanePath({ harness, from, at, why: executable.missing });
+  return oatsError("E_LAUNCH_EXECUTABLE", `launch configuration ${config?.name}: ${executable.missing}; ${PANE_PATH_FIX}`);
 }
 /** null when `path` is a regular executable file; otherwise why not. */
 export function checkLaunchExecutable(path) {
@@ -2816,7 +2946,7 @@ function requirementsWithArgsMessage(harness, providers, config) {
  *  and not at all for a preview. A home
  *  that records no launch recipe (an earlier kernel spawned it) is not planned:
  *  E_LAUNCH_LEGACY, re-spawn it from the deployment. */
-export function planLaunch({ home, instance, meta, contextDir, agentLike, selection = {}, launchConfigs, resolvedCfg, env = process.env, preview = false, assertRoots, reselect = null }) {
+export function planLaunch({ home, instance, meta, contextDir, agentLike, selection = {}, launchConfigs, resolvedCfg, env = process.env, preview = false, assertRoots, reselect = null, panePath: expectedPane }) {
   assertRoots?.();
   const problems = [];
   const fail = (check, code, detail) => { if (!preview) throw oatsError(code, detail); problems.push({ check, ok: false, detail, code }); };
@@ -2842,16 +2972,23 @@ export function planLaunch({ home, instance, meta, contextDir, agentLike, select
   // the default no longer decides (a bare --launch-config none, another harness).
   const frozenYolo = frozen && !(frozen.launchConfigDefault === true && !config?.frozen) ? frozen.yolo : undefined;
   const yolo = resolveYolo(selection.yolo ?? chosen.configuredYolo ?? (frozen ? frozenYolo : agentLike?.yolo ?? resolvedCfg?.yolo));
+  // A frozen recipe keeps its recorded path. Otherwise a bare name is looked up where the pane will
+  // look it up (launchLookup: the configuration's PATH, else `expectedPane`, the start's expected
+  // session or server PATH; a start looks again on the session it gets).
   const executable = config?.frozen
     ? { path: config.executablePath, declared: frozen.executableDeclared ?? null, resolvedFrom: frozen.executableResolvedFrom || "recorded", missing: existsSync(config.executablePath) ? undefined : `${config.executablePath} (recorded) does not exist` }
-    : resolveLaunchExecutable({ harness, declared: config?.executable, declaringDir: config?.source, contextDir });
-  if (!executable.path && !config?.executable && launchChoice) {
+    : resolveLaunchExecutable({ harness, declared: config?.executable, declaringDir: config?.source, contextDir, lookup: config?.executable?.includes("/") ? undefined : launchLookup(config?.env, env, expectedPane, config?.name, home) });
+  const notOnPane = !executable.path && executable.lookup ? executableNotOnPanePath(executable, { harness, config, from: launchChoice?.from, at: launchChoice?.at }) : null;
+  if (notOnPane) {
+    if (!preview) throw notOnPane;
+    problems.push({ check: "executable", ok: false, detail: notOnPane.message, code: notOnPane.code });
+  } else if (!executable.path && !config?.executable && launchChoice) {
     const e = harnessUnavailable({ harness, from: launchChoice.from, at: launchChoice.at, why: executable.missing });
     if (!preview) throw e;
     problems.push({ check: "executable", ok: false, detail: e.message, code: e.code });
   }
-  const exeProblem = executable.path ? checkLaunchExecutable(executable.path) : !config?.executable && launchChoice ? null : executable.missing;
-  if (exeProblem) fail("executable", "E_LAUNCH_EXECUTABLE", `launch configuration ${config?.name || "(harness default)"}: ${exeProblem}`); else problems.push({ check: "executable", ok: true, detail: `${executable.path} (${executable.resolvedFrom})` });
+  const exeProblem = executable.path ? checkLaunchExecutable(executable.path) : notOnPane || (!config?.executable && launchChoice) ? null : executable.missing;
+  if (exeProblem) fail("executable", "E_LAUNCH_EXECUTABLE", `launch configuration ${config?.name || "(harness default)"}: ${exeProblem}`); else if (!notOnPane) problems.push({ check: "executable", ok: true, detail: `${executable.path} (${executable.resolvedFrom})` });
   // Capability contributions: recorded at spawn with provenance; a harness
   // switch needs the new harness's launch args from the same capabilities.
   let hooks = { launch: {}, env: {}, contributions: [], pending: true };
@@ -3106,10 +3243,11 @@ function* spawnBody(root, agent, o = {}) {
     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 (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;
+  // A caller that will have to create the tmux session reads the environment for it here, before
+  // any scaffold, work tree, identity or hook, so that an instance that cannot is refused with
+  // nothing left behind; the harness is first looked up on the PATH this plan expects (below). A
+  // preview reads only what exists.
+  const tmuxSessionPlan = launch ? planOatsTmuxSession(session, undefined, { preview: o.preview === true }) : undefined;
 
   // Forward-only lineage: EXPLICIT only. Relations (child|sibling|parent|unrelated)
   // anchor the new instance to an EXISTING instance (o.relativeTo). o.parent
@@ -3393,7 +3531,12 @@ function* spawnBody(root, agent, o = {}) {
   // reconciliation, so this spawn-time check is the authoritative one.
 
   // Prerequisites must fail before creating a home, worktree, or identity.
-  const executable = resolveLaunchExecutable({ harness, declared: launchConfig?.executable, declaringDir: launchConfig?.source, contextDir: repoAbs });
+  // A launched harness is looked up where its pane will look it up (launchLookup): this is the
+  // preflight against the expected PATH; the launch looks again on the session it gets. Without a
+  // launch (or a known destination) the lookup is this process's PATH, as before.
+  const lookupFor = (pane) => launch && !launchConfig?.executable?.includes("/") ? launchLookup(launchConfig?.env, process.env, pane, launchConfig?.name, home) : undefined;
+  const executable = resolveLaunchExecutable({ harness, declared: launchConfig?.executable, declaringDir: launchConfig?.source, contextDir: repoAbs, lookup: lookupFor(() => expectedPanePath(tmuxSessionPlan, session, undefined, home)) });
+  if (!executable.path && executable.lookup) { previewPreflightBudget = null; throw executableNotOnPanePath(executable, { harness, config: launchConfig, from: launchChoice.from, at: launchChoice.at }); }
   // No executable for the chosen harness (none declared by a configuration): E_HARNESS_UNAVAILABLE names the
   // layer that chose it and the fix. Never a fallback to another harness.
   if (!executable.path && !launchConfig?.executable) { previewPreflightBudget = null; throw harnessUnavailable({ harness, from: launchChoice.from, at: launchChoice.at, why: executable.missing }); }
@@ -3902,7 +4045,7 @@ function* spawnBody(root, agent, o = {}) {
       assertDirectoryRoots(home, homeReal);
       const path = join(home, "work");
       if (!readdirSync(path).length) return;
-      const directoryFingerprint = fingerprintTree(path);
+      const directoryFingerprint = directoryBytes(path);
       if (lastDirectoryFingerprint === directoryFingerprint) return;
       const receipt = preserveRetirementWork({ home, work: path, directory: true, directoryFingerprint, classes: ["directory work bytes"] }, { work, repo: repoAbs }, instance);
       directoryRecoveries.push(receipt.path);
@@ -4034,7 +4177,7 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
     if (triggerEventFile) recipe.env.OATS_TRIGGER_EVENT_FILE = triggerEventFile;
     const folderTrust = launchFolderTrust({ harness, home, meta: { workspace: { deployment: o.prepared?.deployment } }, yolo });
     if (folderTrust.warning) warnings.push(folderTrust.warning);
-    const cmdline = renderLaunchRecipe(recipe, { home, instance, trustHome: folderTrust.trustHome });
+    let cmdline = renderLaunchRecipe(recipe, { home, instance, trustHome: folderTrust.trustHome });
 
     // Module skills as materialize landed them (flat, .agents/skills/<skill>/),
     // beside the soul's own: per-skill provenance `module:<cap>` (lead decision c3),
@@ -4133,11 +4276,26 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
 
     spawnTmux = meta.tmux;
     if (work === "directory") assertDirectoryRoots(home, homeReal);
-    const executionCommand = launch ? nativeRecordCommand(cmdline, home, harness) : null;
+    let executionCommand = launch ? nativeRecordCommand(cmdline, home, harness) : null;
     if (launch) {
       // 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);
+      // The harness looked up again on the PATH this window's pane will actually start with, whoever
+      // created the session and with whatever environment (a race lost to another creator, a session
+      // that overrides PATH). Not there: refused, and the spawn is compensated. Found elsewhere than
+      // the preflight found it: the launch runs that one.
+      if (executable.lookup) {
+        const actual = resolveLaunchExecutable({ harness, declared: launchConfig?.executable, declaringDir: launchConfig?.source, lookup: lookupFor(() => panePath(socket, session, undefined, home)) });
+        if (!actual.path) throw executableNotOnPanePath(actual, { harness, config: launchConfig, from: launchChoice.from, at: launchChoice.at });
+        const bad = checkLaunchExecutable(actual.path);
+        if (bad) throw oatsError("E_LAUNCH_EXECUTABLE", `launch configuration ${launchConfig?.name || "(harness default)"}: ${bad}`);
+        if (actual.path !== recipe.executable) {
+          recipe.executable = actual.path;
+          meta.command = cmdline = renderLaunchRecipe(recipe, { home, instance, trustHome: folderTrust.trustHome });
+          executionCommand = nativeRecordCommand(cmdline, home, harness);
+        }
+      }
       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")}`); }
@@ -4692,43 +4850,147 @@ const GIT_MAX_BUFFER = 512 * 1024 * 1024;
 
 /** Kernel-owned receipts the kernel itself appends to a home after the spawn
  *  baseline (events log, stop/restart receipts). They are evidence about the
- *  instance, not the instance's work, so a retirement fingerprint ignores them —
- *  otherwise every stop or event write would read as "changed home bytes". */
+ *  instance, not the instance's work, so the stored digest a spawn baseline is
+ *  compared with passes over them — otherwise every stop or event write would
+ *  read as "changed home bytes". The home copy carries them, so the exact
+ *  digest, which says whether the retire hooks moved the home, holds them.
+ *  A new kernel-written top-level home entry, whether or not it belongs here,
+ *  MUST be added in the same change to the names a capability may not declare
+ *  as its own (`retirement.disposable.home`: KERNEL_HOME_NAMES and
+ *  KERNEL_HOME_NAME_PREFIXES in lib/capability-contract.mjs, and the schema). */
 const KERNEL_HOME_RECEIPTS = new Set([".oats-events.jsonl", ".oats-stop.json", ".oats-stop-receipt.json", ".oats-restart.json"]);
 const KERNEL_HOME_RECEIPT_PATTERNS = [/^\.oats-stop-receipt\..+\.json$/, /^\.oats-agents-md\..+\.previous$/];
 /** Harness project settings in the home are configuration, not work: the
  *  home's `.claude/` is harness layout the kernel already shapes (the skills
  *  alias), and capabilities keep their own entries current in its
- *  settings.json at every launch. A retirement fingerprint ignores exactly
- *  that path, home-relative. */
+ *  settings.json at every launch. The stored digest passes over exactly that
+ *  path, home-relative; the exact digest holds it, as the home copy does. */
 const HARNESS_HOME_SETTINGS = new Set([join(".claude", "settings.json")]);
-function fingerprintTree(root, { excludeRoot = new Set(), excludeGitMetadata = false, instanceHome = false } = {}) {
-  const hash = createHash("sha256");
+/** The refusal for an entry that is not a file, a directory or a symbolic link
+ *  (a socket, a FIFO, a device): it has no bytes to read or to copy. One
+ *  sentence for every caller of fingerprintTree, at spawn and at retire, so it
+ *  names neither. It does not say "remove": the entry may be a live endpoint. */
+const unsupportedEntry = (path) => oatsError("E_WORK_INSPECTION_FAILED", `${path} has an unsupported filesystem type: it is not a file, a directory or a symbolic link, so it cannot be read or copied. Safely stop the process or resource that owns it, or move the entry elsewhere, before retrying`);
+const PATH_SEPARATOR_BYTES = Buffer.from(sep);
+/** The digests of a tree, from one walk that reads each file once → { stored,
+ *  exact }; each only when asked for (`stored` by default).
+ *
+ *  Both hash, for each entry in order, its path under the root, its
+ *  permission bits, its kind, and a file's bytes or a link's target. Entry
+ *  names and link targets are read and hashed as bytes, never as decoded
+ *  text: two trees that differ only in bytes that are not UTF-8 have two
+ *  digests, and an entry with such a name is read, not missed. This is about
+ *  what a digest tells apart. It does not make such a tree copyable:
+ *  copyTreeSafe reads entry names as text and cannot carry a file name that
+ *  is not UTF-8.
+ *
+ *  A name's text (its bytes decoded as UTF-8, the way readdirSync decodes
+ *  them: replacement characters for bytes that are not UTF-8, a byte order
+ *  mark kept) is used only to order the entries and to test membership: the
+ *  names a digest passes over and `instance.json`, as they have always been
+ *  tested. Both digests pass over what a copy does not carry: `excludeRoot`
+ *  and, with `excludeGitMetadata`, `.git`. Only the stored digest also passes
+ *  over the kernel's receipts and the harness settings of a home.
+ *
+ *  `stored` is the digest a spawn baseline holds, written by this kernel or
+ *  by an older one, so it never changes: its framing (each field followed by
+ *  NUL, no lengths), its order, and a home's `instance.json` without the
+ *  fields the kernel writes after spawn (kernelNeutralInstanceJson). For a
+ *  tree whose names and link targets are all valid UTF-8 it is what it was
+ *  when they were read as text: hashing a text hashes its UTF-8, which is
+ *  those bytes. It is what is compared with a baseline. Without lengths it
+ *  reads alike a file whose bytes spell the entry that follows it and those
+ *  two entries, and the neutral form reads alike two `instance.json` files
+ *  that parse to the same value.
+ *
+ *  `exact` is for every comparison of a tree with itself later, or with its
+ *  copy: whether the retire hooks left it as it was. It is kept nowhere. It
+ *  holds every entry the copy carries: of a home, the kernel's receipts and
+ *  the harness settings too, which the copy carries and a retire hook can
+ *  write. Two different trees cannot give it the same stream: an entry is its
+ *  path, its mode, its kind and its content, where the path and the content
+ *  carry their length and the mode and the kind end in NUL, so the stream can
+ *  be read back into its entries in one way only, and a tree is the set of
+ *  its entries. A home's `instance.json` goes in as the bytes it has.
+ *
+ *  The root's own permission bits, which are no entry of the walk, are in
+ *  the exact digest: a path the recovery copier copies is compared with its
+ *  own bits, because copyTreeSafe ends with a chmod of what it made.
+ *  `children` is for a root the copier creates itself (a home, a worktree):
+ *  its copy is made inside a directory the copier creates, so the root's bits
+ *  are no part of what it carries, and the root is compared through its
+ *  children alone. The stored digest never holds the root's bits. */
+function fingerprintTrees(root, { excludeRoot = new Set(), excludeGitMetadata = false, instanceHome = false, stored = true, exact = false, children = false } = {}) {
+  const s = stored ? createHash("sha256") : null, x = exact ? createHash("sha256") : null;
+  const digests = () => ({ stored: s ? `sha256:${s.digest("hex")}` : undefined, exact: x ? `sha256:${x.digest("hex")}` : undefined });
+  /** A field of the exact digest whose length is not fixed: its length, NUL, its bytes. */
+  const sized = (bytes) => { x.update(String(bytes.length)); x.update("\0"); x.update(bytes); };
   const rootStat = lstatSync(root);
   if (!rootStat.isDirectory()) {
-    hash.update(String(rootStat.mode & 0o7777)); hash.update("\0");
-    if (rootStat.isSymbolicLink()) { hash.update("link\0"); hash.update(readlinkSync(root)); }
-    else if (rootStat.isFile()) { hash.update("file\0"); hash.update(readFileSync(root)); }
-    else throw oatsError("E_WORK_INSPECTION_FAILED", `${root} has an unsupported filesystem type`);
-    return `sha256:${hash.digest("hex")}`;
-  }
-  const walk = (dir, rel = "") => {
-    for (const e of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
-      if ((!rel && excludeRoot.has(e.name)) || (instanceHome && !rel && (KERNEL_HOME_RECEIPTS.has(e.name) || KERNEL_HOME_RECEIPT_PATTERNS.some((p) => p.test(e.name)))) || (excludeGitMetadata && e.name === ".git")) continue;
-      const childRel = rel ? join(rel, e.name) : e.name;
-      if (instanceHome && HARNESS_HOME_SETTINGS.has(childRel)) continue;
-      const path = join(dir, e.name);
+    const mode = String(rootStat.mode & 0o7777);
+    s?.update(mode); s?.update("\0");
+    x?.update("entry\0"); x?.update(mode); x?.update("\0");
+    if (rootStat.isSymbolicLink()) { const target = readlinkSync(root, "buffer"); s?.update("link\0"); s?.update(target); if (x) { x.update("link\0"); sized(target); } }
+    else if (rootStat.isFile()) { const bytes = readFileSync(root); s?.update("file\0"); s?.update(bytes); if (x) { x.update("file\0"); sized(bytes); } }
+    else throw unsupportedEntry(root);
+    return digests();
+  }
+  x?.update(children ? "tree\0" : `tree with its mode\0${rootStat.mode & 0o7777}\0`);
+  // `dir` and `rel` are bytes: the directory, and its path under the root
+  // (empty at the root). `relText` is `rel` as text, for the name tests.
+  // `outer` is the stored hash, or null inside an entry it passes over.
+  const walk = (dir, rel, relText, outer) => {
+    // The order is the one it has always been: the names as text, compared
+    // by localeCompare, on the listing as readdirSync returns it. The sort is
+    // stable and the listing is the same whether its names come as text or
+    // as bytes, so a tree whose names are all valid UTF-8 is walked in the
+    // order it always was. Names that decode alike (two that are not UTF-8,
+    // or one and a name that really holds the replacement character) keep
+    // the listing's order. Where that order is not fixed, two reads of one
+    // directory can differ, which adds a copy attempt; two different trees
+    // cannot read alike for it, because the bytes of every name are hashed.
+    const entries = readdirSync(dir, { encoding: "buffer" }).map((bytes) => ({ bytes, name: bytes.toString("utf8") }));
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const { bytes: nameBytes, name } of entries) {
+      if ((!relText && excludeRoot.has(name)) || (excludeGitMetadata && name === ".git")) continue;
+      const childRelText = relText ? join(relText, name) : name;
+      const storedPassesOver = instanceHome && ((!relText && (KERNEL_HOME_RECEIPTS.has(name) || KERNEL_HOME_RECEIPT_PATTERNS.some((p) => p.test(name)))) || HARNESS_HOME_SETTINGS.has(childRelText));
+      if (storedPassesOver && !x) continue;
+      const s = storedPassesOver ? null : outer;
+      const childRel = rel.length ? Buffer.concat([rel, PATH_SEPARATOR_BYTES, nameBytes]) : nameBytes;
+      const path = Buffer.concat([dir, PATH_SEPARATOR_BYTES, nameBytes]);
       const st = lstatSync(path);
-      hash.update(childRel); hash.update("\0"); hash.update(String(st.mode & 0o7777)); hash.update("\0");
-      if (st.isSymbolicLink()) { hash.update("link\0"); hash.update(readlinkSync(path)); hash.update("\0"); }
-      else if (st.isFile()) { hash.update("file\0"); hash.update(instanceHome && !rel && e.name === "instance.json" ? kernelNeutralInstanceJson(readFileSync(path)) : readFileSync(path)); /* kernel-field neutrality applies ONLY when the tree IS an instance home; a work tree's instance.json is the agent's bytes */ hash.update("\0"); }
-      else if (st.isDirectory()) { hash.update("dir\0"); walk(path, childRel); }
-      else throw oatsError("E_WORK_INSPECTION_FAILED", `${path} has an unsupported filesystem type`);
+      const mode = String(st.mode & 0o7777);
+      s?.update(childRel); s?.update("\0"); s?.update(mode); s?.update("\0");
+      if (x) { sized(childRel); x.update(mode); x.update("\0"); }
+      if (st.isSymbolicLink()) {
+        const target = readlinkSync(path, "buffer");
+        s?.update("link\0"); s?.update(target); s?.update("\0");
+        if (x) { x.update("link\0"); sized(target); }
+      } else if (st.isFile()) {
+        const bytes = readFileSync(path);
+        // Kernel-field neutrality applies ONLY when the tree IS an instance home, and only to the
+        // stored digest; a work tree's instance.json is the agent's bytes.
+        s?.update("file\0"); s?.update(instanceHome && !relText && name === "instance.json" ? kernelNeutralInstanceJson(bytes) : bytes); s?.update("\0");
+        if (x) { x.update("file\0"); sized(bytes); }
+      } else if (st.isDirectory()) { s?.update("dir\0"); x?.update("dir\0"); walk(path, childRel, childRelText, s); }
+      else throw unsupportedEntry(join(root, childRelText));
     }
   };
-  walk(root);
-  return `sha256:${hash.digest("hex")}`;
+  walk(Buffer.from(root), Buffer.alloc(0), "", s);
+  return digests();
+}
+/** The stored digest of a tree (fingerprintTrees): what a spawn baseline holds and is compared with. */
+function fingerprintTree(root, options = {}) {
+  return fingerprintTrees(root, { ...options, stored: true, exact: false }).stored;
 }
+/** The exact digest of a tree (fingerprintTrees): what a tree is compared with itself later, or with its copy. */
+function exactTreeDigest(root, options = {}) {
+  return fingerprintTrees(root, { ...options, stored: false, exact: true }).exact;
+}
+/** The bytes of a directory instance's work/, as their exact digest, with the
+ *  permission bits of work/ itself: what a copy of it carries. Kept nowhere. */
+const directoryBytes = (work) => exactTreeDigest(work);
 
 /** 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
@@ -4745,13 +5007,24 @@ function worktreeAdminMissing(work) {
   if (!m) return true;
   return !existsSync(join(resolve(work, m[1]), "HEAD"));
 }
-function worktreeStatus(repo) {
+/** A repository's status as Git printed it, as bytes. A path that is not
+ *  UTF-8 is in there as it is: the work state compares these bytes
+ *  (repositoryGitState). Output that does not decode is not a failure; only
+ *  a `git status` that fails is. */
+function worktreeStatusBytes(repo) {
   try {
-    return execFileSync("git", ["-C", repo, "status", "--porcelain=v1", "-z", "--untracked-files=all", "--ignored=matching", "--ignore-submodules=none"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] , maxBuffer: GIT_MAX_BUFFER });
+    return execFileSync("git", ["-C", repo, "status", "--porcelain=v1", "-z", "--untracked-files=all", "--ignored=matching", "--ignore-submodules=none"], { stdio: ["ignore", "pipe", "pipe"] , maxBuffer: GIT_MAX_BUFFER });
   } catch (e) {
     throw oatsError("E_WORK_INSPECTION_FAILED", `could not inspect instance worktree: ${String(e.stderr ?? e.message ?? "").trim() || "git status failed"}`);
   }
 }
+/** The same status as text, for what reads its rows: the classes, the rows a
+ *  spawn baseline was taken from, the comparison of a copy with its source.
+ *  Bytes that are not UTF-8 read as replacement characters here, so this
+ *  text is never what proves a worktree unchanged. */
+function worktreeStatus(repo) {
+  return worktreeStatusBytes(repo).toString("utf8");
+}
 
 /** `git status --porcelain=v1 -z` as Map<path, XY>; a rename/copy row names its source (`R  ← old`). */
 function statusRows(z) {
@@ -4825,24 +5098,90 @@ function retirementDisposableRoots(work, capabilities) {
 const KERNEL_POST_SPAWN_FIELDS = ["spawnCompleted", "wake"];
 function kernelNeutralInstanceJson(bytes) {
   try {
-    const m = JSON.parse(String(bytes));
+    // Bytes that are not UTF-8 would each read as the replacement character,
+    // and two such files would then read alike: a file that does not decode
+    // and encode back to the same bytes is hashed as it is, like one that is
+    // not JSON.
+    const text = String(bytes);
+    if (!Buffer.from(text).equals(bytes)) return bytes;
+    const m = JSON.parse(text);
     if (!m || typeof m !== "object" || Array.isArray(m)) return bytes;
     for (const k of KERNEL_POST_SPAWN_FIELDS) delete m[k];
     return Buffer.from(JSON.stringify(m));
   } catch { return bytes; }
 }
+const byCodeUnit = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+/** The provider-owned home entries the active capabilities declare
+ *  (`retirement.disposable.home`, lib/capability-contract.mjs) → [{ owner, root }],
+ *  sorted by owner then root. Recorded in the spawn baseline: retirement reads
+ *  them from there and from nowhere else. */
+function retirementDisposableHome(capabilities) {
+  const rows = new Map();
+  for (const cap of capabilities || []) {
+    for (const root of cap?.retirement?.disposable?.home || []) {
+      if (disposableHomeRootProblem(root)) throw new Error(`retirement disposable home entry from ${cap.id} is not declarable: ${JSON.stringify(root)}`);
+      rows.set(`${cap.id}\0${root}`, { owner: cap.id, root });
+    }
+  }
+  return [...rows.values()].sort((a, b) => byCodeUnit(a.owner, b.owner) || byCodeUnit(a.root, b.root));
+}
+/** A baseline's `disposableHome`, or no exclusions at all: it must be an array
+ *  of { owner, root } whose every root passes the manifest grammar. Anything
+ *  else (absent, an older baseline, a malformed or widened row) excludes
+ *  nothing, so the home is copied whole. Never the manifest in the home's
+ *  module copy, the capability as it is today, or instance.json. */
+function baselineDisposableHome(baseline) {
+  const rows = baseline?.disposableHome;
+  if (!Array.isArray(rows) || !rows.every((r) => isPlainObject(r) && nonEmptyString(r.owner) && !disposableHomeRootProblem(r.root))) return [];
+  return rows.map((r) => ({ owner: r.owner, root: r.root })).sort((a, b) => byCodeUnit(a.owner, b.owner) || byCodeUnit(a.root, b.root));
+}
+/** One pass's resolved exclusion set: the home's top-level entries that
+ *  `disposableHome` rows cover, matched by name (a symlink is its name; it is
+ *  never followed). The fingerprint, the copy and the copy's verification of
+ *  that pass all use this one set. → { excludeRoot: Set (work/ and the covered
+ *  names), notCopied: [{ scope: "home", path, owner }] sorted by path }: names
+ *  and owners only. Two owners of one entry: the first in owner order. */
+function resolveHomeExclusions(home, disposableHome = []) {
+  const excludeRoot = new Set(["work"]);
+  const notCopied = [];
+  if (!disposableHome.length) return { excludeRoot, notCopied };
+  for (const name of readdirSync(home).sort(byCodeUnit)) {
+    const row = name === "work" ? undefined : disposableHome.find((r) => disposableHomeRootMatches(r.root, name));
+    if (!row) continue;
+    excludeRoot.add(name);
+    notCopied.push({ scope: "home", path: name, owner: row.owner });
+  }
+  return { excludeRoot, notCopied };
+}
+function unionNotCopied(...lists) {
+  const byPath = new Map();
+  for (const row of lists.flatMap((list) => list || [])) if (!byPath.has(row.path)) byPath.set(row.path, row);
+  return [...byPath.values()].sort((a, b) => byCodeUnit(a.path, b.path));
+}
+function retirementBaselineValid(baseline, home) {
+  return baseline?.version === RETIRE_BASELINE_VERSION && baseline.home === realPathOrNearest(home);
+}
+/** What a retire plan may say about recovery without hashing anything: where a
+ *  recovery would be written, and the home entries the spawn baseline declares
+ *  as not copied (none without a valid baseline). */
+export function retirementRecoveryFacts(home) {
+  const baseline = readJsonOrUndefined(retirementBaselinePath(home));
+  return { recoveryRoot: join(retirementStateRoot(home), "recovery"), disposableHome: retirementBaselineValid(baseline, home) ? baselineDisposableHome(baseline) : [] };
+}
 function writeRetirementBaseline(home, work, mode, capabilities, runtime, { exclusive = false, incarnationId, executionBinding } = {}) {
   if (mode === "directory") assertDirectoryRoots(home);
   const isWorktree = mode === "worktree";
   const status = isWorktree && existsSync(work) ? worktreeStatus(work) : "";
   const disposableReceipts = isWorktree ? retirementDisposableRoots(work, capabilities) : [];
+  const disposableHome = retirementDisposableHome(capabilities);
   const baseline = {
     version: RETIRE_BASELINE_VERSION,
     ...(incarnationId ? { incarnationId, executionBinding } : {}),
     ...(mode === "directory" ? { directoryWork: true, directoryRoots: { home: directoryIdentity(home), work: directoryIdentity(work) } } : {}),
     home: realPathOrNearest(home),
-    homeFingerprint: fingerprintTree(home, { excludeRoot: new Set(["work"]), instanceHome: true }),
+    homeFingerprint: fingerprintTree(home, { excludeRoot: resolveHomeExclusions(home, disposableHome).excludeRoot, instanceHome: true }),
     disposableReceipts,
+    disposableHome,
     generatedWorkFingerprint: isWorktree ? generatedWorkFingerprint(work, status, disposableReceipts.map((r) => r.root)) : undefined,
     runtime: {
       launched: runtime?.launched === true,
@@ -5163,8 +5502,16 @@ export function withLaunchModel(command, model) {
   return renderLaunchCommand(tokens);
 }
 
+/** One tmux command on `socket`. With `env` (a window client: oatsWindowEnvironment, which has no
+ *  PATH) the tmux is the absolute one this process's own PATH finds, so its lookup never depends on
+ *  the environment it is passed; none found is reported as tmux being unavailable (ENOENT). */
 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 } : {}) });
+  let tmux = "tmux";
+  if (env) {
+    tmux = process.env.PATH === undefined ? null : lookupOnPath("tmux", process.env.PATH);
+    if (!tmux) throw Object.assign(new Error("no tmux was found on this process's PATH"), { code: "ENOENT" });
+  }
+  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) {
@@ -5545,6 +5892,28 @@ export function startInstanceSession(home, o = {}) {
     // --reselect-launch (feature launch-preference): apply the home's launch layers now (souls.launch,
     // the recorded soul's launch, the host default) instead of the frozen recipe.
     const reselect = o.reselectLaunch === true ? homeLaunchLayers(realHome, meta) : null;
+    // The session this start opens its window in when it has to create one, and what its creation
+    // needs (planOatsTmuxSession), read at most once: by the plan's lookup or by the creation's preflight.
+    const planSession = receipt.target?.session || meta.tmux?.session || DEFAULT_TMUX_SESSION;
+    let sessionPlanRead;
+    const sessionPlan = () => {
+      if (!sessionPlanRead) { try { sessionPlanRead = { plan: planOatsTmuxSession(planSession, o.io) }; } catch (e) { sessionPlanRead = { error: e }; } }
+      if (sessionPlanRead.error) throw sessionPlanRead.error;
+      return sessionPlanRead.plan;
+    };
+    // The recorded target, observed once: by the plan's lookup, which must know whether the pane will
+    // be reused before it chooses where to look, or by the gate below. A lost server is a stopped one;
+    // any other failure is the gate's refusal (E_SESSION_UNKNOWN), and the lookup does not decide it.
+    let recordedRead;
+    const recordedState = () => {
+      if (!recordedRead) {
+        try { recordedRead = { state: receipt.target ? inspectSessionTarget(receipt.target, o.io) : { present: false, state: "not-launched" } }; }
+        catch (e) { recordedRead = lostTmuxServer(e) ? { state: { present: false, state: "stopped" } } : { error: e }; }
+      }
+      return recordedRead;
+    };
+    // A pane the start reuses where it is: one the recorded target shows, running or left as a shell.
+    const reusable = (state) => !!(state?.paneId && (state.present || state.state === "stopped"));
     const selected = reselect !== null || o.launchConfig !== undefined || o.harness !== undefined || o.yolo !== undefined;
     const hasRecipe = meta.launch && typeof meta.launch === "object";
     let launchPlan = null, launchHooksPass = null, hookMeta, explicitModelFrom = null, warnings = [];
@@ -5559,8 +5928,23 @@ export function startInstanceSession(home, o = {}) {
       // the launch hook re-checks joined memberships against them.
       const resolvedCfg = resolvedFromHome(realHome, meta, { teams: o.teams, defaultTeam: o.defaultTeam, teamsSource: o.teamsSource });
       let agent; try { agent = findAgent(dirname(dirname(dirname(realHome))), meta.agent); } catch { agent = undefined; }
-      const plan = planLaunch({ home: realHome, instance: meta.instance, meta, contextDir: context, agentLike: agent || { harness: meta.harness, model: meta.model, yolo: meta.yolo }, selection: { launchConfig: o.launchConfig, harness: o.harness, model: o.model, yolo: o.yolo }, reselect, resolvedCfg, env: o.env || process.env, assertRoots: checkRoots });
-      launchPlan = { recipe: plan.recipe, command: plan.command, harness: plan.harness, model: plan.model, yolo: plan.yolo, modelFrom: modelFromOf(plan.modelSource, { at: "start", prior: meta.modelFrom ?? null }),
+      // Where the plan looks a harness up by name: a pane the start will reuse, on its own recorded
+      // session, whatever the OATS server holds; otherwise the session's or the server's PATH when a
+      // server runs; when none does, the PATH of the environment this start will create the server
+      // with (read once, here, for the plan and for the creation below). For a creator that may not
+      // create the server the plan looks on this process's PATH, and its refusal comes at the
+      // creation's own place, after the start's other preflights.
+      const pane = () => {
+        const recorded = recordedState();
+        if (reusable(recorded.state)) return panePath(receipt.target.socket, receipt.target.session, o.io, realHome);
+        if (recorded.error) return undefined; // the gate refuses below; the lookup does not decide it
+        const preview = planOatsTmuxSession(planSession, o.io, { preview: true });
+        if (!preview || preview.server) return expectedPanePath(preview, planSession, o.io, realHome);
+        try { return expectedPanePath(sessionPlan(), planSession, o.io, realHome); } catch (e) { if (oatsCoded(e)) return undefined; throw e; }
+      };
+      const plan = planLaunch({ home: realHome, instance: meta.instance, meta, contextDir: context, agentLike: agent || { harness: meta.harness, model: meta.model, yolo: meta.yolo }, selection: { launchConfig: o.launchConfig, harness: o.harness, model: o.model, yolo: o.yolo }, reselect, resolvedCfg, env: o.env || process.env, assertRoots: checkRoots,
+        panePath: pane });
+      launchPlan = { recipe: plan.recipe, command: plan.command, harness: plan.harness, model: plan.model, yolo: plan.yolo, executable: plan.executable, config: plan.config, launchChoice: plan.launchChoice, trustHome: plan.trustHome, modelFrom: modelFromOf(plan.modelSource, { at: "start", prior: meta.modelFrom ?? null }),
         ...(plan.launchChoice ? { launchFrom: plan.launchChoice.from, launchAt: plan.launchChoice.at, launchDeclared: plan.launchChoice.declared } : {}) };
       // The plan ran preview-aware launch hooks as a preview: their real run, over the planned
       // contributions, waits for the rest of preflight.
@@ -5585,19 +5969,15 @@ export function startInstanceSession(home, o = {}) {
     if (recipeForEnv) { const missing = missingLaunchEnvRefs(recipeForEnv.env, o.env || process.env); if (missing.length) throw oatsError("E_LAUNCH_ENV_MISSING", `this home's launch references ${missing.join(", ")}, not set on this host; nothing was started`); }
     const paneEnv = recipeForEnv ? launchEnvRefs(recipeForEnv, o.env || process.env) : [];
     const paneEnvFlags = paneEnv.flatMap((r) => ["-e", `${r.name}=${r.value}`]);
-    checkRoots(); // preparation has run; no backend has been observed
+    checkRoots(); // preparation has run; no backend has been changed
     let target = receipt.target;
-    let state = { present: false, state: "not-launched" };
-    if (target) {
-      try { state = inspectSessionTarget(target, o.io); }
-      catch (e) {
-        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}`);
-      }
-    }
+    const recorded = recordedState();
+    if (recorded.error) { const e = recorded.error; throw oatsError("E_SESSION_UNKNOWN", `cannot establish whether ${meta.instance} is running, so nothing was started: ${String(e.stderr ?? e.message ?? "").trim() || e.message}`); }
+    let state = recorded.state;
     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,
+    // A caller that will have to create the tmux session reads the environment for it here, unless
+    // the plan's lookup read it already with no server running (an instance that cannot is refused
+    // here either way): 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
@@ -5606,8 +5986,27 @@ export function startInstanceSession(home, o = {}) {
     // 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;
+    const retained = reusable(state);
+    const tmuxSessionPlan = retained ? undefined : sessionPlan();
+    // A harness the plan looked up by name is looked up again where its pane will look it up, before
+    // anything is stopped: the retained pane's own session, or the session this start will create
+    // its window in (as planned). Once more on the session ensureOatsTmuxSession returns (below).
+    // Not there: refused. Found elsewhere: the launch runs that one, and records it. Every executable
+    // named bare (the harness's name, a declared name) is looked up again, also one the plan could only
+    // look up on this process's PATH; a recorded (frozen) or a declared path never is.
+    const lookAgain = (pane) => {
+      if (!launchPlan || launchPlan.config?.frozen || launchPlan.config?.executable?.includes("/")) return false;
+      const { config, launchChoice } = launchPlan;
+      const actual = resolveLaunchExecutable({ harness: launchPlan.harness, declared: config?.executable, declaringDir: config?.source, lookup: launchLookup(config?.env, o.env || process.env, pane, config?.name, realHome) });
+      if (!actual.path) throw executableNotOnPanePath(actual, { harness: launchPlan.harness, config, from: launchChoice?.from, at: launchChoice?.at });
+      const bad = checkLaunchExecutable(actual.path);
+      if (bad) throw oatsError("E_LAUNCH_EXECUTABLE", `launch configuration ${config?.name || "(harness default)"}: ${bad}; nothing was started`);
+      if (actual.path === launchPlan.recipe.executable) return false;
+      launchPlan.recipe = { ...launchPlan.recipe, executable: actual.path };
+      command = launchPlan.command = renderLaunchRecipe(launchPlan.recipe, { home: realHome, instance: meta.instance, trustHome: launchPlan.trustHome });
+      return true;
+    };
+    lookAgain(retained ? () => panePath(target.socket, target.session, o.io, realHome) : () => expectedPanePath(tmuxSessionPlan, planSession, o.io, realHome));
     // 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,
@@ -5655,13 +6054,12 @@ export function startInstanceSession(home, o = {}) {
     const startedAt = new Date().toISOString();
     const id = randomUUID();
     checkRoots();
-    const executionCommand = nativeRecordCommand(command, realHome, launchPlan?.harness || harness);
-    const completedCommand = `${executionCommand}; oats_start_status=$?; printf '%s\\n' ${shq(id)} > ${shq(exitedPath)}`;
+    const windowCommand = () => paneCommand(`${nativeRecordCommand(command, realHome, launchPlan?.harness || harness)}; oats_start_status=$?; printf '%s\\n' ${shq(id)} > ${shq(exitedPath)}`);
     let reused = "new";
     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 = paneCommand(completedCommand);
+    let windowCmd = windowCommand();
     let moved = null;
     // A fallback shell (no harness descendant) or a retained dead pane is
     // the agent's own pane: the command runs there, on the server the home
@@ -5681,6 +6079,7 @@ export function startInstanceSession(home, o = {}) {
       // 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);
+      if (lookAgain(() => panePath(socket, session, o.io, realHome))) { planExtra.launch = launchPlan.recipe; windowCmd = windowCommand(); }
       let names;
       try { names = tmuxOn(socket, ["list-windows", "-t", `=${session}`, "-F", "#{window_name}"], o.io).split("\n").filter(Boolean); }
       catch (e) {
@@ -5722,6 +6121,287 @@ export function startInstanceSession(home, o = {}) {
   }
 }
 
+/** One Git call of a retirement inspection → its stdout, as bytes: a text
+ *  with one code unit per byte (latin1), so that no byte is replaced. Git
+ *  prints ref names and paths as the bytes they are, and decoded as UTF-8 two
+ *  names that differ only in bytes that are not UTF-8 would read alike: a
+ *  state a hook changed would compare equal, and a copy would be skipped.
+ *  What is compared is this text, never a decoded one. A value that is also
+ *  used as a path is decoded where it is used (repositoryGitState).
+ *  With `absent`, Git's quiet exit 1 ("no such ref", nothing on stderr)
+ *  gives null. Any other failure throws E_WORK_INSPECTION_FAILED: a state
+ *  that could not be read is never taken for an unchanged one. What a failed
+ *  read of the state means for the retire is inspectRetirementWork's
+ *  decision: not provable. */
+function inspectGit(repo, args, { absent = false, env } = {}) {
+  try {
+    return execFileSync("git", ["-C", repo, ...args], { stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER, ...(env ? { env: { ...process.env, ...env } } : {}) }).toString("latin1");
+  } catch (e) {
+    const detail = String(e.stderr ?? "").trim();
+    if (absent && e.status === 1 && !detail) return null;
+    throw oatsError("E_WORK_INSPECTION_FAILED", `could not inspect the Git state of ${repo}: ${detail || String(e.message ?? "").trim() || `git ${args[0]} failed`}`);
+  }
+}
+/** Whether an entry is there, for a read of the Git state. Only "not there"
+ *  is absence: a test that fails for any other reason (no permission on a
+ *  directory above it, for example) throws, so an entry the kernel cannot see
+ *  is never taken for one that does not exist. A link is followed, as
+ *  existsSync follows it. */
+function inspectedEntryExists(path) {
+  try { statSync(path); return true; }
+  catch (e) {
+    if (e.code === "ENOENT") return false;
+    throw oatsError("E_WORK_INSPECTION_FAILED", `could not inspect ${path}: ${e.message}`);
+  }
+}
+/** How the recovery copier resolves what it reads from a repository, read by
+ *  the copier and by the comparison alike (repositoryGitState), so that the
+ *  comparison holds the files the copy carries, found where the copy finds
+ *  them. Git's answer decoded as UTF-8 and trimmed of white space at both
+ *  ends: a path that ends in white space is read without it, which Git itself
+ *  does not do. That is the copier's own reading, kept as it is; a copy of
+ *  the file Git reads would be a change to the copier.
+ *  A worktree whose `core.worktree` (per-worktree configuration) names a
+ *  directory other than `<home>/work` is outside what the retire is
+ *  specified for: Git's status then describes that other directory while
+ *  the retire reads, copies and removes `<home>/work`. copierExcludesFile
+ *  resolves the excludes base the copier's way for it all the same; no test
+ *  pins it. */
+const copierGitText = (repo, args) => execFileSync("git", ["-C", repo, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER }).trim();
+/** The Git directory the copier copies the index and the operation entries from. */
+const copierGitDir = (repo) => copierGitText(repo, ["rev-parse", "--absolute-git-dir"]);
+/** The common directory the copier reads info/exclude, info/attributes and the stash's log from. */
+const copierCommonDir = (repo) => copierGitText(repo, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
+/** The file the copier reads for core.excludesFile; null when it reads none:
+ *  the value is unset, cannot be read, or is only white space. */
+function copierExcludesFile(repo) {
+  let value = "";
+  try { value = copierGitText(repo, ["config", "--path", "--get", "core.excludesFile"]); } catch { /* unset: Git's default applies to both repositories alike */ }
+  return value ? resolve(copierGitText(repo, ["rev-parse", "--show-toplevel"]), value) : null;
+}
+/** What a recovery's work copy holds of the worktree's repository beside the
+ *  bytes of its files: everything copyRecoveryWork carries or restores, read
+ *  the way it reads it, without reading the files. The rule: the work is
+ *  unchanged only if everything its copy would carry is byte-for-byte equal,
+ *  and anything that cannot be compared exactly counts as changed.
+ *   - its status text (the copy is verified against it);
+ *   - its HEAD as the copier reads it (headName): the whole ref, as its
+ *     bytes, which decides whether the copy is cloned on a branch or
+ *     detached; and the commit;
+ *   - the index the copier copies, by what it holds and not by its bytes:
+ *     its entries as `git ls-files -s -v` lists them (mode, object, stage and path, with the
+ *     skip-worktree and assume-unchanged marks), its resolve-undo records
+ *     (`git ls-files --resolve-undo`: resolving a conflict can add them while
+ *     every entry, status row and byte ends up as it was), and the file's
+ *     mode, which copyFileSync gives the copy. Its bytes also hold a stat
+ *     cache that a read-only Git command rewrites, and extensions derived
+ *     from the entries: those are a deliberate semantic exception, never
+ *     compared;
+ *   - each path the copier copies from the Git directories (COPIED_GIT_PATHS:
+ *     an operation in progress, info/attributes, the stash's log), by what its
+ *     copy carries, the permission bits included (copiedGitPathDigest);
+ *   - its tags: a clone brings them, and removing the remote leaves them;
+ *   - the stash ref (detachRecoveryClone fetches it);
+ *   - its exclude rules as carryExcludes reads them: the core.excludesFile
+ *     value, the file carryExcludes reads for it (copierExcludesFile), and
+ *     info/exclude. They are written into the copy as new text, so their
+ *     bytes are what it carries;
+ *   - its status settings as carryStatusConfig reads them: the effective
+ *     value of each STATUS_CONFIG key. The keys, not the configuration file:
+ *     Git rewrites that file for an upstream or a remote, which no copy
+ *     carries;
+ *   - `cloneHead`, for a worktree whose HEAD the copier copies detached (no
+ *     branch, a ref that is not a branch, a name that is not UTF-8): that copy
+ *     is cloned without --branch, so it keeps a local branch for the HEAD of
+ *     the repository it is cloned from, and none when that HEAD is not on a
+ *     branch. That HEAD is read as its whole ref.
+ *  The repository's other branches are not here: they outlive the worktree,
+ *  and the copy does not hold them. Its tags, stash, rules and settings are
+ *  the shared repository's: one made there by anyone while the retire hooks
+ *  run adds a copy attempt. The repository's objects and the settings a clone
+ *  of it is served under (its shallow boundary, grafts, hidden refs) stay in
+ *  it and are not compared: a custody boundary, which holds because no
+ *  retire removes that repository or deletes a branch.
+ *  Every read is inspectGit's, a file read or an existence test
+ *  (inspectedEntryExists): only Git's quiet "not set" and an entry that is
+ *  not there are absence; any other failure throws, and the worktree is then
+ *  not provable (inspectRetirementWork).
+ *  Everything in the list is compared as its bytes; nothing of it goes
+ *  through a decoding that replaces a byte. Git's output is inspectGit's
+ *  text of bytes, the status is the status bytes as such a text, a file is
+ *  the digest of its bytes, and a copied path is its exact digest
+ *  (fingerprintTrees), which reads names and link targets as bytes. The
+ *  three `rev-parse` paths and the `core.excludesFile` value are in the state
+ *  as Git printed them (`paths`, and the first of `excludesFile`), compared
+ *  as their bytes; a `rev-parse` path that does not decode to an existing one
+ *  throws below, and the worktree is not provable. Every file and directory
+ *  the state reads is found where the copier finds it, by the copier's own
+ *  functions (copierGitDir, copierCommonDir, copierExcludesFile, headName):
+ *  the state is what the copy carries, read the way the copy reads it. A
+ *  file the copier does not reach is not there for the state either.
+ *  `status`: the repository's worktreeStatusBytes, when the caller has it.
+ *  `cloneSource`: the repository the copy is cloned from (meta.repo). */
+function repositoryGitState(repo, { status, cloneSource } = {}) {
+  /** One of the copier's reads; any failure makes the worktree not provable. */
+  const asCopier = (read) => {
+    try { return read(repo); }
+    catch (e) {
+      if (e?.code === "E_WORK_INSPECTION_FAILED") throw e;
+      throw oatsError("E_WORK_INSPECTION_FAILED", `could not inspect the Git state of ${repo}: ${String(e?.stderr ?? "").trim() || String(e?.message ?? "").trim()}`);
+    }
+  };
+  // Three paths, one per line. A path with a line feed in it prints more
+  // lines, and taken apart wrongly every test below would read "not there",
+  // before the hooks and after them alike. So: exactly three, absolute, there.
+  /** A value Git printed, as the path the kernel's text paths name with it. */
+  const pathOf = (value) => Buffer.from(value, "latin1").toString("utf8");
+  const printed = inspectGit(repo, ["rev-parse", "--path-format=absolute", "--absolute-git-dir", "--git-common-dir", "--show-toplevel"]).split("\n");
+  if (printed.at(-1) === "") printed.pop();
+  const paths = printed.map(pathOf);
+  if (paths.length !== 3 || !paths.every((path) => isAbsolute(path) && inspectedEntryExists(path))) {
+    throw oatsError("E_WORK_INSPECTION_FAILED", `could not inspect the Git state of ${repo}: git rev-parse did not give its Git directory, its common directory and its top level as three existing absolute paths`);
+  }
+  const [gitDir, commonDir] = paths;
+  const bytesOf = (path) => {
+    try { return createHash("sha256").update(readFileSync(path)).digest("hex"); }
+    catch (e) {
+      if (e.code === "ENOENT") return null;
+      throw oatsError("E_WORK_INSPECTION_FAILED", `could not read ${path}: ${e.message}`);
+    }
+  };
+  /** The permission bits a copyFileSync gives the copy of `path`; null when it is not there. */
+  const modeOf = (path) => {
+    try { return statSync(path).mode & 0o7777; }
+    catch (e) {
+      if (e.code === "ENOENT") return null;
+      throw oatsError("E_WORK_INSPECTION_FAILED", `could not read ${path}: ${e.message}`);
+    }
+  };
+  /** One value Git may not have: null when it is not set. */
+  const valueOf = (...args) => inspectGit(repo, args, { absent: true })?.replace(/\n$/, "") ?? null;
+  const sourceValueOf = (...args) => inspectGit(cloneSource, args, { absent: true })?.replace(/\n$/, "") ?? null;
+  const head = asCopier(headName);
+  const copierGit = asCopier(copierGitDir), copierCommon = asCopier(copierCommonDir);
+  const excludesFile = valueOf("config", "--path", "--get", "core.excludesFile");
+  const excludesRead = asCopier(copierExcludesFile);
+  return {
+    paths: printed,
+    status: (status ?? worktreeStatusBytes(repo)).toString("latin1"),
+    head: head.ref === null ? null : head.ref.toString("latin1"),
+    commit: valueOf("rev-parse", "--verify", "--quiet", "HEAD"),
+    // The index the copier copies (copierGitDir), read as an index: Git's
+    // own, at a path that differs from it only in white space, is not what
+    // the copy carries. One that is not there lists nothing.
+    index: inspectGit(repo, ["ls-files", "-s", "-v", "-z"], { env: { GIT_INDEX_FILE: join(copierGit, "index") } }),
+    resolveUndo: inspectGit(repo, ["ls-files", "--resolve-undo", "-z"], { env: { GIT_INDEX_FILE: join(copierGit, "index") } }),
+    indexMode: modeOf(join(copierGit, "index")),
+    copied: COPIED_GIT_PATHS.map((entry) => copiedGitPathDigest(entry, copiedGitPath(entry, copierGit, copierCommon))),
+    tags: inspectGit(repo, ["for-each-ref", "--format=%(objectname) %(refname)", "refs/tags"]),
+    stash: valueOf("rev-parse", "--verify", "--quiet", "refs/stash"),
+    excludesFile: excludesFile === null && excludesRead === null ? null : [excludesFile, excludesRead, excludesRead && bytesOf(excludesRead)],
+    exclude: bytesOf(join(copierCommon, "info", "exclude")),
+    statusConfig: STATUS_CONFIG.map((key) => valueOf("config", "--get", key)),
+    // The copy is cloned from the repository the instance was spawned from
+    // (`cloneSource`, meta.repo), which can be a linked worktree of it: that
+    // repository's HEAD is read there, as its whole ref, not the common
+    // directory's.
+    cloneHead: head.branch === null && gitDir !== commonDir && cloneSource
+      ? [sourceValueOf("symbolic-ref", "--quiet", "HEAD"), sourceValueOf("rev-parse", "--verify", "--quiet", "HEAD")]
+      : null,
+  };
+}
+/** Every repository under a worktree, at any depth → [{ path, inner }]:
+ *  nestedGitRoots, and (`inner`) the repositories inside those. A recovery
+ *  rebuilds a nested repository from a clone; one inside it comes along as
+ *  plain files, its Git directory included, which the copy's verification
+ *  leaves out and which no read-only Git command can describe whole.
+ *  A directory whose `.git` cannot be tested (inspectedEntryExists throws),
+ *  or is a dangling symbolic link (a link `stat` cannot follow, which the
+ *  copy carries as a link and the digests pass over by its name), is listed
+ *  as { path, unknown: true }: it is not taken for a directory without a
+ *  repository, and not for a repository either. So every directory with a
+ *  `.git` entry of any kind is listed: a directory, a file, a link to
+ *  anything, a dangling link, and a `.git` that cannot be tested. */
+function repositoriesUnder(work) {
+  const out = [];
+  // Asked only where `stat` found no `.git`: whether there is an entry all the same.
+  const entryIsThere = (path) => {
+    try { lstatSync(path); return true; }
+    catch (e) {
+      if (e.code === "ENOENT") return false;
+      throw oatsError("E_WORK_INSPECTION_FAILED", `could not inspect ${path}: ${e.message}`);
+    }
+  };
+  const walk = (dir, inner) => {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      if (!e.isDirectory() || e.isSymbolicLink?.() || e.name === ".git") continue;
+      const path = join(dir, e.name);
+      let repository = false;
+      try {
+        repository = inspectedEntryExists(join(path, ".git"));
+        if (!repository && entryIsThere(join(path, ".git"))) out.push({ path, unknown: true });
+      } catch (e) {
+        if (e?.code !== "E_WORK_INSPECTION_FAILED") throw e;
+        out.push({ path, unknown: true });
+      }
+      if (repository) out.push({ path, inner });
+      walk(path, inner || repository);
+    }
+  };
+  walk(work, false);
+  return out;
+}
+/** The work state of a worktree instance, without the bytes of its files: the
+ *  worktree's Git state (repositoryGitState), as one text. Two inspections of
+ *  an untouched tree give the same text. The bytes are the other part, read
+ *  only when needed: observedWorkBytes. A repository under the worktree is not
+ *  part of it: such a worktree is not provable (inspectRetirementWork). */
+function worktreeGitState(work, status, cloneSource) { // `status`: the worktree's status bytes
+  return JSON.stringify({ worktree: repositoryGitState(work, { status, cloneSource }) });
+}
+/** The bytes of a worktree, Git metadata left out, as their exact digest: what a work copy is verified
+ *  with, and what proves that the hooks left the files as they were. One full read. Kept nowhere. */
+const worktreeBytes = (work) => exactTreeDigest(work, { excludeRoot: new Set([".git"]), excludeGitMetadata: true, children: true });
+/** The byte part of an observed worktree's work state, read at most once per
+ *  observation and kept on it; undefined where the observation saw no
+ *  worktree. An inspection never reads it. The retire reads it before it
+ *  writes the pre-hook recovery, the copy's verification uses it (so a pass
+ *  that copies the work costs no extra read), and so does the proof that the
+ *  retire hooks left the work as it was (movedByHooks). */
+function observedWorkBytes(observation) {
+  if (observation.worktree && observation.workBytes === undefined) {
+    // A read that fails is an inspection that failed, with its code: where the
+    // retire reads before it writes, nothing else gives the failure one.
+    try { observation.workBytes = worktreeBytes(observation.work); }
+    catch (e) {
+      if (e?.code === "E_WORK_INSPECTION_FAILED") throw e;
+      throw oatsError("E_WORK_INSPECTION_FAILED", `could not read the worktree at ${observation.work}: ${e.message}`);
+    }
+  }
+  return observation.workBytes;
+}
+/** What the retire hooks moved, between the observation before them and the
+ *  one after → { home, work }. Nothing when the later observation has nothing
+ *  to preserve. The home moved when its exact digest did: that is its bytes,
+ *  `instance.json` as it is. (The stored digest, which a baseline is compared
+ *  with, leaves the kernel's own fields of that file out and frames entries
+ *  without lengths; it reads alike some homes that differ.)
+ *  The work moved unless it is proven unchanged: a directory by its bytes
+ *  (its exact digest); a worktree by its Git state and, only when that is
+ *  equal, by its bytes. A status text or a class list alone proves nothing: a
+ *  hook can rewrite a file that was already modified. `before` must hold its
+ *  bytes already (the retire reads them before it writes the pre-hook
+ *  recovery); without them the work counts as moved. So does a worktree that
+ *  cannot be proven unchanged at all (`workProvable` false: a worktree that
+ *  holds a repository, or a read of the Git state that failed). */
+function movedByHooks(before, after) {
+  if (!after.classes.length) return { home: false, work: false };
+  const home = after.homeBytes !== before.homeBytes;
+  let work = after.workFingerprint !== before.workFingerprint;
+  if (!work && after.worktree) work = !before.workProvable || !after.workProvable || before.workBytes === undefined || observedWorkBytes(after) !== before.workBytes;
+  return { home, work };
+}
+
 function inspectRetirementWork(home, work, isWorktree, { recordedBranch, worktreeRemoval, directory = false, orphanedWork = false } = {}) {
   if (directory) assertDirectoryRoots(home);
   const classes = [];
@@ -5732,10 +6412,20 @@ function inspectRetirementWork(home, work, isWorktree, { recordedBranch, worktre
   } catch (e) {
     throw oatsError("E_WORK_INSPECTION_FAILED", `could not read the independent retirement baseline: ${e.message}`);
   }
-  const baselineValid = baseline?.version === RETIRE_BASELINE_VERSION && baseline.home === realPathOrNearest(home);
+  const baselineValid = retirementBaselineValid(baseline, home);
+  // This pass's one resolved exclusion set: provider-owned entries the spawn
+  // baseline declared. Every home fingerprint here and the copy made from this
+  // observation use it; without a valid baseline there is none.
+  const homeExclusions = resolveHomeExclusions(home, baselineValid ? baselineDisposableHome(baseline) : []);
+  // One walk of the home, two digests: the stored one for the comparison with
+  // the baseline, which must not see the kernel's own fields of instance.json,
+  // and the exact one for the comparison after the hooks, which must see
+  // every byte.
+  let homeDigests;
+  const fingerprintHome = () => (homeDigests ??= fingerprintTrees(home, { excludeRoot: homeExclusions.excludeRoot, instanceHome: true, exact: true, children: true })).stored;
   if (!baselineValid) {
     classes.push("unknown instance-home provenance");
-  } else if (baseline.homeFingerprint !== fingerprintTree(home, { excludeRoot: new Set(["work"]), instanceHome: true })) {
+  } else if (baseline.homeFingerprint !== fingerprintHome()) {
     classes.push("changed instance-home bytes");
   }
   // A mutable mode must not turn owned directory bytes into an excluded shared
@@ -5745,7 +6435,7 @@ function inspectRetirementWork(home, work, isWorktree, { recordedBranch, worktre
   }
   let directoryFingerprint;
   if (directory) {
-    directoryFingerprint = fingerprintTree(work);
+    directoryFingerprint = directoryBytes(work);
     // Never stamp hook-created or authored execution bytes as disposable.
     if (readdirSync(work).length) classes.push("directory work bytes");
   }
@@ -5756,24 +6446,65 @@ function inspectRetirementWork(home, work, isWorktree, { recordedBranch, worktre
   // 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 worktree = isWorktree && existsSync(work);
+  let gitState = "", workProvable = true;
+  if (worktree) {
+    // Read once, as bytes. The bytes go into the Git state; the rows, the
+    // classes and the comparison with the spawn baseline read them as text.
+    const statusBytes = worktreeStatusBytes(work);
+    const status = statusBytes.toString("utf8");
     const rows = status.split("\0").filter(Boolean);
     if (rows.some((row) => !row.startsWith("?? ") && !row.startsWith("!! "))) classes.push("tracked or index worktree state");
     const disposableRoots = baseline?.disposableReceipts?.map((r) => r.root) || [];
     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) : "")
+    const found = repositoriesUnder(work);
+    if (found.some((r) => !r.unknown)) classes.push("nested repository state");
+    // The one place where a read of the Git state that fails is decided. It
+    // is never taken for "not set" or for "unchanged", and it does not refuse
+    // either: main's inspection read none of this and let such a retire go
+    // on. The worktree is then not provable, and the copy decides, as it did
+    // on main: nothing to preserve retires, anything else is copied before
+    // the hooks (homeOnlyRecovery) and again after them (movedByHooks).
+    // `git status` is not part of this: it failed the inspection on main too.
+    try { gitState = worktreeGitState(work, statusBytes, worktreeRemoval?.repo); }
+    catch (e) {
+      if (!e?.code) throw e;
+      workProvable = false;
+    }
+    // A worktree that holds a repository is not provable either: a directory
+    // under it with a `.git` entry of any kind (repositoriesUnder, the
+    // predicate the class reads): a directory, a file, a link to anything, a
+    // dangling link, and a `.git` that cannot be tested. Only a repository
+    // the predicate can see adds the class; the last two make the work
+    // unprovable without it, and so never home-only (homeOnlyRecovery): a
+    // change to the home alone can then cause a work-copy attempt before
+    // the hooks that main did not make, and any failure of that attempt can
+    // refuse the retirement. The retire hooks run between the two copies and
+    // can change such a repository in ways no read of its state covers (its
+    // configuration, its objects, what a clone of it is shown), so its work
+    // is copied again after them, whatever they did. What stays in the repository the
+    // worktree belongs to needs no copy: no retire removes it or deletes a
+    // branch, and a worktree commit no ref reaches is preserved (the class
+    // above, `unreached`).
+    if (found.length) workProvable = false;
+  }
+  // Two values, so the post-hook pass can tell which part a hook moved: the
+  // home's bytes (its exact digest), and the work state's fingerprint. A
+  // directory's work state is its bytes (`directoryFingerprint`, an exact
+  // digest too). A worktree's is its Git state here, and its bytes, which an
+  // inspection does not read (observedWorkBytes). `workProvable`: whether
+  // that state could be read and covers everything a copy of the work would
+  // carry. None of these is kept in a baseline, a receipt or recovery.json.
+  // When the worktree will be removed, its HEAD (the commit and the ref's
+  // bytes) and whether a ref reaches that commit are part of the work state: a
+  // hook that deletes the ref that reached the commit changes nothing else
+  // the state holds, and the commit must still be preserved again after it.
+  fingerprintHome();
+  const workFingerprint = createHash("sha256").update(directory ? (directoryFingerprint || "missing") : gitState)
     .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, head: unreached?.head, runtimeAuthority: baselineValid ? runtimeAuthorityOf(baseline) : undefined };
+  return { classes: [...new Set(classes)], home, work, directory, orphanedWork, worktree, workProvable, directoryFingerprint, homeBytes: homeDigests.exact, workFingerprint, homeExclude: homeExclusions.excludeRoot, notCopied: homeExclusions.notCopied, branchExists, head: unreached?.head, runtimeAuthority: baselineValid ? runtimeAuthorityOf(baseline) : undefined };
 }
 
 function copyRecoveryTree(src, dest, { excludeRoot = new Set() } = {}) {
@@ -5789,6 +6520,44 @@ const RECOVERABLE_GIT_ADMIN = [
   "BISECT_LOG", "BISECT_START", "BISECT_NAMES", "rebase-apply", "rebase-merge", "sequencer",
 ];
 
+/** The paths of a repository's Git directories that a recovery's work copy
+ *  takes by copying them, beside the clone, the files and the index: one
+ *  selection, read by the copier (restoreStandaloneGitState,
+ *  carryStatusConfig, detachRecoveryClone) and by the comparison
+ *  (repositoryGitState), so that each copied path is compared by what its
+ *  copy carries (copiedGitPathDigest). `dir`: the repository's own Git
+ *  directory ("git") or its common directory ("common"). `copy`: copyTreeSafe
+ *  ("tree") or copyFileSync ("file").
+ *  The index is copied whole and is not in the selection: it is compared by
+ *  its entries, its resolve-undo records and its mode, never by its bytes,
+ *  which hold a cache that a read-only Git command rewrites. That is a
+ *  deliberate semantic exception (repositoryGitState). */
+const COPIED_GIT_PATHS = [
+  ...RECOVERABLE_GIT_ADMIN.map((name) => ({ dir: "git", path: [name], copy: "tree" })),
+  { dir: "common", path: ["info", "attributes"], copy: "file" },
+  { dir: "common", path: ["logs", "refs", "stash"], copy: "file" },
+];
+const [GIT_ATTRIBUTES, GIT_STASH_LOG] = COPIED_GIT_PATHS.slice(-2);
+const copiedGitPath = ({ dir, path }, gitDir, commonDir) => join(dir === "git" ? gitDir : commonDir, ...path);
+/** What the copy of one selected path carries, as a digest; null when the
+ *  path is not there. copyTreeSafe gives a copy the entry's kind, bytes or
+ *  target, and the bits of the entry and of everything under it: its exact
+ *  digest. copyFileSync follows a link and gives the copy the bytes and the
+ *  mode of what it reaches: those. Any failure but "not there" throws, as a
+ *  read of the Git state does, and so does a file path that is not a file. */
+function copiedGitPathDigest(entry, at) {
+  if (!inspectedEntryExists(at)) return null;
+  try {
+    if (entry.copy === "tree") return exactTreeDigest(at);
+    const st = statSync(at);
+    if (!st.isFile()) throw new Error("it is not a file");
+    return createHash("sha256").update(`${st.mode & 0o7777}\0`).update(readFileSync(at)).digest("hex");
+  } catch (e) {
+    if (e?.code === "E_WORK_INSPECTION_FAILED") throw e;
+    throw oatsError("E_WORK_INSPECTION_FAILED", `could not read ${at}: ${e.message}`);
+  }
+}
+
 /** Object ids among `oids` that `repo` does not have, from one
  *  `cat-file --batch-check` process. */
 export function missingGitObjects(repo, oids) {
@@ -5803,7 +6572,7 @@ export function missingGitObjects(repo, oids) {
 }
 
 function restoreStandaloneGitState(sourceWork, recoveredRepo) {
-  const sourceGit = execFileSync("git", ["-C", sourceWork, "rev-parse", "--absolute-git-dir"], { encoding: "utf8" , maxBuffer: GIT_MAX_BUFFER }).trim();
+  const sourceGit = copierGitDir(sourceWork);
   const recoveredGit = join(recoveredRepo, ".git");
   const indexRows = execFileSync("git", ["-C", sourceWork, "ls-files", "--stage", "-z"], { maxBuffer: GIT_MAX_BUFFER });
   // The staged blobs the recovered index will point at. The clone already
@@ -5827,11 +6596,13 @@ function restoreStandaloneGitState(sourceWork, recoveredRepo) {
   }
   const stillMissing = missingGitObjects(recoveredRepo, [...staged]);
   if (stillMissing.length) throw new Error(`recovered repository lacks ${stillMissing.length} staged object(s) after restore: ${stillMissing.slice(0, 3).join(", ")}`);
+  // The index is the selection's one exception (COPIED_GIT_PATHS): copied
+  // whole, compared by its entries, resolve-undo records and mode.
   copyFileSync(join(sourceGit, "index"), join(recoveredGit, "index"));
-  for (const name of RECOVERABLE_GIT_ADMIN) {
-    const source = join(sourceGit, name);
+  for (const entry of COPIED_GIT_PATHS.filter((e) => e.dir === "git")) {
+    const source = copiedGitPath(entry, sourceGit);
     if (!existsSync(source)) continue;
-    const dest = join(recoveredGit, name);
+    const dest = copiedGitPath(entry, recoveredGit);
     rmSync(dest, { recursive: true, force: true });
     copyTreeSafe(source, dest);
   }
@@ -5844,7 +6615,6 @@ function restoreStandaloneGitState(sourceWork, recoveredRepo) {
  *  info/exclude, which keeps Git's precedence (a later pattern wins, and info/exclude outranks
  *  core.excludesFile). → the sources carried, [{ kind, path }]. */
 function carryExcludes(sourceWork, recoveredRepo) {
-  const git = (...args) => execFileSync("git", ["-C", sourceWork, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER }).trim();
   const carried = [], parts = [];
   // A file with no pattern line (Git's template info/exclude is comments only) changes nothing: not carried.
   const carry = (kind, file) => {
@@ -5853,12 +6623,9 @@ function carryExcludes(sourceWork, recoveredRepo) {
     if (!text.split("\n").some((line) => line.trim() && !line.startsWith("#"))) return;
     parts.push(text); carried.push({ kind, path: file });
   };
-  let excludesFile = "";
-  try { excludesFile = git("config", "--path", "--get", "core.excludesFile"); } catch { /* unset: Git's default applies to both repositories alike */ }
-  if (excludesFile) {
-    carry("core.excludesFile", resolve(git("rev-parse", "--show-toplevel"), excludesFile));
-  }
-  carry("info/exclude", join(git("rev-parse", "--path-format=absolute", "--git-common-dir"), "info", "exclude"));
+  const excludesFile = copierExcludesFile(sourceWork);
+  if (excludesFile) carry("core.excludesFile", excludesFile);
+  carry("info/exclude", join(copierCommonDir(sourceWork), "info", "exclude"));
   if (!carried.length) return carried;
   mkdirSync(join(recoveredRepo, ".git", "info"), { recursive: true });
   writeFileSync(join(recoveredRepo, ".git", "info", "exclude"), parts.map((t) => (t.endsWith("\n") ? t : `${t}\n`)).join(""));
@@ -5885,11 +6652,12 @@ function carryStatusConfig(sourceWork, recoveredRepo) {
     execFileSync("git", ["-C", recoveredRepo, "config", "--local", ...(value === null ? ["--unset-all", key] : [key, value])], { stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER });
     carried.push({ kind: "config", key, value });
   }
-  const common = execFileSync("git", ["-C", sourceWork, "rev-parse", "--path-format=absolute", "--git-common-dir"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER }).trim();
-  const attributes = join(common, "info", "attributes");
+  const common = copierCommonDir(sourceWork);
+  const attributes = copiedGitPath(GIT_ATTRIBUTES, null, common);
   if (existsSync(attributes)) {
-    mkdirSync(join(recoveredRepo, ".git", "info"), { recursive: true });
-    copyFileSync(attributes, join(recoveredRepo, ".git", "info", "attributes"));
+    const dest = copiedGitPath(GIT_ATTRIBUTES, null, join(recoveredRepo, ".git"));
+    mkdirSync(dirname(dest), { recursive: true });
+    copyFileSync(attributes, dest);
     carried.push({ kind: "info/attributes", path: attributes });
   }
   return carried;
@@ -5901,10 +6669,10 @@ function detachRecoveryClone(source, recovered) {
   catch { stash = undefined; }
   if (stash) {
     execFileSync("git", ["-C", recovered, "fetch", "--quiet", source, "refs/stash:refs/stash"], { maxBuffer: GIT_MAX_BUFFER });
-    const sourceCommon = execFileSync("git", ["-C", source, "rev-parse", "--path-format=absolute", "--git-common-dir"], { encoding: "utf8" , maxBuffer: GIT_MAX_BUFFER }).trim();
-    const stashLog = join(sourceCommon, "logs", "refs", "stash");
+    const sourceCommon = copierCommonDir(source);
+    const stashLog = copiedGitPath(GIT_STASH_LOG, null, sourceCommon);
     if (existsSync(stashLog)) {
-      const recoveredLog = join(recovered, ".git", "logs", "refs", "stash");
+      const recoveredLog = copiedGitPath(GIT_STASH_LOG, null, join(recovered, ".git"));
       mkdirSync(dirname(recoveredLog), { recursive: true });
       copyFileSync(stashLog, recoveredLog);
     }
@@ -5965,7 +6733,133 @@ function preservedOutputs(work, directory) {
   return { paths, bytes: paths.reduce((n, p) => n + p.bytes, 0) };
 }
 
-function preserveRetirementWork(observation, meta, instance) {
+/** The home part of a recovery at `dest`: everything but work/ and this pass's
+ *  excluded provider-owned entries (observation.homeExclude), verified against
+ *  the source with that same set. The copy is hashed whole, so an excluded
+ *  entry that reached it fails the verification. The stored digest is what
+ *  is compared: it leaves the kernel's own fields of instance.json out, so a
+ *  kernel write there between the copy and this check is not a disagreement.
+ *  That is an inherited limit, and this is not an exact verification of the
+ *  whole home: the stored digest also passes over the kernel's receipts and
+ *  the harness settings, reads instance.json through a parse, and frames its
+ *  entries without lengths. */
+function copyRecoveryHome(observation, dest) {
+  const excludeRoot = observation.homeExclude || new Set(["work"]);
+  copyRecoveryTree(observation.home, dest, { excludeRoot });
+  if (fingerprintTree(observation.home, { excludeRoot, instanceHome: true }) !== fingerprintTree(dest, { instanceHome: true })) {
+    throw new Error("home recovery verification disagreed with the source");
+  }
+}
+
+/** The work part of a recovery under `parent`, copied and verified: `repo/`, a
+ *  standalone clone of a worktree instance's repository carrying its
+ *  uncommitted state, or `work/`, a directory instance's bytes. A worktree's
+ *  source bytes are the observation's (observedWorkBytes), so the verified
+ *  value is also its byte state. → { copied, branchDrift?, excludes?,
+ *  statusConfig? }; `copied` is false where neither applies (another work
+ *  mode, or a worktree home with no recorded repo or branch). A HEAD that
+ *  cannot be read is an inspection failure, not a failed copy: its error is
+ *  put in `unreadableHeads`, and the callers throw it as it is. */
+const unreadableHeads = new WeakSet();
+function copyRecoveryWork(observation, meta, parent) {
+  let branchDrift, excludes, statusConfig, copied = false;
+  if (meta.work === "worktree" && meta.repo && meta.branch && (existsSync(observation.work) || observation.branchExists)) {
+    const recoveredRepo = join(parent, "repo");
+    // 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. A HEAD that is detached, or on a ref OATS
+    // carries no name for, recovers detached at its exact commit.
+    let ref;
+    try { ref = existsSync(observation.work) ? worktreeHead(observation.work) : { branch: meta.branch, commit: null }; }
+    catch (e) { unreadableHeads.add(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.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);
+    if (existsSync(observation.work)) {
+      restoreStandaloneGitState(observation.work, recoveredRepo);
+      excludes = carryExcludes(observation.work, recoveredRepo).map((c) => ({ repo: ".", ...c }));
+      statusConfig = carryStatusConfig(observation.work, recoveredRepo).map((c) => ({ repo: ".", ...c }));
+      for (const e of readdirSync(observation.work, { withFileTypes: true })) {
+        if (e.name === ".git") continue;
+        const dest = join(recoveredRepo, e.name);
+        rmSync(dest, { recursive: true, force: true });
+        copyTreeSafe(join(observation.work, e.name), dest);
+      }
+      const nested = materializeNestedRepositories(observation.work, recoveredRepo);
+      excludes.push(...nested.excludes); statusConfig.push(...nested.statusConfig);
+    }
+    if (existsSync(join(recoveredRepo, ".git", "objects", "info", "alternates"))) throw new Error("recovery clone depends on object alternates");
+    if (existsSync(observation.work)) {
+      // The source's bytes as this observation holds them: read before the
+      // pre-hook recovery was written, or by the proof that the hooks moved
+      // nothing, or else here. Either way they are kept as the observation's
+      // byte state.
+      if ((observation.worktree ? observedWorkBytes(observation) : worktreeBytes(observation.work)) !== worktreeBytes(recoveredRepo)) 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.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");
+    copied = true;
+  }
+  if (observation.directory && observation.directoryFingerprint) {
+    const recoveredWork = join(parent, "work");
+    copyTreeSafe(observation.work, recoveredWork);
+    if (directoryBytes(observation.work) !== observation.directoryFingerprint || directoryBytes(recoveredWork) !== observation.directoryFingerprint) {
+      throw new Error("directory recovery verification disagreed with the inspected source");
+    }
+    copied = true;
+  }
+  return { copied, branchDrift, excludes, statusConfig };
+}
+
+/** The top-level entries of a recovery's home snapshot with their bytes,
+ *  largest first; a directory ends in `/`. What the retire summary names as
+ *  copied from the home. */
+function preservedHome(recoveredHome) {
+  const paths = readdirSync(recoveredHome, { withFileTypes: true })
+    .map((e) => ({ path: e.isDirectory() ? `${e.name}/` : e.name, bytes: treeBytes(join(recoveredHome, e.name)) }))
+    .sort((a, b) => b.bytes - a.bytes || a.path.localeCompare(b.path));
+  return { paths, bytes: paths.reduce((n, p) => n + p.bytes, 0) };
+}
+
+/** Whether a recovery of this observation holds the home only. A home-only
+ *  change (notes, harness files, credentials) needs a home snapshot, not
+ *  another copy of an otherwise disposable clean worktree. In-progress Git
+ *  operations retain the full standalone recovery even when porcelain status
+ *  has no changed paths. An orphaned work directory (no git admin entry) stays
+ *  where it is, never moved or removed, and git cannot read it: only the home
+ *  is snapshotted. A worktree that cannot be proven unchanged (workProvable
+ *  false) is never home-only: after the hooks it could be neither proven nor
+ *  taken as copied, so its work goes into the snapshot before them. */
+function homeOnlyRecovery(observation, meta) {
+  if (observation.orphanedWork === true) return true;
+  if (observation.workProvable === false) return false;
+  if (!(observation.classes.length === 1 && observation.classes[0] === "changed instance-home bytes" && meta.work === "worktree" && existsSync(observation.work))) return false;
+  const gitDir = copierGitDir(observation.work);
+  return !RECOVERABLE_GIT_ADMIN.some((name) => existsSync(join(gitDir, name)));
+}
+
+/** Write one verified recovery of an observed home and work: staged beside its
+ *  final name and renamed into place. `phase` goes into recovery.json:
+ *  "before-hooks" for the snapshot a retirement takes before its retire hooks
+ *  (completeRetirementRecovery concludes it), "complete" for a recovery nothing
+ *  will add to. → { receipt, manifest }: the receipt retire reports, and
+ *  recovery.json as written. */
+function writeRetirementRecovery(observation, meta, instance, phase) {
   const recoveryRoot = join(retirementStateRoot(observation.home), "recovery");
   mkdirSync(recoveryRoot, { recursive: true });
   if (observation.directory && realpathSync(recoveryRoot) !== join(realpathSync(dirname(observation.home)), ".oats-retirement", "recovery")) {
@@ -5973,98 +6867,115 @@ 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.
-    // In-progress Git operations retain the full standalone recovery even
-    // when porcelain status has no changed paths.
-    // An orphaned work directory (no git admin entry) stays where it is, never moved or removed, and git
-    // cannot read it: only the home is snapshotted.
-    let homeOnly = observation.orphanedWork === true || (observation.classes.length === 1 && observation.classes[0] === "changed instance-home bytes"
-      && meta.work === "worktree" && existsSync(observation.work));
-    if (homeOnly && !observation.orphanedWork) {
-      const gitDir = execFileSync("git", ["-C", observation.work, "rev-parse", "--absolute-git-dir"], { encoding: "utf8", maxBuffer: GIT_MAX_BUFFER }).trim();
-      homeOnly = !RECOVERABLE_GIT_ADMIN.some((name) => existsSync(join(gitDir, name)));
-    }
+    const homeOnly = homeOnlyRecovery(observation, meta);
     const recoveredHome = join(staging, "home");
-    copyRecoveryTree(observation.home, recoveredHome, { excludeRoot: new Set(["work"]) });
-    if (fingerprintTree(observation.home, { excludeRoot: new Set(["work"]), instanceHome: true }) !== fingerprintTree(recoveredHome, { instanceHome: true })) {
-      throw new Error("home recovery verification disagreed with the source");
-    }
-    let branchDrift, excludes, statusConfig;
-    if (!homeOnly && meta.work === "worktree" && meta.repo && meta.branch && (existsSync(observation.work) || observation.branchExists)) {
-      const recoveredRepo = join(staging, "repo");
-      // 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. 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.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);
-      if (existsSync(observation.work)) {
-        restoreStandaloneGitState(observation.work, recoveredRepo);
-        excludes = carryExcludes(observation.work, recoveredRepo).map((c) => ({ repo: ".", ...c }));
-        statusConfig = carryStatusConfig(observation.work, recoveredRepo).map((c) => ({ repo: ".", ...c }));
-        for (const e of readdirSync(observation.work, { withFileTypes: true })) {
-          if (e.name === ".git") continue;
-          const dest = join(recoveredRepo, e.name);
-          rmSync(dest, { recursive: true, force: true });
-          copyTreeSafe(join(observation.work, e.name), dest);
-        }
-        const nested = materializeNestedRepositories(observation.work, recoveredRepo);
-        excludes.push(...nested.excludes); statusConfig.push(...nested.statusConfig);
-      }
-      if (existsSync(join(recoveredRepo, ".git", "objects", "info", "alternates"))) throw new Error("recovery clone depends on object alternates");
-      if (existsSync(observation.work)) {
-        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.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");
-      copyTreeSafe(observation.work, recoveredWork);
-      if (fingerprintTree(observation.work) !== observation.directoryFingerprint || fingerprintTree(recoveredWork) !== observation.directoryFingerprint) {
-        throw new Error("directory recovery verification disagreed with the inspected source");
-      }
-    }
+    copyRecoveryHome(observation, recoveredHome);
+    const { branchDrift, excludes, statusConfig } = homeOnly ? {} : copyRecoveryWork(observation, meta, staging);
     const repoCopy = homeOnly ? { copied: false, reason: "Only instance-home bytes changed; no work state requires a repository copy", source: meta.repo, branch: meta.branch } : undefined;
-    // What the copy cost: the untracked/ignored (or directory) outputs it carries, named.
+    // What the copy cost: the home entries it carries and the untracked/ignored (or directory) outputs, named.
+    const home = preservedHome(recoveredHome);
     const workCopied = observation.directory ? !!observation.directoryFingerprint : !homeOnly && meta.work === "worktree" && existsSync(observation.work);
     const outputs = workCopied ? preservedOutputs(observation.work, observation.directory) : undefined;
-    writeFileSync(join(staging, "recovery.json"), JSON.stringify({ version: 1, instance, classes: observation.classes, sourceHome: observation.home, createdAt: new Date().toISOString(), ...(repoCopy ? { repoCopy } : {}), ...(branchDrift ? { branchDrift } : {}), ...(excludes?.length ? { excludes } : {}), ...(statusConfig?.length ? { statusConfig } : {}), ...(outputs ? { outputs } : {}) }, null, 2) + "\n", { mode: 0o600 });
+    const notCopied = observation.notCopied?.length ? observation.notCopied : undefined;
+    const manifest = { version: 1, phase, instance, classes: observation.classes, sourceHome: observation.home, createdAt: new Date().toISOString(), ...(repoCopy ? { repoCopy } : {}), ...(branchDrift ? { branchDrift } : {}), ...(excludes?.length ? { excludes } : {}), ...(statusConfig?.length ? { statusConfig } : {}), home, ...(outputs ? { outputs } : {}), ...(notCopied ? { notCopied } : {}) };
+    writeFileSync(join(staging, "recovery.json"), JSON.stringify(manifest, null, 2) + "\n", { mode: 0o600 });
     const bytes = treeBytes(staging);
     mkdirSync(dirname(recovery), { recursive: true });
     renameSync(staging, recovery);
-    return { path: recovery, classes: observation.classes, bytes, ...(outputs ? { outputs } : {}), ...(repoCopy ? { repoCopy } : {}) };
+    return { receipt: { path: recovery, classes: observation.classes, bytes, home, ...(outputs ? { outputs } : {}), ...(repoCopy ? { repoCopy } : {}), ...(notCopied ? { notCopied } : {}) }, manifest };
   } catch (e) {
     rmSync(staging, { recursive: true, force: true });
-    if (e === headUnreadable) throw e;
+    if (unreadableHeads.has(e)) 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 } : {});
   }
 }
 
+/** One complete recovery, for a caller with no retire hooks still to run
+ *  between the snapshot and the removal. → its receipt. */
+function preserveRetirementWork(observation, meta, instance) {
+  return writeRetirementRecovery(observation, meta, instance, "complete").receipt;
+}
+
+/** The post-hook check on the recovery a retirement wrote before its retire
+ *  hooks. Each part a hook moved (movedByHooks: the home by its bytes, the work
+ *  unless it is proven unchanged) is copied again, whole and verified, under
+ *  `after-hooks/`; nothing under the pre-hook `home/`, `repo/` or `work/` is
+ *  written, moved or removed. The home is not copied again merely because the
+ *  work is: a home whose every byte the hooks left as it was (its exact
+ *  digest) is in the pre-hook snapshot as it still is.
+ *  `after-hooks/` is staged inside the recovery under a dot-name and renamed
+ *  into place; an `after-hooks` entry that already exists is a failure, never
+ *  replaced. Then ONE atomic rewrite of recovery.json records `afterHooks` and
+ *  moves `phase` to "complete" (the same rewrite, without `afterHooks`, when
+ *  the hooks changed nothing). Until that rewrite the manifest says
+ *  "before-hooks", so an interrupted pass under-reports and can never read as
+ *  complete. A failure removes the staging, leaves the pre-hook snapshot and
+ *  its manifest as they were, and refuses: the caller keeps the home.
+ *  Directory mode: the retire hooks ran since the pre-hook pass verified that
+ *  the recovery sits in the owned storage beside the home, so that is verified
+ *  again before anything is written through its path.
+ *  → the receipt, updated: `classes` and `notCopied` are the union of both
+ *  passes, `bytes` covers the whole directory. */
+function completeRetirementRecovery({ receipt, manifest }, before, after, meta) {
+  const recovery = receipt.path;
+  const moved = movedByHooks(before, after);
+  const wantHome = moved.home;
+  const final = join(recovery, "after-hooks");
+  const manifestPath = join(recovery, "recovery.json");
+  const manifestTmp = join(recovery, `.recovery.json.${process.pid}.tmp`);
+  const occupied = () => { try { lstatSync(final); return true; } catch { return false; } };
+  const assertOwnedStorage = () => {
+    if (!after.directory) return;
+    let owned = false;
+    try { owned = realpathSync(recovery) === join(realpathSync(dirname(after.home)), ".oats-retirement", "recovery", basename(recovery)); } catch { /* gone: not the owned storage */ }
+    if (!owned) throw new Error("directory recovery storage was redirected");
+  };
+  let staging, manifestStarted = false;
+  try {
+    assertOwnedStorage();
+    // Work that is not proven unchanged is copied. So is work this recovery does
+    // not hold yet: a pre-hook snapshot that was home-only stands for no work,
+    // so "unchanged" proves nothing about it. When the observation after the
+    // hooks is not home-only by that pass's own rule, the work is copied, moved
+    // or not: a class can appear from outside the work state (the baseline is
+    // gone). That rule only ever adds a copy attempt here; it never skips one.
+    // It asks Git, so it is decided in here: a failure refuses like any other
+    // in this pass.
+    const firstWorkCopy = receipt.repoCopy?.copied === false && after.classes.length > 0 && !homeOnlyRecovery(after, meta);
+    const wantWork = !after.orphanedWork && (moved.work || firstWorkCopy);
+    let afterHooks;
+    if (wantHome || wantWork) {
+      if (occupied()) throw new Error(`${final} already exists`);
+      staging = mkdtempSync(join(recovery, ".after-hooks-"));
+      if (wantHome) copyRecoveryHome(after, join(staging, "home"));
+      const workCopied = wantWork && copyRecoveryWork(after, meta, staging).copied;
+      if (wantHome || workCopied) {
+        if (occupied()) throw new Error(`${final} already exists`);
+        renameSync(staging, final);
+        afterHooks = { home: wantHome, work: workCopied };
+      } else rmSync(staging, { recursive: true, force: true });
+      staging = undefined;
+    }
+    const classes = [...new Set([...receipt.classes, ...after.classes])];
+    const notCopied = unionNotCopied(receipt.notCopied, after.notCopied);
+    const { notCopied: _before, ...rest } = manifest;
+    assertOwnedStorage();
+    manifestStarted = true;
+    writeFileSync(manifestTmp, JSON.stringify({ ...rest, phase: "complete", classes, ...(notCopied.length ? { notCopied } : {}), ...(afterHooks ? { afterHooks } : {}) }, null, 2) + "\n", { mode: 0o600 });
+    renameSync(manifestTmp, manifestPath);
+    const { notCopied: _was, ...kept } = receipt;
+    return { ...kept, classes, bytes: treeBytes(recovery), ...(notCopied.length ? { notCopied } : {}), ...(afterHooks ? { afterHooks } : {}) };
+  } catch (e) {
+    if (staging) rmSync(staging, { recursive: true, force: true });
+    if (manifestStarted) rmSync(manifestTmp, { force: true });
+    if (unreadableHeads.has(e)) throw e;
+    const details = e.statusDisagreement ? { home: after.home, statusDisagreement: e.statusDisagreement } : undefined;
+    throw Object.assign(oatsError("E_WORK_PRESERVATION_FAILED", `retirement work remains at ${after.home}; recovery could not be verified: ${e.message}`, details), details ? { details } : {});
+  }
+}
+
 /** Marker a self-retiring instance leaves BESIDE its home: the retirement is
  *  requested and owed, and a detached completion is on its way. It is not
  *  written into the home, so the caller changes no instance bytes and the
@@ -6361,6 +7272,7 @@ export function retireInstance(root, name, o = {}) {
   // `=` forces exact matching: tmux targets otherwise PREFIX-match window names.
   // A no-launch instance is already quiesced. A launched one must have exact
   // window absence established before recovery copying begins.
+  let sessionStopped = false;
   if (!self && runtimeAuthority?.launched) {
     const runtimeSession = runtimeAuthority.tmux.session;
     const runtimeWindow = runtimeAuthority.tmux.window;
@@ -6384,11 +7296,41 @@ export function retireInstance(root, name, o = {}) {
         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` : ""})`);
       }
     }
+    sessionStopped = true;
   }
   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);
+  // The bytes of the worktree as they are before the hooks: after the hooks,
+  // "the work did not move" is then proven, never taken from a status text.
+  // Read before the recovery is written, so that a worktree that cannot be
+  // read (an entry that is not a file, a directory or a symbolic link)
+  // refuses here and leaves no recovery behind, however often it is retried.
+  // The refusal says what this retire has and has not done by now: a launched
+  // instance's session was stopped above. A pre-hook copy of the work
+  // verifies itself against this same read. A worktree that cannot be proven
+  // unchanged is copied again in any case, and with nothing to preserve
+  // before the hooks there is nothing to prove: any class after them is
+  // preserved.
+  // What a refusal before the hooks tells the operator about the retire so far.
+  const soFar = (kept) => `${name} is not retired and ${kept}; ${sessionStopped ? "its session has been stopped" : "this retire stopped no session"}`;
+  if (stableObservation.classes.length && stableObservation.workProvable) {
+    try { observedWorkBytes(stableObservation); }
+    catch (e) {
+      throw oatsError(e.code, `${e.message}. No recovery was written and nothing was deleted: ${soFar("its home is kept")}`);
+    }
+  }
+  // One recovery per retirement. The snapshot taken here, before the retire
+  // hooks, is the gate: it is verified before any hook runs and is never
+  // rewritten. What the hooks change is added to it afterwards. A copy that
+  // cannot be made or verified refuses here, with the same disclosure.
+  let preHookRecovery;
+  if (stableObservation.classes.length) {
+    try { preHookRecovery = writeRetirementRecovery(stableObservation, meta, name, "before-hooks"); }
+    catch (e) {
+      if (e?.code !== "E_WORK_PRESERVATION_FAILED") throw e;
+      throw Object.assign(oatsError(e.code, `${e.message}. No retire hook has run, no recovery was written and nothing was deleted: ${soFar("its home and work are kept")}`, e.provenance), e.details ? { details: e.details } : {});
+    }
+  }
+  let workRecovery = preHookRecovery?.receipt;
 
   // Capability lifecycle hooks (retire) — run BEFORE the dir (and any package state in it,
   // e.g. aweb signing keys) is removed. The knowledge integration harvests notes/ here;
@@ -6463,11 +7405,19 @@ 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.
+  // them. A recovery written before the hooks gains a separately verified
+  // snapshot of each part they moved, under its after-hooks/, and its manifest
+  // is concluded; a home that only now has something to preserve gets its one
+  // recovery here. Nothing was preserved before the hooks only when there was
+  // no class then, so a class now is something new to preserve, whether it
+  // came from the home, from the work or from outside both (another ref, the
+  // baseline): it does not have to be a move of the observed state. Either
+  // way this finishes, or refuses and keeps the home, before the worktree
+  // step and before the home is removed.
   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);
+  if (preHookRecovery) workRecovery = completeRetirementRecovery(preHookRecovery, stableObservation, finalObservation, meta);
+  else if (finalObservation.classes.length) {
+    workRecovery = preserveRetirementWork({ ...finalObservation, notCopied: unionNotCopied(stableObservation.notCopied, finalObservation.notCopied) }, meta, name);
   }
 
   // Lineage repair: any instance pointing at the retiree (parentInstance from a
@@ -6673,7 +7623,7 @@ 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: 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 result = { retired: name, agent: found.agent.name, workRecovery, 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) {