@awebai/oats 0.22.19 → 0.23.0

package/lib/core.mjs

@@ -23,7 +23,7 @@
  * soul.yaml (flat key: value):
  *   name, description, kind (persistent|local), type (optional agent-type/family, targeted by config),
  *   repo (path rel. to workspace or absolute),
- *   work (worktree|checkout|attached), runtime (pi|claude|codex), model (pi model pattern, optional)
+ *   work (worktree|checkout|attached|workspace|directory), runtime (pi|claude|codex), model (pi model pattern, optional)
  *   (attached as soul default is for service agents — spawn must supply workDir)
  */
 import { execFileSync, execSync, spawn as spawnProcess } from "node:child_process";
@@ -35,6 +35,7 @@ import { accessSync, constants as fsConstants } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { createHash, randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
+import { initializeNativeHistory, prepareNativeStart } from "../packages/record/lib/native-history.mjs";
 import { attachSessionTarget } from "./session-viewer.mjs";
 import { inspectSessionTarget, inputSessionTarget } from "./session-input.mjs";
 import { ensureHerdr, allocateHerdr, launchHerdr, inspectHerdr, stopHerdr, validHerdrTarget, herdrSnapshot, herdrCommand } from "./herdr.mjs";
@@ -42,7 +43,7 @@ import { ensureHerdr, allocateHerdr, launchHerdr, inspectHerdr, stopHerdr, valid
 export const RESERVED = new Set(["bin", "local-agents", "tmp-agents"]);
 /** The work modes spawn accepts — also the enum a quarantine cleanup descriptor
  * must satisfy, so the retry cannot skip Git cleanup on an unrecognised value. */
-export const WORK_MODES = ["worktree", "checkout", "attached", "workspace"];
+export const WORK_MODES = ["worktree", "checkout", "attached", "workspace", "directory"];
 /** Local (uncommitted) souls dir: <scope>/local-agents, a SIBLING of agents/.
  * Legacy nested <root>/local-agents and <root>/tmp-agents are still read. */
 export const LOCAL_AGENTS_DIR = "local-agents";
@@ -340,10 +341,12 @@ export function parseFrontmatter(text) {
 }
 
 // ---------- root discovery ----------
-/** Closest agents/ dir walking up from `cwd`. Returns undefined if none. */
+/** Closest agents/local-agents layout walking up from `cwd`; without one,
+ * the nearest non-laptop config declares a package-only deployment root. */
 export function findRoot(cwd = process.cwd()) {
   if (process.env.PI_AGENTS_ROOT) return resolve(process.env.PI_AGENTS_ROOT);
   let d = resolve(cwd);
+  let configuredRoot; // package-only deployments need no pre-created soul directories
   while (true) {
     if (basename(d) === "agents" && lstatSync(d).isDirectory()) return d;
     if (basename(d) === LOCAL_AGENTS_DIR && lstatSync(d).isDirectory() && basename(dirname(d)) !== "agents") {
@@ -354,8 +357,9 @@ export function findRoot(cwd = process.cwd()) {
     // A scope with only local agents is fully operable: its canonical agents
     // root is the (possibly absent) sibling agents/ dir.
     if (existsSync(join(d, LOCAL_AGENTS_DIR)) && lstatSync(join(d, LOCAL_AGENTS_DIR)).isDirectory()) return candidate;
+    if (!configuredRoot && d !== homedir() && existsSync(join(d, "oats-config.yaml"))) configuredRoot = candidate;
     const parent = dirname(d);
-    if (parent === d) return undefined;
+    if (parent === d) return configuredRoot;
     d = parent;
   }
 }
@@ -486,7 +490,7 @@ export function ensureRoot(cwd) {
   const root = findRoot(cwd);
   if (!root) {
     throw new Error(
-      `no agents/ or local-agents/ directory found walking up from ${resolve(cwd ?? process.cwd())} — create one (mkdir agents, or \`oats create <name> --local\`) or set PI_AGENTS_ROOT`,
+      `no agents/, local-agents/, or deployment oats-config.yaml found walking up from ${resolve(cwd ?? process.cwd())} — create one (mkdir agents, or \`oats create <name> --local\`) or set PI_AGENTS_ROOT`,
     );
   }
   // Deployment root ≠ invocation CWD: homes always land in the primary checkout.
@@ -4621,7 +4625,7 @@ function validateHookEnvironment(capabilityID, value, owners, declarations) {
   return accepted;
 }
 
-export function runLifecycleHooks(event, { home, instance, agentName, soulDir, contextDir, workspaceDir, rootDir, resolved, priorMeta = {}, extraEnv = {} }) {
+export function runLifecycleHooks(event, { home, instance, agentName, soulDir, contextDir, workspaceDir, rootDir, resolved, priorMeta = {}, extraEnv = {}, assertRoots }) {
   const results = { meta: {}, briefs: [], warnings: [], order: [], launch: {}, env: {}, failures: [], contributions: [] };
   const envOwners = new Map();
   const envDeclarations = new Map((resolved.capabilities || []).map((cap) => [cap.id, { names: new Set(cap.environment || []), namespaces: [...(cap.environmentNamespaces || [])] }]));
@@ -4634,6 +4638,7 @@ export function runLifecycleHooks(event, { home, instance, agentName, soulDir, c
     if (cap.executable && !cap.trust?.trusted) results.warnings.push(`${cap.id}: executable surface disabled — ${cap.trust?.reason || "not trusted"}`);
     const cmd = cap.hooks?.[event];
     if (!cmd) continue;
+    assertRoots?.();
     results.order.push(cap.id);
     try {
       const stdout = execSync(cmd, {
@@ -4651,6 +4656,10 @@ export function runLifecycleHooks(event, { home, instance, agentName, soulDir, c
           OATS_SOUL: soulDir || "", OATS_CONTEXT: contextDir, OATS_WORKSPACE: workspaceDir || "", OATS_LEVEL: cap.level || "",
           OATS_TEAM_NAME: resolved.team?.name || "", OATS_TEAM_ID: resolved.team?.id || "", OATS_TEAM_SCOPE: resolved.team?.scope || "",
           ...extraEnv,
+          // Hooks also run through direct core callers (not only bin/oats).
+          // Author this from the running kernel, never PATH, ambient env or
+          // a caller's extraEnv: those may point at a different executable.
+          OATS_CLI_BIN: realpathSync(join(PKG_ROOT, "bin", "oats.mjs")),
           OATS_SETTINGS: JSON.stringify(cap.settings || {}),
           OATS_META: JSON.stringify(priorMeta[cap.id] || {}),
         },
@@ -4710,6 +4719,8 @@ export function runLifecycleHooks(event, { home, instance, agentName, soulDir, c
       // to DETECT hook failures, not just print them (warnings are advisory).
       const required = (cap.requiredHooks || []).includes(event);
       results.failures.push({ capability: cap.id, event, message: detail, required });
+    } finally {
+      assertRoots?.(); // even a failing hook may have exchanged its cwd
     }
   }
   return results;
@@ -4899,6 +4910,18 @@ export function resolveRepo(root, repo) {
   return abs;
 }
 
+/** Only explicit directory execution relaxes the Git requirement. `repo` is
+ * still the config/deployment context, never a directory we take ownership of. */
+function resolveExecutionContext(root, target, work) {
+  if (work !== "directory") return resolveRepo(root, target);
+  if (target !== undefined && (typeof target !== "string" || !target.trim() || target.includes("\0"))) {
+    throw oatsError("E_BAD_ARGS", "directory mode repo must name an existing context directory");
+  }
+  const context = target === undefined ? workspaceOf(root) : resolve(workspaceOf(root), target);
+  if (!existsSync(context) || !statSync(context).isDirectory()) throw oatsError("E_BAD_ARGS", `directory mode context is not a directory: ${context}`);
+  return resolve(context);
+}
+
 // ---------- OKF (Open Knowledge Format) helpers ----------
 export function todayISO() { return new Date().toISOString().slice(0, 10); }
 
@@ -4996,7 +5019,7 @@ export function writeSoul(root, { name, kind, repo, work, runtime, model, yolo,
   // The committed soul remains canonical and config-independent. Composition happens in instances.
   const claudeMd = join(soulDir, "CLAUDE.md");
   try { lstatSync(claudeMd); } catch { symlinkSync("AGENTS.md", claudeMd); }
-  const ctx = repo ? resolveRepo(root, repo) : (defaultRepo(root) || workspaceOf(root));
+  const ctx = work === "directory" ? resolveExecutionContext(root, repo, work) : repo ? resolveRepo(root, repo) : (defaultRepo(root) || workspaceOf(root));
   const resolved = resolveOatsConfig(ctx, name);
   runSoulScaffoldHooks({
     home: soulDir, instance: name, agentName: name, soulDir,
@@ -5020,7 +5043,7 @@ export function createAgent(root, o) {
   const name = slug(o.name);
   if (RESERVED.has(name)) throw new Error(`"${name}" is a reserved name`);
   if (findAgent(root, name)) throw new Error(`agent "${name}" already exists`);
-  if (o.repo) resolveRepo(root, o.repo);
+  if (o.repo !== undefined) resolveExecutionContext(root, o.repo, o.work);
   // kind: "local" → a FULL soul (memory, skills, instances) under the scope's
   // local-agents/ — uncommitted by contract; otherwise a committed persistent soul.
   const kind = o.local || o.kind === "local" ? "local" : "persistent";
@@ -5446,6 +5469,18 @@ export function renderLaunchRecipe(recipe, { home, instance, redact = false }) {
   return `OATS_INSTANCE=${shq(instance)} OATS_INSTANCE_HOME=${shq(home)} PI_AGENT_INSTANCE=${shq(instance)} PI_AGENT_HOME=${shq(home)}${envTokens.length ? ` ${envTokens.join(" ")}` : ""} ${cmdline}`;
 }
 
+/** Execution, not preview: mark pending before dispatch, then resolve native
+ * storage inside the backend shell under the actual command environment.
+ * The original executable/argv is exec'd unchanged after recording succeeds. */
+function nativeRecordCommand(command, home, runtime) {
+  const { tokens, binary } = parseLaunchCommand(command);
+  const args = tokens.slice(binary + 1).filter(t => t.kind !== "prompt").map(t => t.value ?? t.text);
+  const id = prepareNativeStart(home, runtime);
+  const recorder = join(PKG_ROOT, "packages", "record", "bin", "record-native-start.mjs");
+  const inner = `${shq(process.execPath)} ${shq(recorder)} ${shq(home)} ${shq(id)} ${shq(runtime)} ${shq(JSON.stringify(args))} && exec ${tokens.slice(binary).map(t => t.text).join(" ")}`;
+  return `${tokens.slice(0, binary).map(t => t.text).join(" ")} /bin/sh -c ${shq(inner)}`;
+}
+
 /** A recorded recipe this kernel understands, or a refusal before anything
  *  is observed or stopped. */
 export function assertLaunchRecipe(recipe, what) {
@@ -5481,7 +5516,8 @@ function requirementsWithArgsMessage(runtime, providers, config) {
  *  collects every failed check into `preflight` instead of throwing. A home
  *  that predates recipes is not planned here (E_LAUNCH_LEGACY): its frozen
  *  command is described as is, and converted only by restart. */
-export function planLaunch({ home, instance, meta, contextDir, agentLike, selection = {}, launchConfigs, resolvedCfg, env = process.env, preview = false }) {
+export function planLaunch({ home, instance, meta, contextDir, agentLike, selection = {}, launchConfigs, resolvedCfg, env = process.env, preview = false, assertRoots }) {
+  assertRoots?.();
   const problems = [];
   const fail = (check, code, detail) => { if (!preview) throw oatsError(code, detail); problems.push({ check, ok: false, detail, code }); };
   // A recorded recipe is validated before anything is observed; a home that
@@ -5507,7 +5543,7 @@ export function planLaunch({ home, instance, meta, contextDir, agentLike, select
     // every capability that gave runtime-specific ones; recorded arguments
     // of a capability the scope no longer trusts are not reused.
     try {
-      hooks = prepareLaunchHooks({ frozen, runtime, resolvedCfg, home, meta, contextDir });
+      hooks = prepareLaunchHooks({ frozen, runtime, resolvedCfg, home, meta, contextDir, assertRoots });
       const current = new Map((resolvedCfg?.capabilities || []).map((c) => [c.id, c]));
       const untrusted = hooks.contributions.filter((c) => c.capability && current.has(c.capability) && !current.get(c.capability).trust?.trusted).map((c) => c.capability);
       const inactive = hooks.contributions.filter((c) => c.capability && !current.has(c.capability)).map((c) => c.capability);
@@ -5605,6 +5641,9 @@ export function redactLaunchRecipe(recipe) {
 export function spawnInstance(root, agent, o = {}) {
   const work = o.work || agent.work || "checkout";
   if (!WORK_MODES.includes(work)) throw new Error(`unknown work mode "${work}" (${WORK_MODES.join("|")})`);
+  if (work === "directory" && (o.workDir !== undefined || o.branch !== undefined)) {
+    throw oatsError("E_BAD_ARGS", "directory mode owns only <home>/work; workDir/--work-dir and branch/--branch are not allowed");
+  }
   if (work === "attached" && !o.workDir) throw new Error(`attached mode needs workDir — the owning instance's work tree (its <home>/work)`);
   if (o.task !== undefined && typeof o.task !== "string") throw new Error(`task must be a string (got ${typeof o.task}) — a flag parser handing --task's next flag through shows up here`);
   if (o.launchConfig !== undefined && (typeof o.launchConfig !== "string" || !o.launchConfig.trim())) throw oatsError("E_BAD_ARGS", "launchConfig must be a configuration name or none");
@@ -5613,7 +5652,7 @@ export function spawnInstance(root, agent, o = {}) {
   if (!["tmux", "herdr"].includes(backend)) throw new Error(`unknown session backend "${backend}" (tmux|herdr)`);
   if (o.herdrSocket !== undefined && (typeof o.herdrSocket !== "string" || !o.herdrSocket)) throw oatsError("E_BAD_ARGS", "herdrSocket must be a socket path");
   const launch = o.launch !== false;
-  const repoAbs = resolveRepo(root, o.repo || agent.repo);
+  const repoAbs = resolveExecutionContext(root, work === "directory" ? (o.repo !== undefined ? o.repo : agent.repo) : (o.repo || agent.repo), work);
   if (!repoAbs) throw new Error(`agent "${agent.name}" has no repo configured — pass one`);
   // Launch selection: a named configuration (explicit, or the soul's
   // launch-config default), or none; the runtime and model follow from it.
@@ -5950,6 +5989,7 @@ export function spawnInstance(root, agent, o = {}) {
   const herdrBase = launch && backend === "herdr" ? ensureHerdr({ binary: which("herdr"), socket: o.herdrSocket }) : undefined;
   const task = o.task ?? (o.taskFile ? readFileSync(o.taskFile, "utf8") : "");
 
+  if (existsSync(directoryRollbackPath(homeReal))) throw oatsError("E_WORK_INSPECTION_FAILED", `directory cleanup is still owed for ${home}; restore and retire the retained home before reusing its name`);
   mkdirSync(home, { recursive: true });
   // TOCTOU: the placement checks above ran BEFORE composition and the runtime
   // package preflight, both of which shell out — a window in which anything able
@@ -5967,6 +6007,8 @@ export function spawnInstance(root, agent, o = {}) {
     throw oatsError("E_NO_CANONICAL_ROOT", `instance home ${home} was created at ${createdReal}, not at ${expectedHome} — the path changed after it was validated (a swapped instances/ link), so nothing has been written into it and the spawn is aborted`);
   }
 
+  initializeNativeHistory(home);
+
   // Body: the soul is linked for reference, while instructions are a generated instance-local view.
   symlinkSync(soulDir, join(home, "soul"));
   writeFileSync(join(home, "AGENTS.md"), composition.text);
@@ -6092,6 +6134,9 @@ export function spawnInstance(root, agent, o = {}) {
       const note = incomplete.length ? ` — rollback INCOMPLETE — clean up manually: ${incomplete.join("; ")}` : "";
       throw new Error(`git worktree add/canonicalization failed: ${original}${note}`);
     }
+  } else if (work === "directory") {
+    // An owned execution directory, not a link to the source or a fake Git repo.
+    mkdirSync(join(home, "work"));
   } else if (work === "attached") {
     // Attach to ANOTHER instance's work tree (o.workDir): sibling home, shared tree.
     // The tree belongs to its owner — retire never removes it (work/ is a symlink).
@@ -6122,12 +6167,19 @@ export function spawnInstance(root, agent, o = {}) {
     catch (e) { warnings.push(`worktree setup command failed (continuing): ${String(e.message || e).slice(0, 200)}`); }
   }
 
+  // Establish directory ownership while these are still the kernel's own roots.
+  // A hook may replace either path; it must never mint authority for that target.
+  if (work === "directory") {
+    assertDirectoryRoots(home, homeReal);
+    writeRetirementBaseline(home, join(home, "work"), work, wm, resolvedCfg.capabilities, { launched: false });
+  }
+
   // Capability lifecycle hooks (spawn) — the knowledge integration scaffolds instance
   // memory (STATE.md/log.md/notes/ are OKF conventions, not kernel ones); the
   // messaging integration mints the comms identity. Kernel stays memory-agnostic.
   const hookRes = runLifecycleHooks("spawn", {
     home, instance, agentName: agent.name, soulDir, contextDir: repoAbs,
-    workspaceDir: workspaceOf(root), resolved: resolvedCfg,
+    workspaceDir: workspaceOf(root), rootDir: root, resolved: resolvedCfg,
     extraEnv: { OATS_TASK: task, OATS_REPO: repoAbs, OATS_BRANCH: branch || "", OATS_WORK: work, OATS_RUNTIME: runtime, OATS_KIND: agent.kind || "persistent" },
   });
   warnings.push(...hookRes.warnings);
@@ -6162,7 +6214,7 @@ export function spawnInstance(root, agent, o = {}) {
         if (work === "worktree") { outstandingGit.add("worktree"); if (branch) outstandingGit.add("branch"); }
         return quarantineInstanceHome({ home, instance, agent, incomplete, failed, outstandingHooks, outstandingGit,
           repoAbs, work, branch, resolvedCfg, hookMeta: hookRes.meta || {},
-          launched: true, sessionTarget: spawnHerdr, recordRetirementBaseline: true });
+          launched: true, sessionTarget: spawnHerdr, directoryHome: homeReal, recordRetirementBaseline: true });
       }
     }
     if (windowMayExist && backend === "herdr" && !spawnHerdr) {
@@ -6186,11 +6238,44 @@ export function spawnInstance(root, agent, o = {}) {
         return quarantineInstanceHome({
           home, instance, agent, incomplete, failed, outstandingHooks, outstandingGit,
           repoAbs, work, branch, resolvedCfg, hookMeta: hookRes.meta || {},
-          launched: true, tmux: spawnTmux, recordRetirementBaseline: true,
+          launched: true, tmux: spawnTmux, directoryHome: homeReal, recordRetirementBaseline: true,
         });
       }
     }
+    // Once hooks ran, directory execution may already hold authored results.
+    // Preserve before compensation and again afterwards, just like retirement.
+    // Failure to copy retains the home, never converts a failed spawn into loss.
+    const directoryRecoveries = [];
+    let lastDirectoryFingerprint;
     let compensationMeta = {};
+    const retainDirectory = (error) => {
+      incomplete.push(`directory preservation: ${error.message}`);
+      // No successful copy means no destructive cleanup. Even after a partial
+      // compensation pass, retry with the ORIGINAL spawn receipt, not its report.
+      for (const cap of resolvedCfg.capabilities) {
+        if (cap.hooks?.retire || (hookRes.order?.includes(cap.id) && hookRes.meta?.[cap.id])) outstandingHooks.add(cap.id);
+      }
+      const note = quarantineInstanceHome({
+        home, instance, agent, incomplete, failed, outstandingHooks, outstandingGit,
+        repoAbs, work, branch, resolvedCfg, hookMeta: hookRes.meta || {}, compensationMeta,
+        launched: false, directoryPreservation: true, directoryHome: homeReal,
+        recordRetirementBaseline: true,
+      });
+      return `${note}${directoryRecoveries.length ? `; prior work recovery: ${directoryRecoveries.join(", ")}` : ""}`;
+    };
+    const preserveDirectory = () => {
+      if (work !== "directory") return;
+      assertDirectoryRoots(home, homeReal);
+      const path = join(home, "work");
+      if (!readdirSync(path).length) return;
+      const directoryFingerprint = fingerprintTree(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);
+      lastDirectoryFingerprint = directoryFingerprint;
+    };
+    try { preserveDirectory(); }
+    catch (e) { return retainDirectory(e); }
     try {
       const comp = runLifecycleHooks("retire", {
         home, instance, agentName: agent.name, soulDir, contextDir: repoAbs,
@@ -6244,6 +6329,8 @@ export function spawnInstance(root, agent, o = {}) {
       incomplete.push(`${cap.id}: its spawn hook reported state it created, but the capability declares no retire hook, so OATS cannot undo it`);
       outstandingHooks.add(cap.id);
     }
+    try { preserveDirectory(); }
+    catch (e) { return retainDirectory(e); }
     let note;
     if (outstandingHooks.size || outstandingGit.size) {
       // Preserve credentials and the original hook receipt until cleanup
@@ -6253,14 +6340,14 @@ export function spawnInstance(root, agent, o = {}) {
         failed,
         outstandingHooks, outstandingGit, repoAbs, work, branch, resolvedCfg,
         hookMeta: hookRes.meta || {}, compensationMeta, launched: false,
-        recordRetirementBaseline: true,
+        directoryHome: homeReal, recordRetirementBaseline: true,
       });
     } else {
       try { rmSync(home, { recursive: true, force: true }); } catch (e2) { incomplete.push(`instance home ${home}: ${e2.message}`); }
       if (existsSync(home) && !incomplete.some((m) => m.startsWith("instance home"))) incomplete.push(`instance home ${home}: still present`);
       note = incomplete.length ? ` — rollback INCOMPLETE, clean up manually: ${incomplete.join("; ")}` : " — spawn rolled back";
     }
-    return note;
+    return `${note}${directoryRecoveries.length ? `; directory work preserved at ${directoryRecoveries.join(", ")}` : ""}`;
   };
 
   try {
@@ -6269,6 +6356,9 @@ export function spawnInstance(root, agent, o = {}) {
       const code = requiredFailures.some((f) => f.contract === "environment") ? "E_HOOK_ENVIRONMENT_CONTRACT" : "E_REQUIRED_HOOK_FAILED";
       throw oatsError(code, `a capability this soul activates could not configure itself:\n${detail}\n\nThe instance would have started with an invalid or missing capability configuration`);
     }
+    // Hooks have finished, but no TASK, launch recipe, successful scaffold, or
+    // backend operation may be published until the owned roots are revalidated.
+    if (work === "directory") assertDirectoryRoots(home, homeReal);
     {
       const owned = Object.keys(launchConfig?.env || {}).filter((n) => Object.hasOwn(hookRes.env, n));
       if (owned.length) {
@@ -6281,6 +6371,8 @@ export function spawnInstance(root, agent, o = {}) {
       ? `a dedicated git worktree of ${repoAbs} on branch "${branch}" — commit freely there`
       : work === "attached"
       ? `ATTACHED to another instance's work tree (${o.workDir}, branch ${branch}) — you share it with that instance; make your changes and commits focused, and never switch branches`
+      : work === "directory"
+      ? `an instance-owned execution directory — not a Git worktree or a link to ${repoAbs}; that path supplies configuration only`
       : work === "workspace"
       ? `the WHOLE WORKSPACE (${realpathSync(join(home, "work"))}) — every member repo is read-context; you coordinate, you do not edit member repos (see your work-mode briefing)`
       : `a symlink to the ${repoAbs} checkout — you share it; work on the currently checked-out branch (${branch}) and do not switch branches without being asked`;
@@ -6377,14 +6469,16 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
     const spawnWarnings = warnings;
 
     spawnTmux = meta.tmux;
+    if (work === "directory") assertDirectoryRoots(home, homeReal);
+    const executionCommand = launch ? nativeRecordCommand(cmdline, home, runtime) : null;
     if (launch && backend === "herdr") {
       windowMayExist = true;
       spawnHerdr = allocateHerdr(herdrBase, { home, instance });
       meta.sessionTarget = spawnHerdr;
       meta.launched = true;
       writeFileSync(join(home, "instance.json"), JSON.stringify(meta, null, 2) + "\n");
-      writeRetirementBaseline(home, join(home, "work"), work === "worktree", wm, resolvedCfg.capabilities, { launched: true, sessionTarget: spawnHerdr });
-      try { launchHerdr(spawnHerdr, `${launchEnvExports(recipe, process.env)}${cmdline}`); }
+      writeRetirementBaseline(home, join(home, "work"), work, wm, resolvedCfg.capabilities, { launched: true, sessionTarget: spawnHerdr });
+      try { launchHerdr(spawnHerdr, `${launchEnvExports(recipe, process.env)}${executionCommand}`); }
       catch (e) { throw oatsError("E_SPAWN_LAUNCH_FAILED", `Herdr could not run the launch command for ${instance} (${e.code === "ENOENT" ? "herdr unavailable" : "pane run failed"}); the command line is withheld from this message`); }
     } else if (launch) {
       if (!tmuxAlive(session)) {
@@ -6399,17 +6493,17 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
       // Commit the final child metadata and its independent byte authority before
       // the managed runtime can write. No child-home transition follows launch.
       writeFileSync(join(home, "instance.json"), JSON.stringify(meta, null, 2) + "\n");
-      writeRetirementBaseline(home, join(home, "work"), work === "worktree", wm, resolvedCfg.capabilities, { launched: true, tmux: meta.tmux });
+      writeRetirementBaseline(home, join(home, "work"), work, wm, resolvedCfg.capabilities, { launched: true, tmux: meta.tmux });
       // Wrap the command so the window drops into an interactive shell when the
       // agent exits (e.g. Ctrl-C) instead of tmux killing the window.
-      const windowCmd = `${cmdline}; exec "\${SHELL:-/bin/zsh}"`;
+      const windowCmd = `${executionCommand}; exec "\${SHELL:-/bin/zsh}"`;
       windowMayExist = true;
       try { sh(`tmux new-window -t ${shq(session)} -n ${shq(instance)} -c ${shq(home)}${launchEnvTmuxFlags(recipe, process.env)} ${shq(windowCmd)}`); }
       catch (e) { throw oatsError("E_SPAWN_LAUNCH_FAILED", `tmux new-window failed for ${instance} (${e.code === "ENOENT" ? "tmux unavailable" : "the window command was refused"}); the command line and tmux's output are withheld from this message because they can carry reference values; run tmux list-windows on the session to inspect`); }
     } else {
       meta.launched = false;
       writeFileSync(join(home, "instance.json"), JSON.stringify(meta, null, 2) + "\n");
-      writeRetirementBaseline(home, join(home, "work"), work === "worktree", wm, resolvedCfg.capabilities, { launched: false, tmux: meta.tmux });
+      writeRetirementBaseline(home, join(home, "work"), work, wm, resolvedCfg.capabilities, { launched: false, tmux: meta.tmux });
     }
 
     // parent relation: re-point the ANCHOR's recorded lineage so its parent is
@@ -6466,7 +6560,8 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION) {
           : { instance: e.name, home };
         // A home retained by an incomplete rollback is NOT a live instance: it
         // is preserved state awaiting cleanup, and must read that way.
-        const quarantine = join(home, ".oats-rollback-incomplete.json");
+        const fallback = directoryRollbackPath(home);
+        const quarantine = existsSync(fallback) ? fallback : join(home, ".oats-rollback-incomplete.json");
         let rollbackIncomplete;
         if (existsSync(quarantine)) {
           try { rollbackIncomplete = JSON.parse(readFileSync(quarantine, "utf8")); }
@@ -6601,11 +6696,63 @@ export const QUARANTINE_CLEANUP_VERSION = 1;
 /** The rollback-owned Git steps a quarantine can still owe. */
 export const QUARANTINE_GIT_DEBT = ["worktree", "branch"];
 
+// A substituted/missing home cannot hold its own receipt. This sibling fallback
+// is independent of both home bytes and the recovery storage that may have failed.
+function directoryRollbackPath(home) {
+  return join(dirname(home), `.oats-directory-rollback-${basename(home)}.json`);
+}
+
+function assertDirectoryHome(home, canonicalHome = realPathOrNearest(home)) {
+  let st;
+  try { st = lstatSync(home); } catch { /* fail closed below */ }
+  if (!st?.isDirectory() || st.isSymbolicLink() || realpathSync(home) !== canonicalHome) {
+    throw oatsError("E_WORK_INSPECTION_FAILED", `directory instance home was removed or exchanged: ${home}; restore the owned home before retrying cleanup`);
+  }
+}
+
+function assertDirectoryRoots(home, canonicalHome) {
+  assertDirectoryHome(home, canonicalHome);
+  const work = join(home, "work");
+  let st;
+  try { st = lstatSync(work); } catch { /* fail closed below */ }
+  if (!st?.isDirectory() || st.isSymbolicLink()) {
+    throw oatsError("E_WORK_INSPECTION_FAILED", `directory work must remain an owned directory, not missing, a link or another filesystem type: ${work}; restore the owned work root before retrying cleanup`);
+  }
+}
+
+function directoryIdentity(path) {
+  const st = lstatSync(path);
+  return { dev: st.dev, ino: st.ino };
+}
+
+// Read independently of mutable instance bytes, BEFORE realpath(home), hooks,
+// lock creation or backend observation. A metadata mode edit cannot disable it.
+function sessionDirectoryGuard(home) {
+  let baseline;
+  try { baseline = JSON.parse(readFileSync(retirementBaselinePath(home), "utf8")); }
+  catch (e) { if (e.code === "ENOENT") return () => {}; throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", "independent session receipt is unreadable"); }
+  const expected = join(realPathOrNearest(dirname(home)), basename(home));
+  const check = () => {
+    if (baseline.directoryWork === true) {
+      if (baseline.version !== RETIRE_BASELINE_VERSION || baseline.home !== expected) throw oatsError("E_WORK_INSPECTION_FAILED", "invalid independent directory home authority");
+      assertDirectoryRoots(home, expected);
+      for (const [name, path] of [["home", home], ["work", join(home, "work")]]) {
+        const actual = directoryIdentity(path), recorded = baseline.directoryRoots?.[name];
+        if (!recorded || actual.dev !== recorded.dev || actual.ino !== recorded.ino) throw oatsError("E_WORK_INSPECTION_FAILED", `directory ${name} was exchanged; restore the owned root before retrying start`);
+      }
+    }
+    let meta;
+    try { meta = JSON.parse(readFileSync(join(home, "instance.json"), "utf8")); } catch { return; } // ordinary receipt validation reports this
+    if ((meta.work === "directory") !== (baseline.directoryWork === true)) throw oatsError("E_WORK_INSPECTION_FAILED", "directory work mode disagrees with independent session authority");
+  };
+  check();
+  return check;
+}
+
 /** Retain the home and its cleanup receipt when spawn compensation or retirement
  * cannot finish. Keeping the original credentials makes cleanup retryable. */
-function quarantineInstanceHome({ home, instance, agent, incomplete, failed, outstandingHooks, outstandingGit, repoAbs, work, branch, resolvedCfg, hookMeta, compensationMeta, launched, tmux, sessionTarget, recordRetirementBaseline = false, reason }) {
-  try {
-    writeFileSync(join(home, ".oats-rollback-incomplete.json"), JSON.stringify({
+function quarantineInstanceHome({ home, instance, agent, incomplete, failed, outstandingHooks, outstandingGit, repoAbs, work, branch, resolvedCfg, hookMeta, compensationMeta, launched, tmux, sessionTarget, recordRetirementBaseline = false, reason, directoryPreservation = false, directoryHome = realPathOrNearest(home) }) {
+  const marker = {
       // `reason` is optional and DEFAULTS to the spawn wording, so every existing
       // caller is byte-identical; only a caller that supplies one differs. The
       // quarantine shape is now reached from two events and a fixed "spawn"
@@ -6620,7 +6767,7 @@ function quarantineInstanceHome({ home, instance, agent, incomplete, failed, out
         version: QUARANTINE_CLEANUP_VERSION,
         repo: repoAbs, work, branch, launched, tmux,
         ...(sessionTarget ? { sessionTarget } : {}),
-        outstanding: { hooks: [...outstandingHooks], git: [...outstandingGit] },
+        outstanding: { hooks: [...outstandingHooks], git: [...outstandingGit], ...(directoryPreservation ? { directory: true } : {}) },
         capabilityRuntime: (resolvedCfg.capabilities || []).map((cap) => ({
           id: cap.id, layer: cap.layer, level: cap.level, settings: cap.settings,
           hooks: cap.hooks, requiredHooks: cap.requiredHooks, environment: cap.environment, environmentNamespaces: cap.environmentNamespaces,
@@ -6630,11 +6777,30 @@ function quarantineInstanceHome({ home, instance, agent, incomplete, failed, out
         capabilityMeta: hookMeta || {},
       },
       createdAt: new Date().toISOString(),
-    }, null, 2) + "\n");
-  } catch { /* the quarantine still stands without its marker */ }
+  };
+  try {
+    const path = join(home, ".oats-rollback-incomplete.json");
+    if (work === "directory") {
+      assertDirectoryHome(home, directoryHome);
+      writeJsonAtomic(path, marker, 0o600);
+    } else writeFileSync(path, JSON.stringify(marker, null, 2) + "\n");
+  } catch {
+    if (work === "directory") {
+      // Never write through a substituted home (even its metadata paths).
+      // The original parent is outside the disposable home; no recovery copy is
+      // needed to retain the frozen hook inputs and the cleanup obligations.
+      try {
+        const path = directoryRollbackPath(directoryHome);
+        if (realpathSync(dirname(path)) !== dirname(path)) throw new Error("directory cleanup parent was redirected; refusing to write through it");
+        writeJsonAtomic(path, marker, 0o600);
+        incomplete.push(`cleanup descriptor retained at ${path}; restore the home before retrying`);
+      } catch (fallbackError) { incomplete.push(`cleanup descriptor could not be stored: ${fallbackError.message}`); }
+    }
+  }
   if (recordRetirementBaseline) {
     try {
-      writeRetirementBaseline(home, join(home, "work"), work === "worktree", resolveWorkMode(repoAbs, work), resolvedCfg.capabilities || [], { launched: launched === true, tmux, sessionTarget });
+      if (work === "directory") assertDirectoryRoots(home, directoryHome);
+      writeRetirementBaseline(home, join(home, "work"), work, resolveWorkMode(repoAbs, work), resolvedCfg.capabilities || [], { launched: launched === true, tmux, sessionTarget });
     } catch (e) {
       incomplete.push(`independent retirement authority: ${e.message}`);
     }
@@ -6670,7 +6836,9 @@ function usableCleanupDescriptor(marker) {
   if (c.work === "worktree" && !nonEmptyString(c.branch)) return false;
   if (c.branch !== undefined && !nonEmptyString(c.branch)) return false;
   if (c.capabilityMeta !== undefined && !isPlainObject(c.capabilityMeta)) return false;
-  if (!Array.isArray(c.capabilityRuntime) || !c.capabilityRuntime.length) return false;
+  const directoryDebt = c.outstanding?.directory === true && c.work === "directory";
+  if (c.outstanding?.directory !== undefined && !directoryDebt) return false;
+  if (!Array.isArray(c.capabilityRuntime) || (!c.capabilityRuntime.length && !directoryDebt)) return false;
   if (!c.capabilityRuntime.every((cap) => isPlainObject(cap) && nonEmptyString(cap.id))) return false;
   if (!isPlainObject(c.outstanding) || !Array.isArray(c.outstanding.hooks) || !Array.isArray(c.outstanding.git)) return false;
   if (!c.outstanding.hooks.every(nonEmptyString)) return false;
@@ -6679,10 +6847,10 @@ function usableCleanupDescriptor(marker) {
   // other work mode describes a quarantine that could not have happened.
   if (c.outstanding.git.length && c.work !== "worktree") return false;
   // The decisive invariant: a quarantine with NOTHING outstanding is a proof
-  // obligation of zero — the retry would run, prove nothing, and delete the home
-  // and its credential (reviewer-2baa631). The producer cannot emit it, so a
-  // marker claiming it is not one of ours.
-  if (!c.outstanding.hooks.length && !c.outstanding.git.length) return false;
+  // obligation of zero. Directory preservation is also real debt: the retry's
+  // independent-authority inspection and verified snapshots must succeed even
+  // when no capability has a retire hook. It is never a Git/shared-work escape.
+  if (!c.outstanding.hooks.length && !c.outstanding.git.length && !directoryDebt) return false;
   // The retry must be ABLE to rerun what it must prove: an outstanding hook whose
   // capability is not in the set could never run, so the quarantine would never
   // clear — and the home would be unremovable without --force.
@@ -6701,7 +6869,7 @@ function retirementStateRoot(home) {
 }
 
 function retirementKey(home) {
-  return createHash("sha256").update(realPathOrNearest(home)).digest("hex");
+  return createHash("sha256").update(join(realPathOrNearest(dirname(home)), basename(home))).digest("hex");
 }
 
 function retirementBaselinePath(home) {
@@ -6785,11 +6953,14 @@ function retirementDisposableRoots(work, workMode, capabilities) {
   return roots;
 }
 
-function writeRetirementBaseline(home, work, isWorktree, workMode, capabilities, runtime) {
+function writeRetirementBaseline(home, work, mode, workMode, capabilities, runtime) {
+  if (mode === "directory") assertDirectoryRoots(home);
+  const isWorktree = mode === "worktree";
   const status = isWorktree && existsSync(work) ? worktreeStatus(work) : "";
   const disposableReceipts = isWorktree ? retirementDisposableRoots(work, workMode, capabilities) : [];
   const baseline = {
     version: RETIRE_BASELINE_VERSION,
+    ...(mode === "directory" ? { directoryWork: true, directoryRoots: { home: directoryIdentity(home), work: directoryIdentity(work) } } : {}),
     home: realPathOrNearest(home),
     homeFingerprint: fingerprintTree(home, { excludeRoot: new Set(["work"]) }),
     disposableReceipts,
@@ -7172,7 +7343,7 @@ export function capturedProviders(meta, frozen) {
     return { id, contribution, binding, settings: contribution?.settings ?? binding?.settings ?? {} };
   });
 }
-export function prepareLaunchHooks({ frozen, runtime, resolvedCfg, home, meta, contextDir, extraEnv = {} }) {
+export function prepareLaunchHooks({ frozen, runtime, resolvedCfg, home, meta, contextDir, extraEnv = {}, assertRoots }) {
   const contributions = (frozen.hooks?.contributions || []).map((c) => ({ ...c }));
   const env = { ...(frozen.hooks?.env || {}) };
   const refreshed = [];
@@ -7194,7 +7365,7 @@ export function prepareLaunchHooks({ frozen, runtime, resolvedCfg, home, meta, c
     if (hooks.launch) withLaunchHook.push({ id: p.id, capability: p.id, manifest, layer: p.contribution?.layer ?? p.binding?.layer ?? manifest.layer ?? null, level: p.contribution?.level ?? p.binding?.level ?? null, settings: p.settings, hooks, trust, environment: [...(manifest.environment || [])], environmentNamespaces: [...(manifest.environmentNamespaces || [])], missingRequires: [] });
   }
   if (withLaunchHook.length) {
-    const res = runLifecycleHooks("launch", { home, instance: meta.instance, agentName: meta.agent, contextDir: ctx, rootDir: dirname(dirname(dirname(home))), resolved: { ...(resolvedCfg || {}), capabilities: withLaunchHook }, priorMeta: meta.capabilityMeta || {}, extraEnv: { OATS_RUNTIME: runtime, OATS_PREVIOUS_RUNTIME: frozen.runtime || "", ...extraEnv } });
+    const res = runLifecycleHooks("launch", { assertRoots, home, instance: meta.instance, agentName: meta.agent, contextDir: ctx, rootDir: dirname(dirname(dirname(home))), resolved: { ...(resolvedCfg || {}), capabilities: withLaunchHook }, priorMeta: meta.capabilityMeta || {}, extraEnv: { OATS_RUNTIME: runtime, OATS_PREVIOUS_RUNTIME: frozen.runtime || "", ...extraEnv } });
     const failed = (res.failures || []).map((f) => `${f.capability}: ${f.message}`);
     if (failed.length) throw oatsError("E_LAUNCH_PREPARATION", `a capability could not prepare the ${runtime} launch:\n  ${failed.join("\n  ")}`);
     // Ownership holds across retained AND refreshed contributions, as the
@@ -7263,7 +7434,15 @@ export function prepareLaunchHooks({ frozen, runtime, resolvedCfg, home, meta, c
 export function restartInstanceSession(home, o = {}) { return startInstanceSession(home, { ...o, restart: true }); }
 export function startInstanceSession(home, o = {}) {
   if (typeof home !== "string" || !isAbsolute(home)) throw oatsError("E_BAD_ARGS", "session start needs an absolute instance home");
+  // Check the sibling receipt BEFORE resolving a possibly substituted home.
+  if (existsSync(directoryRollbackPath(home))) throw oatsError("E_INSTANCE_RETIRING", `${home} has retained directory cleanup; restore and retire it before starting anything there`);
+  const checkRoots = sessionDirectoryGuard(home);
   const realHome = realPathOrNearest(home);
+  let originalHomeIdentity;
+  try { originalHomeIdentity = directoryIdentity(realHome); } catch { /* missing home reported below */ }
+  const rawIo = o.io;
+  const guardedExec = (...args) => { checkRoots(); return (rawIo?.exec || execFileSync)(...args); };
+  o = { ...o, io: { ...rawIo, exec: guardedExec, kill: (...args) => { checkRoots(); return (rawIo?.kill || process.kill)(...args); } } };
   const metaPath = join(realHome, "instance.json");
   if (!existsSync(metaPath)) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `${realHome} is not an OATS instance home (no instance.json); nothing was started`);
   const lock = join(realHome, ".oats-start.lock");
@@ -7282,6 +7461,7 @@ export function startInstanceSession(home, o = {}) {
   // mutable metadata; both tmp+rename. A failure between them is what the
   // pending receipt exists for.
   const record = (meta, { id, backend, target, model, command, startedAt, reused, launch, runtime: newRuntime, yolo: newYolo, stop }, clearPending = true) => {
+    checkRoots();
     const baselinePath = retirementBaselinePath(realHome);
     let baseline;
     try { baseline = JSON.parse(readFileSync(baselinePath, "utf8")); } catch (e) { throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `independent session receipt is missing or unreadable for ${realHome}: ${e.message}`); }
@@ -7333,6 +7513,7 @@ export function startInstanceSession(home, o = {}) {
       if (!validReceipt) throw oatsError("E_SESSION_UNKNOWN", `an earlier start left an unreadable or invalid receipt at ${pendingPath}; inspect it before retrying; nothing was started`);
       const pbackend = pending.target.backend === "herdr" ? "herdr" : "tmux";
       let st;
+      checkRoots();
       try { st = inspectSessionTarget(pending.target, o.io); }
       catch (e) {
         if (pbackend === "tmux" && lostTmuxServer(e)) st = { present: false, state: "stopped" };
@@ -7385,7 +7566,7 @@ export function startInstanceSession(home, o = {}) {
       const context = meta.repo && existsSync(meta.repo) ? resolve(meta.repo) : dirname(dirname(dirname(dirname(realHome))));
       const resolvedCfg = resolveOatsConfig(context, meta.agent);
       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 || { runtime: meta.runtime, model: meta.model, yolo: meta.yolo }, selection: { launchConfig: o.launchConfig, runtime: o.runtime, model: o.model, yolo: o.yolo }, resolvedCfg, env: o.env || process.env });
+      const plan = planLaunch({ home: realHome, instance: meta.instance, meta, contextDir: context, agentLike: agent || { runtime: meta.runtime, model: meta.model, yolo: meta.yolo }, selection: { launchConfig: o.launchConfig, runtime: o.runtime, model: o.model, yolo: o.yolo }, resolvedCfg, env: o.env || process.env, assertRoots: checkRoots });
       launchPlan = { recipe: plan.recipe, command: plan.command, runtime: plan.runtime, model: plan.model, yolo: plan.yolo };
       command = launchPlan.command; model = launchPlan.model;
     } else if (o.model !== undefined && o.model !== null && String(o.model).trim() !== "") {
@@ -7401,6 +7582,7 @@ export function startInstanceSession(home, o = {}) {
     const paneEnv = recipeForEnv ? launchEnvRefs(recipeForEnv, o.env || process.env) : [];
     const paneEnvFlags = paneEnv.flatMap((r) => ["-e", `${r.name}=${r.value}`]);
     const paneEnvExports = paneEnv.map((r) => `export ${r.name}=${shq(r.value)}; `).join("");
+    checkRoots(); // launch hooks/preparation have run; no backend has been observed
     const planExtra = launchPlan ? { launch: launchPlan.recipe, runtime: launchPlan.runtime, yolo: launchPlan.yolo } : {};
     let target = receipt.target;
     let state = { present: false, state: "not-launched" };
@@ -7426,7 +7608,9 @@ export function startInstanceSession(home, o = {}) {
     }
     const startedAt = new Date().toISOString();
     const id = randomUUID();
-    const completedCommand = `${command}; oats_start_status=$?; printf '%s\\n' ${shq(id)} > ${shq(exitedPath)}`;
+    checkRoots();
+    const executionCommand = nativeRecordCommand(command, realHome, launchPlan?.runtime || runtime);
+    const completedCommand = `${executionCommand}; oats_start_status=$?; printf '%s\\n' ${shq(id)} > ${shq(exitedPath)}`;
     let reused = "new";
     if (backend === "herdr") {
       if (!target) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `this never-launched Herdr home has no saved server endpoint; no tmux fallback was started`);
@@ -7437,6 +7621,7 @@ export function startInstanceSession(home, o = {}) {
         catch (e) { throw oatsError("E_SESSION_UNKNOWN", `Herdr server on ${base.socket} is not reachable, so nothing was started: ${e.message}`); }
         target = allocateHerdr(base, { home: realHome, instance: meta.instance }, o.io);
       }
+      checkRoots();
       writeJsonAtomic(pendingPath, { id, target, command, model: model ?? null, startedAt, ...planExtra }, 0o600);
       try { launchHerdr(target, `${paneEnvExports}cd ${shq(realHome)} && ${completedCommand}; exit "$oats_start_status"`, o.io); }
       catch (e) { throw launchFailure("Herdr", e); }
@@ -7449,6 +7634,7 @@ export function startInstanceSession(home, o = {}) {
       // the agent's own pane: the command runs there, no other window touched.
       const inPlace = state.paneId && (state.present || state.state === "stopped");
       if (inPlace) {
+        checkRoots();
         writeJsonAtomic(pendingPath, { id, target, command, model: model ?? null, startedAt, ...planExtra }, 0o600);
         try { tmuxOn(socket, ["respawn-pane", "-k", "-t", state.paneId, "-c", realHome, ...paneEnvFlags, windowCmd], o.io); }
         catch (e) { throw launchFailure("tmux", e); }
@@ -7456,14 +7642,20 @@ export function startInstanceSession(home, o = {}) {
       } else {
         const instancesRoot = dirname(realHome);
         const hq = existsSync(dirname(dirname(instancesRoot))) ? dirname(dirname(instancesRoot)) : realHome;
+        checkRoots();
         if (!socket) {
           // Never launched (--no-launch): the default server, as spawn uses.
-          if (!tmuxAlive(session)) {
-            sh(`tmux new-session -d -s ${shq(session)} -n hq -c ${shq(hq)}`);
-            shTry(`tmux set-option -t ${shq(session)} -g window-size latest`);
-            shTry(`tmux set-option -t ${shq(session)} -g aggressive-resize on`);
+          const defaultTmux = args => guardedExec("tmux", args, { encoding: "utf8", timeout: 10000, stdio: ["ignore", "pipe", "pipe"] }).trim();
+          let alive = false;
+          try { defaultTmux(["has-session", "-t", session]); alive = true; } catch (e) { checkRoots(); }
+          if (!alive) {
+            defaultTmux(["new-session", "-d", "-s", session, "-n", "hq", "-c", hq]);
+            for (const option of [["window-size", "latest"], ["aggressive-resize", "on"]]) {
+              try { defaultTmux(["set-option", "-t", session, "-g", ...option]); } catch (e) { checkRoots(); }
+            }
           }
-          socket = tmuxSocket(session);
+          socket = defaultTmux(["display-message", "-p", "-t", session, "#{socket_path}"]);
+          if (!socket) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", "tmux did not report its socket");
         } else if (serverGone) {
           // The recorded server is gone (a reboot): the same socket path again.
           mkdirSync(dirname(socket), { recursive: true });
@@ -7479,6 +7671,7 @@ export function startInstanceSession(home, o = {}) {
         }
         if (names.includes(window)) throw oatsError("E_SESSION_RUNNING", `tmux window ${session}:${window} appeared on ${socket} during the start; nothing was started`);
         target = { backend: "tmux", session, window, socket: resolve(socket) };
+        checkRoots();
         writeJsonAtomic(pendingPath, { id, target, command, model: model ?? null, startedAt, ...planExtra }, 0o600);
         try { tmuxOn(socket, ["new-window", "-t", `=${session}:`, "-n", window, "-c", realHome, ...paneEnvFlags, windowCmd], o.io); }
         catch (e) { throw launchFailure("tmux", e); }
@@ -7494,11 +7687,17 @@ export function startInstanceSession(home, o = {}) {
       throw oatsError("E_SESSION_START_INCOMPLETE", `${meta.instance} was started (${backend === "herdr" ? `Herdr pane ${target.paneId}` : `tmux ${target.session}:${target.window} on ${target.socket}`}) but its metadata could not be recorded: ${e.message}; the actual target is kept in ${pendingPath} and the next start adopts it instead of allocating another`);
     }
   } finally {
-    rmSync(lock, { recursive: true, force: true });
+    // A hook may have replaced the home itself. Never follow that replacement
+    // to remove a target's lock; keep the original retry state with its home.
+    try {
+      const st = lstatSync(realHome);
+      if (st.isDirectory() && !st.isSymbolicLink() && st.dev === originalHomeIdentity?.dev && st.ino === originalHomeIdentity?.ino) rmSync(lock, { recursive: true, force: true });
+    } catch { /* retain retry state when its authority is lost */ }
   }
 }
 
-function inspectRetirementWork(home, work, isWorktree, { branchDeletion } = {}) {
+function inspectRetirementWork(home, work, isWorktree, { branchDeletion, directory = false } = {}) {
+  if (directory) assertDirectoryRoots(home);
   const classes = [];
   let baseline;
   const path = retirementBaselinePath(home);
@@ -7513,7 +7712,18 @@ function inspectRetirementWork(home, work, isWorktree, { branchDeletion } = {})
   } else if (baseline.homeFingerprint !== fingerprintTree(home, { excludeRoot: new Set(["work"]) })) {
     classes.push("changed instance-home bytes");
   }
-  const branchCommits = branchDeletion?.delete ? branchOnlyCommits(branchDeletion.repo, branchDeletion.branch) : undefined;
+  // A mutable mode must not turn owned directory bytes into an excluded shared
+  // tree (or authorize Git deletion). Require the independent spawn authority.
+  if (directory !== (baselineValid && baseline.directoryWork === true)) {
+    throw oatsError("E_WORK_INSPECTION_FAILED", "directory work mode disagrees with independent retirement authority");
+  }
+  let directoryFingerprint;
+  if (directory) {
+    directoryFingerprint = fingerprintTree(work);
+    // Never stamp hook-created or authored execution bytes as disposable.
+    if (readdirSync(work).length) classes.push("directory work bytes");
+  }
+  const branchCommits = !directory && branchDeletion?.delete ? branchOnlyCommits(branchDeletion.repo, branchDeletion.branch) : undefined;
   if (branchCommits?.length) classes.push("branch-only local commits");
   if (isWorktree && existsSync(work)) {
     const status = worktreeStatus(work);
@@ -7525,9 +7735,9 @@ function inspectRetirementWork(home, work, isWorktree, { branchDeletion } = {})
   }
   const stateFingerprint = createHash("sha256")
     .update(fingerprintTree(home, { excludeRoot: new Set(["work"]) }))
-    .update("\0").update(isWorktree && existsSync(work) ? worktreeStatus(work) : "")
+    .update("\0").update(directory ? (directoryFingerprint || "missing") : isWorktree && existsSync(work) ? worktreeStatus(work) : "")
     .digest("hex");
-  return { classes: [...new Set(classes)], home, work, stateFingerprint, branchExists: branchCommits !== null, runtimeAuthority: baselineValid ? runtimeAuthorityOf(baseline) : undefined };
+  return { classes: [...new Set(classes)], home, work, directory, directoryFingerprint, stateFingerprint, branchExists: branchCommits !== null, runtimeAuthority: baselineValid ? runtimeAuthorityOf(baseline) : undefined };
 }
 
 function copyRecoveryTree(src, dest, { excludeRoot = new Set() } = {}) {
@@ -7632,6 +7842,9 @@ function materializeNestedRepositories(sourceWork, recoveredRepo) {
 function preserveRetirementWork(observation, meta, instance) {
   const recoveryRoot = join(retirementStateRoot(observation.home), "recovery");
   mkdirSync(recoveryRoot, { recursive: true });
+  if (observation.directory && realpathSync(recoveryRoot) !== join(realpathSync(dirname(observation.home)), ".oats-retirement", "recovery")) {
+    throw oatsError("E_WORK_PRESERVATION_FAILED", "directory recovery storage was redirected; retain the source home rather than copying into an unowned or disposable location");
+  }
   const staging = mkdtempSync(join(recoveryRoot, `.${instance}-`));
   const recovery = join(recoveryRoot, basename(staging).slice(1));
   try {
@@ -7674,6 +7887,13 @@ function preserveRetirementWork(observation, meta, instance) {
       const sourceHead = execFileSync("git", ["-C", meta.repo, "rev-parse", `refs/heads/${meta.branch}`], { encoding: "utf8" , maxBuffer: GIT_MAX_BUFFER }).trim();
       if (recoveredHead !== sourceHead) throw new Error("recovery clone does not retain the instance branch tip");
     }
+    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");
+      }
+    }
     const repoCopy = homeOnly ? { copied: false, reason: "Only instance-home bytes changed; no work state requires a repository copy", source: meta.repo, branch: meta.branch } : undefined;
     writeFileSync(join(staging, "recovery.json"), JSON.stringify({ version: 1, instance, classes: observation.classes, sourceHome: observation.home, createdAt: new Date().toISOString(), ...(repoCopy ? { repoCopy } : {}) }, null, 2) + "\n", { mode: 0o600 });
     mkdirSync(dirname(recovery), { recursive: true });
@@ -7845,7 +8065,8 @@ export function retireInstance(root, name, o = {}) {
   // not finish) has no instance.json — it never got that far. Its marker carries
   // the cleanup descriptor in the same shape, so retire can rerun compensation
   // instead of silently skipping every hook and deleting the credentials.
-  const quarantinePath = join(found.home, ".oats-rollback-incomplete.json");
+  const directoryFallbackPath = directoryRollbackPath(found.home);
+  const quarantinePath = existsSync(directoryFallbackPath) ? directoryFallbackPath : join(found.home, ".oats-rollback-incomplete.json");
   let quarantine;
   let markerUnusable = false;
   // A marker means the home is quarantined, WHETHER OR NOT instance.json exists:
@@ -7892,8 +8113,9 @@ export function retireInstance(root, name, o = {}) {
   }
 
   const workPath = join(found.home, "work");
-  const isWorktree = meta.work === "worktree" ||
-    (existsSync(workPath) && !lstatSync(workPath).isSymbolicLink());
+  const directory = meta.work === "directory";
+  const isWorktree = !directory && (meta.work === "worktree" ||
+    (existsSync(workPath) && !lstatSync(workPath).isSymbolicLink()));
   // A live runtime cannot establish a stable final work inspection of itself,
   // so self-retire never inspects, runs hooks, or removes anything here. It
   // persists the intent and hands the whole retirement to a detached process
@@ -7905,7 +8127,7 @@ export function retireInstance(root, name, o = {}) {
   // First inspection is non-destructive. Only after it succeeds may OATS quiesce
   // the managed runtime; recovery copying never races a live managed Pi.
   const branchDeletion = { delete: !!(o.deleteBranch || quarantine), repo: meta.repo, branch: meta.branch };
-  const initialObservation = inspectRetirementWork(found.home, workPath, isWorktree, { branchDeletion });
+  const initialObservation = inspectRetirementWork(found.home, workPath, isWorktree, { branchDeletion, directory });
   // Runtime identity is destructive authority. The mutable child metadata may
   // describe it for humans, but only the independent baseline can authorize the
   // endpoint that proves quiescence.
@@ -7946,7 +8168,7 @@ export function retireInstance(root, name, o = {}) {
       if (!/no server running|failed to connect|can't find session|no sessions/i.test(detail)) throw oatsError("E_RUNTIME_QUIESCE_FAILED", `could not establish that ${runtimeSession}:${runtimeWindow} stopped on ${runtimeSocket}: ${detail || "tmux inspection failed"}`);
     }
   }
-  const stableObservation = inspectRetirementWork(found.home, workPath, isWorktree, { branchDeletion });
+  const stableObservation = inspectRetirementWork(found.home, workPath, isWorktree, { branchDeletion, directory });
   const workRecoveries = [];
   if (stableObservation.classes.length) workRecoveries.push(preserveRetirementWork(stableObservation, meta, name));
   let workRecovery = workRecoveries.at(-1);
@@ -7993,7 +8215,7 @@ export function retireInstance(root, name, o = {}) {
 
   // Hooks are allowed to mutate the inspected tree, so inspect again after
   // them and preserve a separately verified post-hook snapshot when needed.
-  const finalObservation = inspectRetirementWork(found.home, workPath, isWorktree, { branchDeletion });
+  const finalObservation = inspectRetirementWork(found.home, workPath, isWorktree, { branchDeletion, directory });
   if (finalObservation.classes.length && finalObservation.stateFingerprint !== stableObservation.stateFingerprint) {
     workRecoveries.push(preserveRetirementWork(finalObservation, meta, name));
     workRecovery = workRecoveries.at(-1);
@@ -8164,6 +8386,7 @@ export function retireInstance(root, name, o = {}) {
   const forced = !!(stillIncomplete && o.force);
   if (!o.keepDir && (!stillIncomplete || forced)) {
     rmSync(found.home, { recursive: true, force: true });
+    rmSync(directoryFallbackPath, { force: true });
     // The owed retirement is paid: clear the pending marker, and the failed
     // outcome an earlier deferred attempt may have left beside the home; a
     // deferred completion writes its own outcome after this returns.