@awebai/oats 0.22.17 → 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";
@@ -31,17 +31,19 @@ import {
   chmodSync, closeSync, copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, symlinkSync, writeFileSync,
 } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+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 } from "./herdr.mjs";
+import { ensureHerdr, allocateHerdr, launchHerdr, inspectHerdr, stopHerdr, validHerdrTarget, herdrSnapshot, herdrCommand } from "./herdr.mjs";
 
 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";
@@ -210,30 +212,106 @@ export function parseYamlFlat(text) {
 /** Small dependency-free YAML subset used by oats-config.yaml.
  * Supports nested maps, namespaced/quoted keys, booleans, numbers, and inline arrays/maps. */
 function yamlScalar(raw) {
-  const val = raw.trim().replace(/\s+#.*$/, "").trim();
+  const trimmed = raw.trim();
+  // A double-quoted scalar is read with JSON's escape rules (what the CLI
+  // writes for values with spaces, quotes or metacharacters); a single-quoted
+  // one with YAML's doubled-quote rule. A trailing comment never cuts a
+  // quoted value. Anything the escape rules refuse falls back to the raw text
+  // between the quotes, as before.
+  if (trimmed.startsWith('"')) {
+    let i = 1, esc = false;
+    for (; i < trimmed.length; i++) { const c = trimmed[i]; if (esc) esc = false; else if (c === "\\") esc = true; else if (c === '"') break; }
+    if (i < trimmed.length) { const q = trimmed.slice(0, i + 1); try { return JSON.parse(q); } catch { return q.slice(1, -1); } }
+  }
+  if (trimmed.startsWith("'")) {
+    let i = 1, out = "";
+    for (; i < trimmed.length; i++) { const c = trimmed[i]; if (c === "'") { if (trimmed[i + 1] === "'") { out += "'"; i++; continue; } break; } out += c; }
+    if (i < trimmed.length) return out;
+  }
+  // Inline collections are split quote- and nesting-aware, so an element
+  // may carry commas, "#" or nothing at all; a trailing comment after the
+  // closing bracket is dropped, one inside quotes is kept.
+  if (trimmed.startsWith("[") || trimmed.startsWith("{")) {
+    const close = inlineCollectionEnd(trimmed);
+    if (close > 0) {
+      const inner = trimmed.slice(1, close);
+      const parts = splitInline(inner);
+      if (trimmed[0] === "[") return parts.map((v) => yamlScalar(v));
+      const out = {};
+      for (const part of parts) {
+        const i = inlineKeyEnd(part);
+        if (i < 0) continue;
+        const key = yamlKey(part.slice(0, i).trim().replace(/^["']|["']$/g, ""));
+        out[key] = yamlScalar(part.slice(i + 1));
+      }
+      return out;
+    }
+  }
+  const val = trimmed.replace(/\s+#.*$/, "").trim();
   if (/^(true|false)$/i.test(val)) return val.toLowerCase() === "true";
   if (/^(null|~)$/i.test(val)) return null;
   if (/^-?\d+(\.\d+)?$/.test(val)) return Number(val);
-  if (val.startsWith("[") && val.endsWith("]")) {
-    return val.slice(1, -1).split(",").map((v) => yamlScalar(v)).filter((v) => v !== "");
-  }
-  if (val.startsWith("{") && val.endsWith("}")) {
-    const out = {};
-    for (const part of val.slice(1, -1).split(",")) {
-      const i = part.indexOf(":");
-      if (i < 0) continue;
-      const key = yamlKey(part.slice(0, i).trim().replace(/^["']|["']$/g, ""));
-      out[key] = yamlScalar(part.slice(i + 1));
-    }
-    return out;
-  }
   return val.replace(/^["']|["']$/g, "");
 }
+/** Index of the bracket closing the inline collection that opens `s`, or -1. */
+function inlineCollectionEnd(s) {
+  let depth = 0, quote = null;
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (quote) { if (c === "\\" && quote === '"') { i++; continue; } if (c === quote) { if (quote === "'" && s[i + 1] === "'") { i++; continue; } quote = null; } continue; }
+    if (c === '"' || c === "'") { quote = c; continue; }
+    if (c === "[" || c === "{") depth++;
+    else if (c === "]" || c === "}") { depth--; if (depth === 0) return i; }
+  }
+  return -1;
+}
+/** Top-level comma split of an inline collection body (quotes and nesting respected). */
+function splitInline(inner) {
+  const parts = []; let depth = 0, quote = null, cur = "", any = false;
+  for (let i = 0; i < inner.length; i++) {
+    const c = inner[i];
+    if (quote) { cur += c; if (c === "\\" && quote === '"') { cur += inner[i + 1] ?? ""; i++; continue; } if (c === quote) { if (quote === "'" && inner[i + 1] === "'") { cur += "'"; i++; continue; } quote = null; } continue; }
+    if (c === '"' || c === "'") { quote = c; cur += c; any = true; continue; }
+    if (c === "[" || c === "{") depth++; else if (c === "]" || c === "}") depth--;
+    if (c === "," && depth === 0) { parts.push(cur); cur = ""; any = true; continue; }
+    if (!/\s/.test(c)) any = true;
+    cur += c;
+  }
+  if (any || cur.trim()) parts.push(cur);
+  return parts.filter((p, i) => !(i === parts.length - 1 && !p.trim() && !quoteOnly(p)));
+}
+const quoteOnly = (p) => /^\s*(""|'')\s*$/.test(p);
+/** The first ":" of an inline map entry outside quotes. */
+function inlineKeyEnd(part) {
+  let quote = null;
+  for (let i = 0; i < part.length; i++) {
+    const c = part[i];
+    if (quote) { if (c === quote) quote = null; continue; }
+    if (c === '"' || c === "'") { quote = c; continue; }
+    if (c === ":") return i;
+  }
+  return -1;
+}
 export function parseYamlNested(text) {
   const root = {};
   const stack = [{ indent: -1, node: root }];
   for (const raw of text.split("\n")) {
     if (!raw.trim() || raw.trim().startsWith("#")) continue;
+    // A block sequence item ("- value") belongs to the key that opened the
+    // current node; the first item turns that node into an array. Items are
+    // scalars only (a "- key: value" item is read as the scalar text).
+    const seq = raw.match(/^(\s*)-(?:\s+(.*?))?\s*$/);
+    if (seq) {
+      const indent = seq[1].length;
+      while (stack.length > 1 && indent <= stack[stack.length - 1].indent) stack.pop();
+      const top = stack[stack.length - 1];
+      if (!Array.isArray(top.node)) {
+        if (!top.parent || Object.keys(top.node).length) continue; // not a list position: ignored, as before
+        top.node = []; top.parent[top.key] = top.node;
+      }
+      if (seq[2] !== undefined && seq[2] !== "") top.node.push(yamlScalar(seq[2]));
+      continue;
+    }
     const m = raw.match(/^(\s*)((?:["'][^"']+["'])|(?:[^:#][^:]*?)):\s*(.*?)\s*$/);
     if (!m) continue;
     const [, ws, rawKey, rawVal] = m;
@@ -241,10 +319,11 @@ export function parseYamlNested(text) {
     const indent = ws.length;
     while (stack.length > 1 && indent <= stack[stack.length - 1].indent) stack.pop();
     const parent = stack[stack.length - 1].node;
+    if (Array.isArray(parent)) continue; // a key line inside a sequence is not part of this subset
     if (rawVal.replace(/\s+#.*$/, "").trim() === "" || rawVal.trim().startsWith("#")) {
       const child = {};
       parent[key] = child;
-      stack.push({ indent, node: child });
+      stack.push({ indent, node: child, parent, key });
     } else parent[key] = yamlScalar(rawVal);
   }
   return root;
@@ -262,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") {
@@ -276,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;
   }
 }
@@ -408,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.
@@ -429,7 +511,71 @@ export const RETIRED_CAPABILITIES = {
 export function retiredCapabilityReason(id) {
   return Object.hasOwn(RETIRED_CAPABILITIES, id) ? RETIRED_CAPABILITIES[id] : undefined;
 }
-const CONFIG_KEYS = new Set(["name", "team", "agent-types", "capabilities", "skill-overrides", "agents-md-injection", "oats", "work-modes", "templates", "yolo"]);
+const CONFIG_KEYS = new Set(["name", "team", "agent-types", "capabilities", "skill-overrides", "agents-md-injection", "oats", "work-modes", "templates", "yolo", "launch-configs"]);
+
+// ---------- launch configurations ----------
+// A named way to start a harness, independent of any soul: the runtime, an
+// executable (a wrapper, another binary), literal argv, environment (literal
+// values, or references resolved on the execution host at start time), a
+// model and yolo. Declared per scope under `launch-configs:`; the closest
+// scope declaring a NAME provides the whole entry (no merging between
+// scopes). Selected at spawn or session start/restart by name.
+export const LAUNCH_RUNTIMES = ["pi", "claude", "codex"];
+export const LAUNCH_CONFIG_KEYS = new Set(["runtime", "executable", "args", "env", "model", "yolo"]);
+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_ROOT", "OATS_CONTEXT", "OATS_WORKSPACE", "OATS_EVENT", "OATS_SETTINGS", "OATS_CLI_BIN", "PI_AGENT_INSTANCE", "PI_AGENT_HOME", "PI_AGENTS_ROOT"]);
+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) {
+  const bad = (why) => { throw oatsError("E_LAUNCH_CONFIG_INVALID", `launch configuration ${JSON.stringify(name)}${where ? ` in ${where}` : ""} ${why}`); };
+  if (typeof name !== "string" || !LAUNCH_CONFIG_NAME.test(name)) bad("has an invalid name (letters, digits, dot, underscore, dash; up to 64 characters)");
+  if (name === "none") bad("cannot be named none: that word selects no configuration");
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) bad("must be a map");
+  for (const key of Object.keys(entry)) if (!LAUNCH_CONFIG_KEYS.has(key)) bad(`has an unsupported key ${JSON.stringify(key)} (runtime, executable, args, env, model, yolo)`);
+  if (!LAUNCH_RUNTIMES.includes(entry.runtime)) bad(`needs runtime: one of ${LAUNCH_RUNTIMES.join(", ")}`);
+  const text = (v, what) => { if (typeof v !== "string" || !v.trim() || v.includes("\0")) bad(`${what} must be non-empty text`); };
+  if (entry.executable !== undefined) text(entry.executable, "executable");
+  if (entry.args !== undefined) {
+    if (!Array.isArray(entry.args)) bad("args must be a list of strings");
+    for (const a of entry.args) if (typeof a !== "string" || a.includes("\0")) bad("args must be a list of strings");
+  }
+  if (entry.env !== undefined) {
+    if (!entry.env || typeof entry.env !== "object" || Array.isArray(entry.env)) bad("env must be a map of NAME to a string or {fromEnv: NAME}");
+    for (const [n, v] of Object.entries(entry.env)) {
+      if (!ENV_NAME.test(n)) bad(`env name ${JSON.stringify(n)} is not a valid environment variable name`);
+      if (reservedLaunchEnv(n)) bad(`env ${n} is set by the kernel for every launch and cannot be overridden`);
+      if (typeof v === "string") { if (v.includes("\0")) bad(`env ${n} must be text`); continue; }
+      if (!v || typeof v !== "object" || Array.isArray(v) || Object.keys(v).length !== 1 || typeof v.fromEnv !== "string" || !ENV_NAME.test(v.fromEnv)) bad(`env ${n} must be a string or {fromEnv: NAME}`);
+      if (v && typeof v === "object" && v.fromEnv && v.fromEnv.startsWith(LAUNCH_REF_PREFIX)) bad(`env ${n} may not reference a ${LAUNCH_REF_PREFIX}* alias`);
+    }
+  }
+  if (entry.model !== undefined) text(entry.model, "model");
+  if (entry.yolo !== undefined && typeof entry.yolo !== "boolean") bad("yolo must be true or false");
+  return entry;
+}
+function validateLaunchConfigs(map, file) {
+  if (map === undefined) return;
+  if (!map || typeof map !== "object" || Array.isArray(map)) throw oatsError("E_LAUNCH_CONFIG_INVALID", `launch-configs in ${file} must be a map of name to configuration`);
+  for (const [name, entry] of Object.entries(map)) validateLaunchConfig(name, entry, file);
+}
+/** The effective launch configurations of a config chain (closest first):
+ *  the closest scope declaring a name provides the WHOLE entry; farther
+ *  declarations of the same name are recorded as shadowed. */
+export function launchConfigsOf(chain) {
+  // Null-prototype: a configuration may legitimately be named constructor or
+  // toString, and membership must never be an inherited property.
+  const out = Object.create(null);
+  for (const c of chain) {
+    for (const [name, entry] of Object.entries(c["launch-configs"] || {})) {
+      if (Object.hasOwn(out, name)) { out[name].shadows.push(c._level); continue; }
+      out[name] = { name, runtime: entry.runtime, ...(entry.executable !== undefined ? { executable: entry.executable } : {}), args: [...(entry.args || [])], env: { ...(entry.env || {}) }, ...(entry.model !== undefined ? { model: entry.model } : {}), ...(entry.yolo !== undefined ? { yolo: entry.yolo } : {}), source: c._level, shadows: [] };
+    }
+  }
+  return out;
+}
 /** Renamed-key tables are read with OWN-property semantics only: a config key
  * spelled `constructor`/`toString` inherits a value from `Object.prototype`,
  * and the plain `TABLE[key]` lookup then reported it as the migration hint —
@@ -471,6 +617,7 @@ function loadLevelConfig(dir) {
  * config source material and must pass the same shape checks). */
 export function validateConfigShape(cfg, file) {
   if (cfg.yolo !== undefined && typeof cfg.yolo !== "boolean") throw new Error(`yolo in ${file} must be true or false`);
+  validateLaunchConfigs(cfg["launch-configs"], file);
   for (const key of Object.keys(cfg)) {
     if (Object.hasOwn(RENAMED_CONFIG_KEYS, key)) throw new Error(`unsupported oats-config key "${key}" in ${file} — ${RENAMED_CONFIG_KEYS[key]}`);
     if (!CONFIG_KEYS.has(key)) throw new Error(`unsupported oats-config key in ${file}: ${key}`);
@@ -588,7 +735,7 @@ function manifestRequiredHooks(manifest) {
   }
   return out;
 }
-const APPROVED_HOOKS = new Set(["soul-scaffold", "spawn", "retire"]);
+const APPROVED_HOOKS = new Set(["soul-scaffold", "spawn", "retire", "launch"]);
 
 /** The declared type (agent family) of a soul, read from its soul.yaml via the agents root. */
 export function soulTypeOf(contextDir, soulName) {
@@ -748,6 +895,7 @@ export function resolveOatsConfig(contextDir, soulName) {
   const out = { layers: {}, provenance: {}, layerDisabled: {}, injects: [], capabilities: [], name: chain[0]?.name, chain };
   const yoloCfg = chain.find((c) => c.yolo !== undefined);
   if (yoloCfg) out.yolo = yoloCfg.yolo;
+  out.launchConfigs = launchConfigsOf(chain);
   // Closest team: declaration wins; the declaring scope is the deployment/team boundary.
   const teamCfg = chain.find((c) => c.team);
   if (teamCfg) out.team = { ...teamCfg.team, scope: teamCfg._level };
@@ -4184,9 +4332,11 @@ export const RUNTIME_PACKAGE_MANAGERS = {
      * roots. `--no-approve` keeps a spawn-time probe from trusting
      * project-local files. Falls back to reading settings when pi cannot be
      * run, which yields presence without a verified directory. */
-    list: (env = process.env) => {
+    list: (env = process.env, opts = {}) => {
       try {
-        const out = execFileSync("pi", ["list", "--no-approve"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], env, timeout: 30000 });
+        // The SELECTED executable answers (a wrapper or another binary), with
+        // pi's own controlled list subcommand only: never a launch argument.
+        const out = execFileSync(opts.bin || "pi", ["list", "--no-approve"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], env, timeout: 30000 });
         const rows = [];
         // pi dims the path with chalk; strip any escapes before matching.
         const lines = out.replace(/\u001b\[[0-9;]*m/g, "").split("\n");
@@ -4475,8 +4625,8 @@ function validateHookEnvironment(capabilityID, value, owners, declarations) {
   return accepted;
 }
 
-export function runLifecycleHooks(event, { home, instance, agentName, soulDir, contextDir, workspaceDir, rootDir, resolved, priorMeta = {}, extraEnv = {} }) {
-  const results = { meta: {}, briefs: [], warnings: [], order: [], launch: {}, env: {}, failures: [] };
+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 || [])] }]));
   const caps = [...(resolved.capabilities || [])];
@@ -4488,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, {
@@ -4505,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] || {}),
         },
@@ -4516,8 +4671,16 @@ export function runLifecycleHooks(event, { home, instance, agentName, soulDir, c
       if (o.brief) results.briefs.push(`- ${o.brief}`);
       if (o.warning) results.warnings.push(o.warning);
       if (o.launch && typeof o.launch === "object") for (const [rt, args] of Object.entries(o.launch)) results.launch[rt] = `${results.launch[rt] ? `${results.launch[rt]} ` : ""}${args}`;
+      // Provenance of what this capability contributed to the launch: which
+      // runtimes it answered launch args for, and which env names, under
+      // which settings and trust. A later start or runtime switch reads this.
+      // A launch hook's run is recorded even when its answer is empty: an
+      // empty answer replaces what the provider contributed before.
+      if (event === "launch" || (o.launch && typeof o.launch === "object" && Object.keys(o.launch).length) || (o.env && typeof o.env === "object" && Object.keys(o.env).length)) {
+        results.contributions.push({ capability: cap.id, layer: cap.layer || null, level: cap.level || null, settings: { ...(cap.settings || {}) }, trust: { trusted: !!cap.trust?.trusted, integrity: cap.trust?.integrity || null }, launch: o.launch && typeof o.launch === "object" ? { ...o.launch } : {}, env: o.env && typeof o.env === "object" ? Object.keys(o.env).sort() : [] });
+      }
       if (o.env !== undefined) {
-        if (event !== "spawn") throw new HookEnvironmentContractError(`${cap.id} hook env is supported only for spawn, not ${event}`);
+        if (event !== "spawn" && event !== "launch") throw new HookEnvironmentContractError(`${cap.id} hook env is supported only for spawn and launch, not ${event}`);
         Object.assign(results.env, validateHookEnvironment(cap.id, o.env, envOwners, envDeclarations));
       }
     } catch (e) {
@@ -4556,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;
@@ -4745,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); }
 
@@ -4842,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,
@@ -4866,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";
@@ -5085,13 +5262,16 @@ export const RELATIONS = ["child", "sibling", "parent", "unrelated"];
  * Absence still fails the spawn: "aweb on pi requires the aweb pi package" is a
  * promise the instance's INSTRUCTIONS rely on, so starting without it would
  * leave the agent believing it can be woken by mail when it cannot. */
-function verifyRuntimePackages(runtime, resolved, contextDir) {
+function verifyRuntimePackages(runtime, resolved, contextDir, { bin, env } = {}) {
+  const probeEnv = env || process.env;
   const found = [];
   const problems = [];
-  // The session launches with the CONTEXT-SELECTED executable (oats-claude-config
-  // may name `claude-personal`), so probing the literal `claude` would inspect a
-  // different account's plugins than the instance will actually use.
-  const probeOpts = runtime === "claude" ? { bin: resolveClaudeBinary(contextDir), context: contextDir } : { context: contextDir };
+  // The session launches with the SELECTED executable (a configuration's,
+  // or the context-selected one: oats-claude-config may name
+  // `claude-personal`), so probing another binary would inspect a different
+  // account's packages than the instance will actually use. The probe is the
+  // manager's controlled list subcommand; no launch argument is added to it.
+  const probeOpts = { context: contextDir, ...(bin ? { bin } : runtime === "claude" ? { bin: resolveClaudeBinary(contextDir) } : {}) };
   for (const cap of resolved.capabilities || []) {
     for (const raw of cap.manifest?.requires || []) {
       if (!raw || typeof raw !== "object" || raw.runtime !== runtime) continue;
@@ -5103,7 +5283,7 @@ function verifyRuntimePackages(runtime, resolved, contextDir) {
       const spec = raw.package;
       if (!safeRuntimePackageSpec(spec, runtime)) { problems.push(`${cap.id}: ${runtime} package spec is not a plain source token (${JSON.stringify(spec)})`); continue; }
       if (raw.marketplace !== undefined && !safeRuntimeSourceRef(raw.marketplace)) { problems.push(`${cap.id}: marketplace is not a plain source reference (${JSON.stringify(raw.marketplace)})`); continue; }
-      const status = runtimePackageStatus(runtime, spec, process.env, probeOpts);
+      const status = runtimePackageStatus(runtime, spec, probeEnv, probeOpts);
       const mgr = RUNTIME_PACKAGE_MANAGERS[runtime];
       const stepList = mgr?.steps ? mgr.steps(spec, raw, probeOpts) : [mgr?.argv(spec, raw, probeOpts) || []];
       const direct = stepList.filter((a) => a.length).map((a) => a.join(" ")).join(" && ");
@@ -5151,21 +5331,335 @@ function verifyRuntimePackages(runtime, resolved, contextDir) {
   return found.filter((x) => (seen.has(x.identity) ? false : seen.add(x.identity))).sort((a, b) => a.identity.localeCompare(b.identity));
 }
 
+
+// ---------- launch recipes ----------
+// What a harness start is made of, recorded in instance.json (`launch`) so a
+// later start or restart can re-render it, select another configuration, or
+// switch runtime without guessing from the command string. The rendered
+// command (`command`) stays beside it, byte-identical to what spawn rendered
+// before recipes existed when no configuration is selected.
+export const LAUNCH_RECIPE_VERSION = 1;
+const LAUNCH_PROMPT = { kind: "task-file", file: "TASK.md" };
+
+/** The executable a launch uses: a configuration's declared one (a bare name
+ *  on PATH; a path against the declaring scope when relative) or the
+ *  runtime's default (claude through oats-claude-config). Never executed. */
+export function resolveLaunchExecutable({ runtime, declared, declaringDir, contextDir }) {
+  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 claudeBin = runtime === "claude" ? resolveClaudeBinary(contextDir) : undefined;
+  const name = runtime === "claude" ? claudeBin : runtime;
+  const found = which(name);
+  return { path: found || null, declared: null, resolvedFrom: runtime === "claude" && claudeBin !== "claude" ? "oats-claude-config" : "PATH", missing: found ? undefined : `${name} binary not found on PATH${claudeBin && claudeBin !== "claude" ? " (named by oats-claude-config)" : ""}` };
+}
+/** null when `path` is a regular executable file; otherwise why not. */
+export function checkLaunchExecutable(path) {
+  try {
+    const st = statSync(path);
+    if (!st.isFile()) return `${path} is not a regular file`;
+    accessSync(path, fsConstants.X_OK);
+    return null;
+  } catch (e) { return `${path} ${e.code === "ENOENT" ? "does not exist" : e.code === "EACCES" ? "is not executable" : e.message}`; }
+}
+/** Source names of {fromEnv} references absent from `env`. */
+export function missingLaunchEnvRefs(configEnv, env = process.env) {
+  return Object.values(configEnv || {}).filter((v) => v && typeof v === "object" && v.fromEnv && env[v.fromEnv] === undefined).map((v) => v.fromEnv).sort();
+}
+/** The selection a start makes: which configuration (explicit name, "none",
+ *  a frozen recipe's, or the soul's default), and from it the runtime and
+ *  model. A named configuration is a unit: an explicit runtime that disagrees
+ *  with it is refused. On an existing home, --runtime alone leaves the old
+ *  configuration behind (its executable and args are not carried), and a
+ *  model never crosses runtimes: explicit or configured model, else the
+ *  frozen model on the same runtime, else the runtime's native default. */
+export function resolveLaunchSelection({ launchConfigs = {}, agent, frozen, selection = {} }) {
+  const bad = (code, msg) => { throw oatsError(code, msg); };
+  let wanted = selection.launchConfig;
+  let config = null;
+  if (wanted === undefined && frozen && !selection.runtime) {
+    // An ordinary start of an existing home runs what was recorded: its
+    // configuration as captured (executable, args, env, references), whether
+    // or not the scope still declares it that way. Only an explicit name
+    // applies the current definition.
+    // Named or not: the recorded executable (a saved wrapper, say), args and
+    // env are what runs; later edits of the scope never change it.
+    config = { name: frozen.launchConfig || null, runtime: frozen.runtime, ...(frozen.executableDeclared ? { executable: frozen.executableDeclared } : {}), executablePath: frozen.executable, args: [...(frozen.args || [])], env: { ...(frozen.env || {}) }, ...(frozen.model ? { model: frozen.model } : {}), ...(frozen.yolo !== undefined ? { yolo: frozen.yolo } : {}), source: frozen.launchConfigSource || null, frozen: true };
+    wanted = "none";
+  }
+  if (wanted === undefined) wanted = frozen ? "none" : (agent?.["launch-config"] || "none");
+  if (wanted !== "none") {
+    if (typeof wanted !== "string" || !Object.hasOwn(launchConfigs, wanted)) bad("E_LAUNCH_CONFIG_UNKNOWN", `no launch configuration ${JSON.stringify(wanted)} is effective here${frozen?.launchConfig === wanted ? " any more (the home was started with it; an unqualified start still runs the recorded one)" : ""}; oats launch-config list shows what is`);
+    config = launchConfigs[wanted];
+    if (selection.runtime && selection.runtime !== config.runtime) bad("E_LAUNCH_CONFIG_MISMATCH", `launch configuration ${wanted} starts ${config.runtime}; --runtime ${selection.runtime} disagrees with it (select another configuration, or --launch-config none with --runtime)`);
+  }
+  const runtime = config?.runtime || selection.runtime || (frozen ? frozen.runtime : agent?.runtime || "pi");
+  if (!LAUNCH_RUNTIMES.includes(runtime)) bad("E_UNSUPPORTED_RUNTIME", `unknown runtime "${runtime}" (pi|claude|codex)`);
+  let model, modelSource;
+  const explicit = selection.model !== undefined && selection.model !== null && String(selection.model).trim() !== "";
+  if (explicit) {
+    model = resolveModelPreference(String(selection.model), runtime); modelSource = "explicit";
+    if (!model) bad("E_MODEL_UNKNOWN", `model preference ${JSON.stringify(selection.model)} has no entry usable by runtime ${runtime}; give a ${runtime} model id`);
+  } else if (config?.model) {
+    model = config.frozen ? config.model : resolveModelPreference(config.model, runtime); modelSource = config.frozen ? "recorded" : `launch-config ${config.name}`;
+    if (!model) bad("E_MODEL_UNKNOWN", `launch configuration ${config.name} names model ${JSON.stringify(config.model)}, which has no entry usable by runtime ${runtime}`);
+  } else if (frozen) {
+    if (frozen.runtime === runtime) { model = frozen.model || ""; modelSource = model ? "recorded" : "native default"; }
+    else { model = ""; modelSource = "native default (runtime changed)"; }
+  } else if (runtime !== (agent?.runtime || "pi")) {
+    // A soul's model preference belongs to the soul's runtime; a bare alias
+    // is no proof it fits another one. Nothing is passed across.
+    model = ""; modelSource = "native default (runtime differs from the soul's)";
+  } else { model = resolveModelPreference(agent?.model || "", runtime); modelSource = model ? "soul default" : "native default"; }
+  return { config, runtime, model, modelSource, configuredYolo: config?.yolo };
+}
+/** The pane environment carrying each reference's value under a
+ *  kernel-owned alias (OATS_LAUNCH_REF_<NAME>), which no configuration can
+ *  name: the command says NAME="$OATS_LAUNCH_REF_NAME", so no source
+ *  variable is ever named in the command and no assignment in the same
+ *  prefix can shadow it (zsh evaluates a prefix's assignments in order).
+ *  Rendered as tmux `-e` flags or a shell export prefix. */
+export function launchEnvRefs(recipe, env = process.env) {
+  const out = [];
+  for (const [name, v] of Object.entries(recipe.env || {})) if (v && typeof v === "object" && v.fromEnv && env[v.fromEnv] !== undefined) out.push({ name: `${LAUNCH_REF_PREFIX}${name}`, value: env[v.fromEnv], target: name, source: v.fromEnv });
+  return out;
+}
+export function launchEnvTmuxFlags(recipe, env) { return launchEnvRefs(recipe, env).map((r) => ` -e ${shq(`${r.name}=${r.value}`)}`).join(""); }
+export function launchEnvExports(recipe, env) { return launchEnvRefs(recipe, env).map((r) => `export ${r.name}=${shq(r.value)}; `).join(""); }
+
+/** The harness command line of a recipe. With no configuration the bytes
+ *  equal what spawn rendered before recipes: env prefix, the executable, the
+ *  runtime's own arguments, capability launch args, the task prompt. A
+ *  configuration's args go after the runtime's own options and before
+ *  capability args; for claude/codex the `--` separator keeps them from
+ *  swallowing the task, for pi they follow the task like capability args.
+ *
+ *  pi runs the STRICT CURRICULUM: the OATS-composed skill set and AGENTS.md
+ *  only (--no-skills + --skill, --no-context-files, --no-prompt-templates,
+ *  --append-system-prompt); extensions stay ambient by founder ruling (no
+ *  --no-extensions, no -e), and the task positional goes ahead of contributed
+ *  options because pi has no `--`. claude gets `--` before the prompt so a
+ *  greedy contributed flag cannot eat it. codex keeps its native policy;
+ *  yolo also trusts this generated home for the launch (projects=...). */
+export function renderLaunchRecipe(recipe, { home, instance, redact = false }) {
+  const { runtime, executable, model, yolo } = recipe;
+  const cfgArgs = (recipe.args || []).map(shq).join(" ");
+  const hookArgs = recipe.hooks?.launch?.[runtime] || "";
+  const tail = `${cfgArgs ? ` ${cfgArgs}` : ""}${hookArgs ? ` ${hookArgs}` : ""}`;
+  let cmdline;
+  if (runtime === "claude") {
+    cmdline = `${shq(executable)}${yolo ? " --dangerously-skip-permissions" : ""}${model ? ` --model ${shq(model)}` : ""}${tail} -- "$(cat TASK.md)"`;
+  } else if (runtime === "codex") {
+    const codexTrust = `projects={${JSON.stringify(realPathOrNearest(home))}={trust_level="trusted"}}`;
+    cmdline = `${shq(executable)} --cd ${shq(home)}${yolo ? ` --yolo -c ${shq(codexTrust)}` : ""}${model ? ` --model ${shq(model)}` : ""}${tail} -- "$(cat TASK.md)"`;
+  } else {
+    cmdline = `${shq(executable)} --no-skills --skill ${shq(join(home, ".agents", "skills"))} --no-context-files --no-prompt-templates --append-system-prompt ${shq(join(home, "AGENTS.md"))} --approve --name ${shq(instance)}${model ? ` --model ${shq(model)}` : ""} ${shq("@TASK.md")}${tail}`;
+  }
+  const hookEnv = recipe.hooks?.env || {};
+  const envTokens = Object.keys(hookEnv).sort().map((name) => `${name}=${shq(redact ? "<redacted>" : hookEnv[name])}`);
+  for (const name of Object.keys(recipe.env || {}).sort()) {
+    const v = recipe.env[name];
+    envTokens.push(typeof v === "string" ? `${name}=${shq(redact ? "<redacted>" : v)}` : `${name}="$${LAUNCH_REF_PREFIX}${name}"`);
+  }
+  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) {
+  const bad = (why) => { throw oatsError("E_LAUNCH_RECIPE_UNSUPPORTED", `${what} records a launch recipe this kernel cannot start from (${why}); inspect launch in its instance.json`); };
+  if (!recipe || typeof recipe !== "object") bad("not an object");
+  if (recipe.version !== LAUNCH_RECIPE_VERSION) bad(`version ${JSON.stringify(recipe.version)}, expected ${LAUNCH_RECIPE_VERSION}`);
+  if (!LAUNCH_RUNTIMES.includes(recipe.runtime)) bad(`runtime ${JSON.stringify(recipe.runtime)}`);
+  if (typeof recipe.executable !== "string" || !recipe.executable) bad("no executable");
+  if (!Array.isArray(recipe.args) || recipe.args.some((a) => typeof a !== "string")) bad("args are not a list of strings");
+  if (!recipe.env || typeof recipe.env !== "object" || Array.isArray(recipe.env)) bad("env is not a map");
+  for (const [n, v] of Object.entries(recipe.env)) if (!(typeof v === "string" || (v && typeof v === "object" && typeof v.fromEnv === "string"))) bad(`env ${n} is neither a string nor a reference`);
+  if (recipe.model !== null && recipe.model !== undefined && typeof recipe.model !== "string") bad("model is not text");
+  if (recipe.yolo !== undefined && typeof recipe.yolo !== "boolean") bad("yolo is not a boolean");
+  if (!recipe.hooks || typeof recipe.hooks !== "object") bad("no hooks record");
+  return recipe;
+}
+/** The runtime-package requirements that apply: declared for this runtime
+ *  and, for a conditional row, holding under the provider's (captured)
+ *  settings. Nothing else is probed or restricted. */
+export function applicableRequirements(runtime, providers) {
+  const holds = (cap, r) => !r.when || (r.when && typeof r.when === "object" && !Array.isArray(r.when) && Object.entries(r.when).every(([k, v]) => String(cap.settings?.[k] ?? "") === String(v)));
+  const out = [];
+  for (const cap of providers || []) for (const r of cap.manifest?.requires || []) if (r && typeof r === "object" && r.runtime === runtime && holds(cap, r)) out.push({ capability: cap.id, package: r.package });
+  return out;
+}
+function requirementsWithArgsMessage(runtime, providers, config) {
+  const rows = applicableRequirements(runtime, providers);
+  return `launch configuration ${config?.name || "(recorded)"} passes arguments (${config.args.map((a) => JSON.stringify(a)).join(", ")}) that the ${runtime} package probe cannot carry, so ${rows.map((r) => `${r.capability}'s requirement ${r.package}`).join(", ")} cannot be verified for that launch; native configuration a required package must see belongs in a wrapper executable or the environment (env / fromEnv), not in args`;
+}
+/** ONE planner for what a start would run, used by preview and by starts of
+ *  existing homes alike: the recorded recipe (or, under a selection, the
+ *  current scoped configuration) resolved, preflighted, rendered. `preview`
+ *  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, 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
+  // predates recipes is converted narrowly from its recorded command (the
+  // kernel's own generated shapes only; environment attributed through the
+  // home's capability declarations); the conversion is recorded by the start
+  // that uses it.
+  const frozen = meta ? (meta.launch && typeof meta.launch === "object" ? assertLaunchRecipe(meta.launch, meta.instance || home) : recipeFromLegacyCommand(meta, home).recipe) : null;
+  const chosen = resolveLaunchSelection({ launchConfigs: launchConfigs || resolvedCfg?.launchConfigs || {}, agent: agentLike, frozen, selection });
+  const { config, runtime, model, modelSource } = chosen;
+  const yolo = resolveYolo(selection.yolo ?? chosen.configuredYolo ?? (frozen ? frozen.yolo : agentLike?.yolo ?? resolvedCfg?.yolo));
+  const executable = config?.frozen
+    ? { path: config.executablePath, declared: frozen.executableDeclared ?? null, resolvedFrom: frozen.executableResolvedFrom || "recorded", missing: existsSync(config.executablePath) ? undefined : `${config.executablePath} (recorded) does not exist` }
+    : resolveLaunchExecutable({ runtime, declared: config?.executable, declaringDir: config?.source, contextDir });
+  const exeProblem = executable.path ? checkLaunchExecutable(executable.path) : executable.missing;
+  if (exeProblem) fail("executable", "E_LAUNCH_EXECUTABLE", `launch configuration ${config?.name || "(runtime default)"}: ${exeProblem}`); else problems.push({ check: "executable", ok: true, detail: `${executable.path} (${executable.resolvedFrom})` });
+  // Capability contributions: recorded at spawn with provenance; a runtime
+  // switch needs the new runtime's launch args from the same capabilities.
+  let hooks = { launch: {}, env: {}, contributions: [], pending: true };
+  if (frozen) {
+    // Recorded contributions, refreshed by capabilities that declare a
+    // launch hook; a runtime change needs the new runtime's arguments from
+    // 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, 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);
+      if (untrusted.length) fail("capabilities", "E_LAUNCH_PREPARATION", `${untrusted.join(", ")} contributed to this launch at spawn but is no longer trusted in the scope; re-trust it (oats trust) or change the binding; nothing was stopped`);
+      else problems.push({ check: "capabilities", ok: true, detail: `${runtime !== frozen.runtime ? "prepared for the new runtime" : "recorded contributions reused"}${hooks.refreshed?.length ? `; refreshed by launch hooks: ${hooks.refreshed.join(", ")}` : ""}${inactive.length ? `; no longer active in the scope, recorded contribution kept: ${inactive.join(", ")}` : ""}` });
+    } catch (e) {
+      if (!e.code || !["E_LAUNCH_PREPARATION", "E_LAUNCH_LEGACY"].includes(e.code)) throw e;
+      fail("capabilities", e.code, e.message);
+      hooks = { launch: { ...(frozen.hooks?.launch || {}) }, env: { ...(frozen.hooks?.env || {}) }, contributions: frozen.hooks?.contributions || [] };
+    }
+  } else problems.push({ check: "capabilities", ok: true, detail: "decided by the capabilities' spawn hooks" });
+  // A configuration may not override environment a capability owns.
+  const configEnv = config?.env || {};
+  const owned = Object.keys(configEnv).filter((n) => Object.hasOwn(hooks.env, n));
+  if (owned.length) {
+    const owner = (n) => hooks.contributions.find((c) => (c.env || []).includes(n))?.capability || "a capability";
+    fail("environment", "E_LAUNCH_ENV_CONFLICT", `${owned.map((n) => `${n} (set by ${owner(n)})`).join(", ")} cannot be overridden by launch configuration ${config?.name}; change the capability's setting instead`);
+  }
+  const missing = missingLaunchEnvRefs(configEnv, env);
+  if (missing.length) fail("environment", "E_LAUNCH_ENV_MISSING", `launch configuration ${config?.name} references ${missing.join(", ")}, not set on this host; nothing was stopped or started`);
+  else if (!owned.length) problems.push({ check: "environment", ok: true, detail: `${Object.keys(configEnv).length} value(s), references resolved on the execution host at start` });
+  problems.push({ check: "model", ok: true, detail: model ? `${model} (${modelSource})` : `native default (${modelSource})` });
+  // Runtime package requirements: the captured providers' (bindings united
+  // with contributions, by id, current manifest, captured settings for
+  // conditional rows) for an existing home, the scope's for a new instance;
+  // probed under the launch's EFFECTIVE environment with the selected
+  // executable, only when some requirement is declared for this runtime and
+  // every reference resolved. Configuration arguments cannot be applied to a
+  // package probe (it must never start a conversation), which is stated.
+  if (executable.path && !missing.length && !owned.length) {
+    const providers = frozen
+      ? capturedProviders(meta, frozen).map((p) => { const manifest = contextDir ? capabilityManifest(p.id, contextDir) : undefined; return manifest ? { id: p.id, manifest, settings: p.settings } : null; }).filter(Boolean)
+      : (resolvedCfg?.capabilities || []);
+    const declared = applicableRequirements(runtime, providers).length > 0;
+    if (declared && (config?.args || []).length) {
+      // The controlled probe cannot carry configuration arguments, so with
+      // an applicable requirement a launch under such arguments cannot be
+      // reported verified: refused, truthfully, with the way out.
+      fail("runtime-packages", "E_LAUNCH_PROBE_UNSUPPORTED", requirementsWithArgsMessage(runtime, providers, config));
+    } else if (declared) {
+      try {
+        verifyRuntimePackages(runtime, { capabilities: providers }, contextDir, { ...(config?.executable || config?.frozen ? { bin: executable.path } : {}), env: launchEffectiveEnv({ base: env, hooksEnv: hooks.env, configEnv }) });
+        problems.push({ check: "runtime-packages", ok: true, detail: `verified with ${executable.path}${(config?.args || []).length ? "; configuration arguments are not applied to the probe: native configuration the packages must see belongs in a wrapper or the environment" : ""}` });
+      } catch (e) { fail("runtime-packages", "E_RUNTIME_PACKAGE", e.message); }
+    } else problems.push({ check: "runtime-packages", ok: true, detail: "no runtime package requirement declared for this runtime; nothing probed" });
+  }
+  const recipe = {
+    version: LAUNCH_RECIPE_VERSION, runtime, launchConfig: config?.name || null, launchConfigSource: config?.source || null,
+    executable: executable.path || executable.declared || runtime, executableDeclared: executable.declared ?? null, executableResolvedFrom: executable.resolvedFrom,
+    args: [...(config?.args || [])], env: { ...configEnv }, model: model || null, ...(yolo !== undefined ? { yolo } : {}),
+    hooks: frozen ? { launch: hooks.launch, env: hooks.env, contributions: hooks.contributions } : hooks, prompt: LAUNCH_PROMPT,
+    ...(frozen?.legacy ? { legacy: { ...frozen.legacy, ...(hooks.refreshed?.length ? { replacedBy: hooks.refreshed } : {}) } } : {}),
+  };
+  const inst = instance || meta?.instance || basename(home);
+  const command = renderLaunchRecipe(recipe, { home, instance: inst });
+  const selectionSource = frozen ? (config?.frozen || (!config && !selection.launchConfig && !selection.runtime) ? "frozen" : "config") : "config";
+  return { recipe, command, runtime, model: model || undefined, modelSource, yolo, config, executable, preflight: problems, ok: problems.every((c) => c.ok), selectionSource, frozen };
+}
+/** The environment a planned launch runs under: the host's base, the
+ *  capabilities' validated env, the configuration's literals and its
+ *  references resolved from the BASE (never from the prefix beside them).
+ *  Package probes run under exactly this, so a CLAUDE_CONFIG_DIR or a
+ *  credential reference selects the same account the launch will. */
+export function launchEffectiveEnv({ base = process.env, hooksEnv = {}, configEnv = {} } = {}) {
+  const out = { ...base, ...hooksEnv };
+  for (const [name, v] of Object.entries(configEnv || {})) {
+    if (typeof v === "string") out[name] = v;
+    else if (v && typeof v === "object" && v.fromEnv && base[v.fromEnv] !== undefined) out[name] = base[v.fromEnv];
+  }
+  return out;
+}
+/** argv (after the executable) and environment names of a rendered command,
+ *  from the parser: what a GUI shows, never the TASK body. */
+export function describeLaunchCommand(command) {
+  const { tokens, binary } = parseLaunchCommand(command);
+  const environment = tokens.slice(0, binary).map((t) => t.kind === "envref" ? { name: t.name, reference: true, ...(t.source.startsWith(LAUNCH_REF_PREFIX) ? {} : { fromEnv: t.source }) } : { name: t.name, redacted: true });
+  const argv = tokens.slice(binary + 1).map((t) => t.kind === "sep" ? "--" : t.kind === "prompt" ? t.text : t.value);
+  return { executable: tokens[binary].value, argv, environment };
+}
+/** A persisted command with every environment value withheld (references
+ *  stay references); a command the parser refuses is withheld whole. */
+/** The identity environment every launch carries: public facts (instance
+ *  name, home path), shown in public renderings; everything else is withheld. */
+export const IDENTITY_LAUNCH_ENV = new Set(["OATS_INSTANCE", "OATS_INSTANCE_HOME", "PI_AGENT_INSTANCE", "PI_AGENT_HOME"]);
+export function redactLaunchCommand(command) {
+  try { return parseLaunchCommand(command).tokens.map((t) => t.kind === "env" && !IDENTITY_LAUNCH_ENV.has(t.name) ? `${t.name}='<redacted>'` : t.text).join(" "); }
+  catch { return "<unparseable launch command withheld>"; }
+}
+/** The recipe with every environment value withheld. */
+export function redactLaunchRecipe(recipe) {
+  const env = Object.fromEntries(Object.keys(recipe.env || {}).sort().map((n) => [n, typeof recipe.env[n] === "string" ? { redacted: true } : { fromEnv: recipe.env[n].fromEnv }]));
+  const hooks = recipe.hooks ? { ...recipe.hooks, env: Object.fromEntries(Object.keys(recipe.hooks.env || {}).sort().map((n) => [n, { redacted: true }])) } : undefined;
+  return { ...recipe, env, ...(hooks ? { hooks } : {}) };
+}
 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`);
-  const runtime = o.runtime || agent.runtime || "pi";
-  if (!["pi", "claude", "codex"].includes(runtime)) throw oatsError("E_UNSUPPORTED_RUNTIME", `unknown runtime "${runtime}" (pi|claude|codex)`);
-  const model = resolveModelPreference(o.model || agent.model || "", runtime);
+  if (o.launchConfig !== undefined && (typeof o.launchConfig !== "string" || !o.launchConfig.trim())) throw oatsError("E_BAD_ARGS", "launchConfig must be a configuration name or none");
   const session = o.tmuxSession || DEFAULT_TMUX_SESSION;
   const backend = o.backend || agent.backend || "tmux";
   if (!["tmux", "herdr"].includes(backend)) throw new Error(`unknown session backend "${backend}" (tmux|herdr)`);
   if (o.herdrSocket !== undefined && (typeof o.herdrSocket !== "string" || !o.herdrSocket)) throw oatsError("E_BAD_ARGS", "herdrSocket must be a socket path");
   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.
+  const launchSelection = resolveLaunchSelection({ launchConfigs: launchConfigsOf(configChain(repoAbs)), agent, selection: { launchConfig: o.launchConfig, runtime: o.runtime, model: o.model } });
+  const launchConfig = launchSelection.config;
+  const runtime = launchSelection.runtime;
+  const model = launchSelection.model;
   // Instance homes belong in the soul-owning repo's PRIMARY checkout, never in a
   // linked worktree (see canonicalDeploymentPath). The CLI resolves this through
   // ensureRoot, but the kernel is its own validation boundary — the desktop
@@ -5468,7 +5962,7 @@ export function spawnInstance(root, agent, o = {}) {
   const soulDir = agent._soulDir || soulOf(agent._dir);
   const composition = composeInstanceAgentsMd(soulDir, repoAbs, agent.name, work, agent.kind);
   const resolvedCfg = composition.resolved;
-  const yolo = resolveYolo(o.yolo ?? agent.yolo ?? resolvedCfg.yolo);
+  const yolo = resolveYolo(o.yolo ?? launchSelection.configuredYolo ?? agent.yolo ?? resolvedCfg.yolo);
   const expectedResources = planInstanceResources({ resolved: resolvedCfg, soulDir, agent, contextDir: repoAbs, composition });
   // Runtime extensions selected by ACTIVE capabilities for THIS instance's
   // runtime. Strict launch disables ambient extension discovery, so each one has
@@ -5476,16 +5970,26 @@ export function spawnInstance(root, agent, o = {}) {
   // must fail here, loudly, rather than produce an instance that silently lost
   // its channel. `--runtime` can override a soul default long after install-time
   // reconciliation, so this spawn-time check is the authoritative one.
-  const runtimePackages = verifyRuntimePackages(runtime, resolvedCfg, repoAbs);
 
   // Prerequisites must fail before creating a home, worktree, or identity.
-  const claudeBin = runtime === "claude" ? resolveClaudeBinary(repoAbs) : undefined;
-  const bin = which(runtime === "claude" ? claudeBin : runtime);
-  if (!bin) throw new Error(`${runtime === "claude" ? claudeBin : runtime} binary not found on PATH${claudeBin && claudeBin !== "claude" ? " (named by oats-claude-config)" : ""}`);
+  const executable = resolveLaunchExecutable({ runtime, declared: launchConfig?.executable, declaringDir: launchConfig?.source, contextDir: repoAbs });
+  if (!executable.path) throw new Error(executable.missing);
+  { const bad = checkLaunchExecutable(executable.path); if (bad) throw oatsError("E_LAUNCH_EXECUTABLE", `launch configuration ${launchConfig?.name || "(runtime default)"}: ${bad}`); }
+  const bin = executable.path;
+  const missingRefs = missingLaunchEnvRefs(launchConfig?.env || {}, process.env);
+  if (missingRefs.length) throw oatsError("E_LAUNCH_ENV_MISSING", `launch configuration ${launchConfig.name} references ${missingRefs.join(", ")}, not set in this environment; nothing was created`);
+  // A configuration's executable answers the package probe (without one the
+  // context-selected name does, as before: its remedies name that command),
+  // under the configuration's environment (literals, references resolved
+  // from the base); the capabilities' own env is not known before their
+  // spawn hooks run, which happens after the home exists.
+  if ((launchConfig?.args || []).length && applicableRequirements(runtime, resolvedCfg.capabilities).length) throw oatsError("E_LAUNCH_PROBE_UNSUPPORTED", `${requirementsWithArgsMessage(runtime, resolvedCfg.capabilities, launchConfig)}; nothing was created`);
+  const runtimePackages = verifyRuntimePackages(runtime, resolvedCfg, repoAbs, { ...(launchConfig?.executable ? { bin } : {}), env: launchEffectiveEnv({ base: process.env, configEnv: launchConfig?.env || {} }) });
   if (launch && !which(backend)) throw new Error(`${backend} not installed${backend === "tmux" ? " (brew install tmux)" : " (https://herdr.dev)"}`);
   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
@@ -5503,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);
@@ -5628,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).
@@ -5658,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);
@@ -5698,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) {
@@ -5722,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,
@@ -5780,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
@@ -5789,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 {
@@ -5805,11 +6356,23 @@ 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) {
+        const owner = (n) => (hookRes.contributions || []).find((c) => (c.env || []).includes(n))?.capability || "a capability";
+        throw oatsError("E_LAUNCH_ENV_CONFLICT", `${owned.map((n) => `${n} (set by ${owner(n)})`).join(", ")} cannot be overridden by launch configuration ${launchConfig.name}; change the capability's setting instead`);
+      }
+    }
     const briefLines = hookRes.briefs.length ? `\n${hookRes.briefs.join("\n")}` : "";
     const workDesc = work === "worktree"
       ? `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`;
@@ -5821,84 +6384,20 @@ You are instance "${instance}" of agent "${agent.name}".
 - Do all repository work inside ./work. Read ./work/AGENTS.md or ./work/CLAUDE.md first if present.${briefLines}${runtime === "codex" ? "\n## Runtime notification delivery\n\nNative Codex has no built-in messaging channel. Follow the explicit delivery briefing for this instance from your messaging capability, if present; it may arrange notification through this terminal. Shared channel instructions alone do not establish that delivery is configured. Without an instance delivery briefing, check your messaging capability's inbox and pending commands at task boundaries or when the operator asks; do not assume messages will wake this session.\n" : ""}
 ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spawn time — await instructions.\n"}`);
 
-    // Launch command. Spawn IS session start: this command is persisted in
-    // instance.json and executed in the instance's tmux window. Capabilities may
-    // contribute runtime-specific arguments via their spawn hook's `launch` map
-    // (e.g. aweb's Claude Code channel plugin flags).
-    const hookArgs = hookRes.launch?.[runtime] ? ` ${hookRes.launch[runtime]}` : "";
-    let cmdline;
-    if (runtime === "claude") {
-      // .claude/skills already links the OATS-composed instance skill set.
-      // "--" terminates option parsing BEFORE the prompt: capability launch
-      // hooks can contribute greedy/variadic flags (e.g. aweb's
-      // --dangerously-load-development-channels), and without the separator
-      // the TASK.md text is swallowed as that flag's next value — claude
-      // errors out ("entries must be tagged: <task text>") and the window
-      // drops to the fallback shell, which reads as a silently stuck spawn.
-      cmdline = `${shq(bin)}${yolo ? " --dangerously-skip-permissions" : ""}${model ? ` --model ${shq(model)}` : ""}${hookArgs} -- "$(cat TASK.md)"`;
-    } else if (runtime === "codex") {
-      // Codex discovers this home's AGENTS.md and .agents/skills natively.
-      // Keep the operator's native permission policy. --add-dir is not valid
-      // under every policy (including untrusted/read-only startup). Worktrees
-      // already live below home; external paths use native approval handling.
-      // --yolo bypasses execution approvals but Codex still asks to trust a new
-      // project. The operator's explicit yolo choice also trusts this generated
-      // home for this launch, without editing the shared user config.
-      const codexTrust = `projects={${JSON.stringify(realPathOrNearest(home))}={trust_level="trusted"}}`;
-      cmdline = `${shq(bin)} --cd ${shq(home)}${yolo ? ` --yolo -c ${shq(codexTrust)}` : ""}`
-        + `${model ? ` --model ${shq(model)}` : ""}${hookArgs} -- "$(cat TASK.md)"`;
-    } else {
-      // STRICT CURRICULUM (pi): the OATS-composed set — no user, ancestor, project
-      // or package skill catalogs, and no auto-discovered AGENTS.md/CLAUDE.md.
-      // NOT "nothing else can contribute": extensions stay ambient by founder
-      // ruling (see below), and an extension's resources_discover hook can add
-      // skill paths that survive --no-skills. The OATS-managed root is exact; the
-      // extension surface is the operator's, and stating otherwise here would
-      // contradict the paragraph twelve lines down (reviewer-aggregate2).
-      //
-      //   --no-skills          ends discovery; --skill stays additive.
-      //   --no-context-files   stops ancestor AGENTS.md/CLAUDE.md auto-injection.
-      //                        It also stops the instance's OWN composed AGENTS.md
-      //                        loading, so that is delivered explicitly via
-      //                        --append-system-prompt. The work tree's AGENTS.md
-      //                        stays READABLE by the read tool: readable, not
-      //                        auto-injected, is the contract.
-      //   --no-prompt-templates  same posture for ambient prompt templates.
-      //
-      // Built-in tools and pi's native interaction model are untouched — OATS
-      // curates the curriculum, it does not cripple the runtime.
-      //
-      // EXTENSIONS STAY AMBIENT, by founder ruling: operators run cross-agent pi
-      // extensions (web search, output formatting) that every instance should
-      // keep. So no --no-extensions, and no -e flags either — pi discovers the
-      // installed extensions itself, and passing them explicitly as well would
-      // load the same extension twice.
-      //
-      // The trade-off is deliberate and narrow: an extension's
-      // `resources_discover` hook can contribute skill paths that survive
-      // --no-skills. Today only the OATS bridge does that, and inside an instance
-      // it contributes that instance's OWN .agents/skills, so the composed set is
-      // unchanged. A third-party extension that contributes skills WOULD add them,
-      // which is the accepted residue of keeping shared extensions working.
-      // Capability-required runtime packages are still verified and recorded
-      // (verifyRuntimePackages), so "aweb on pi requires the aweb pi package"
-      // still holds — it is loaded by pi's own discovery rather than by flag.
-      // pi has no `--` end-of-options marker (it rejects `--` in every position),
-      // so the task positional goes AHEAD of capability-contributed options:
-      // nothing preceding it is waiting for a value, so a trailing variadic
-      // contributed flag cannot consume the task.
-      cmdline = `${shq(bin)} --no-skills --skill ${shq(join(home, ".agents", "skills"))}`
-        + ` --no-context-files --no-prompt-templates`
-        + ` --append-system-prompt ${shq(join(home, "AGENTS.md"))}`
-        + ` --approve --name ${shq(instance)}${model ? ` --model ${shq(model)}` : ""} ${shq("@TASK.md")}${hookArgs}`;
-    }
-    // OATS_INSTANCE_HOME is the runtime-neutral contract name (absolute path to
-    // the instance home) exported to EVERY runtime. PI_AGENT_HOME/PI_AGENT_INSTANCE
-    // are pi-branded predecessors kept as compatibility aliases: the separately
-    // published @awebai/oats-pi extension and bin/oats.mjs still read them, and
-    // an older installed extension must keep working against a newer kernel.
-    const hookEnv = Object.keys(hookRes.env).sort().map((name) => `${name}=${shq(hookRes.env[name])}`).join(" ");
-    cmdline = `OATS_INSTANCE=${shq(instance)} OATS_INSTANCE_HOME=${shq(home)} PI_AGENT_INSTANCE=${shq(instance)} PI_AGENT_HOME=${shq(home)}${hookEnv ? ` ${hookEnv}` : ""} ${cmdline}`;
+    // Launch command. Spawn IS session start: the recipe is persisted in
+    // instance.json beside its rendering, which is executed in the instance's
+    // tmux window. Capabilities contributed runtime-specific arguments and
+    // environment through their spawn hook; both are recorded with provenance.
+    const recipe = {
+      version: LAUNCH_RECIPE_VERSION, runtime,
+      launchConfig: launchConfig?.name || null, launchConfigSource: launchConfig?.source || null,
+      executable: bin, executableDeclared: executable.declared, executableResolvedFrom: executable.resolvedFrom,
+      args: [...(launchConfig?.args || [])], env: { ...(launchConfig?.env || {}) },
+      model: model || null, ...(yolo !== undefined ? { yolo } : {}),
+      hooks: { launch: { ...hookRes.launch }, env: { ...hookRes.env }, contributions: hookRes.contributions || [] },
+      prompt: LAUNCH_PROMPT,
+    };
+    const cmdline = renderLaunchRecipe(recipe, { home, instance });
 
     const meta = {
       agent: agent.name, kind: agent.kind || "persistent", instance, home,
@@ -5965,19 +6464,22 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
         executable: cap.executable,
       })),
       ...(backend === "herdr" ? { backend } : { tmux: { session, window: instance } }),
-      command: cmdline, createdAt: new Date().toISOString(),
+      launch: recipe, command: cmdline, createdAt: new Date().toISOString(),
     };
     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 });
-      launchHerdr(spawnHerdr, 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)) {
         const hq = existsSync(root) ? root : workspaceOf(root); // all-local scopes may have no agents/ dir
@@ -5991,16 +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;
-      sh(`tmux new-window -t ${shq(session)} -n ${shq(instance)} -c ${shq(home)} ${shq(windowCmd)}`);
+      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
@@ -6032,7 +6535,7 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
       }
     }
 
-    return { ...meta, attach: spawnHerdr ? `HERDR_SOCKET_PATH=${shq(spawnHerdr.socket)} ${shq(spawnHerdr.binary)} terminal attach ${shq(spawnHerdr.terminalId)}` : backend === "herdr" ? "not launched" : `tmux attach -t ${session}`, warnings: spawnWarnings.length ? spawnWarnings : undefined };
+    return { ...meta, launch: redactLaunchRecipe(recipe), command: redactLaunchCommand(cmdline), attach: spawnHerdr ? `HERDR_SOCKET_PATH=${shq(spawnHerdr.socket)} ${shq(spawnHerdr.binary)} terminal attach ${shq(spawnHerdr.terminalId)}` : backend === "herdr" ? "not launched" : `tmux attach -t ${session}`, warnings: spawnWarnings.length ? spawnWarnings : undefined };
   } catch (error) {
     const note = compensateSpawn();
     error.message += note;
@@ -6057,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")); }
@@ -6077,7 +6581,7 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION) {
           try { const state = inspectHerdr({ ...meta.sessionTarget, binary: "herdr" }); liveness = { running: state.present, runtimeState: state.status }; }
           catch (error) { liveness = { running: null, runtimeState: "unreachable", runtimeError: error.message }; }
         }
-        return { ...meta, ...liveness, ...(rollbackIncomplete ? { rollbackIncomplete } : {}), ...(retirePending ? { retirePending } : {}) };
+        return { ...meta, ...(meta.launch && typeof meta.launch === "object" ? { launch: redactLaunchRecipe(meta.launch) } : {}), ...(typeof meta.command === "string" ? { command: redactLaunchCommand(meta.command) } : {}), ...liveness, ...(rollbackIncomplete ? { rollbackIncomplete } : {}), ...(retirePending ? { retirePending } : {}) };
 
       });
   };
@@ -6192,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"
@@ -6211,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,
@@ -6221,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}`);
     }
@@ -6261,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;
@@ -6270,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.
@@ -6292,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) {
@@ -6376,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,
@@ -6512,6 +7092,10 @@ export function parseLaunchCommand(command) {
       tokens.push({ kind: "prompt", text: LAUNCH_PROMPT_TOKEN });
       continue;
     }
+    // NAME="$SOURCE": an environment reference, resolved on the execution
+    // host when the command runs; the persisted command carries no value.
+    const ref = /^([A-Za-z_][A-Za-z0-9_]*)="\$([A-Za-z_][A-Za-z0-9_]*)"(?= |$)/.exec(command.slice(i));
+    if (ref) { tokens.push({ kind: "envref", name: ref[1], source: ref[2], text: ref[0] }); i += ref[0].length; continue; }
     let envName;
     const m = /^([A-Za-z_][A-Za-z0-9_]*)='/.exec(command.slice(i));
     if (m) { envName = m[1]; i += envName.length + 1; }
@@ -6541,7 +7125,7 @@ export function parseLaunchCommand(command) {
   }
   let binary = -1;
   for (let k = 0; k < tokens.length; k++) {
-    if (tokens[k].kind === "env") { if (binary >= 0) bad(0, "env assignment after the binary"); continue; }
+    if (tokens[k].kind === "env" || tokens[k].kind === "envref") { if (binary >= 0) bad(0, "env assignment after the binary"); continue; }
     if (binary < 0) { if (tokens[k].kind !== "word" || !tokens[k].quoted) bad(0, "no quoted binary after the env prefix"); binary = k; }
   }
   if (binary < 0) bad(0, "no binary");
@@ -6583,6 +7167,237 @@ function writeJsonAtomic(path, value, mode) {
   renameSync(tmp, path);
 }
 
+
+// ---------- stopping a harness, selecting on an existing home ----------
+const SHELL_NAMES = new Set(["sh", "bash", "zsh", "fish", "dash", "ksh", "tcsh", "csh", "login"]);
+/** The harness processes under a session target: for tmux EVERY descendant
+ *  of the pane's launcher process (the launcher shell itself is left so
+ *  that, once its command ends, it becomes the fallback shell the start
+ *  path recognizes); a wrapper that does not exec the harness, the harness
+ *  and their children are all included, topmost first. For Herdr the
+ *  pane's foreground processes. Each row: { pid, ppid, pgid, comm, depth }. */
+export function harnessProcesses(target, io) {
+  const ps = () => ((io?.exec || execFileSync)("ps", ["-axo", "pid=,ppid=,pgid=,comm="], { encoding: "utf8", timeout: 10000, maxBuffer: 4 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] }))
+    .split("\n").map((l) => l.trim().match(/^(\d+)\s+(\d+)\s+(\d+)\s+(.+)$/)).filter(Boolean)
+    .map(([, pid, ppid, pgid, comm]) => ({ pid: Number(pid), ppid: Number(ppid), pgid: Number(pgid), comm: basename(comm).replace(/^-/, "") }));
+  if (target.backend === "herdr") {
+    // Herdr's PaneProcessInfo (installed schema: shell_pid, nullable;
+    // foreground_process_group_id; foreground_processes) names the pane's
+    // shell. That pid, verified against this host, is the root: OATS launched
+    // `exec /bin/sh -c <command>` in it, so the root is the launcher shell
+    // and the harness its child, exactly as under tmux; a root whose exec
+    // replaced it with a non-shell IS the harness and is included. Without a
+    // shell_pid, the verified non-shell foreground processes are the roots.
+    // Never a fabricated row: an unverifiable pid refuses before any signal.
+    const info = herdrCommand(target, ["pane", "process-info", "--pane", target.paneId], io).process_info;
+    if (!info || typeof info !== "object") throw oatsError("E_SESSION_UNKNOWN", "Herdr returned no process information for the pane");
+    const rows = ps();
+    const byParent = new Map();
+    for (const r of rows) { if (!byParent.has(r.ppid)) byParent.set(r.ppid, []); byParent.get(r.ppid).push(r); }
+    const out = [];
+    const walk = (pid, depth) => { for (const child of byParent.get(pid) || []) { if (!out.some((o) => o.pid === child.pid)) { out.push({ ...child, depth }); walk(child.pid, depth + 1); } } };
+    const verified = (pid, what) => {
+      if (!Number.isInteger(pid) || pid <= 0) throw oatsError("E_SESSION_UNKNOWN", `Herdr reported ${what} without a verifiable pid; nothing was signalled`);
+      const row = rows.find((r) => r.pid === pid);
+      if (!row) throw oatsError("E_SESSION_UNKNOWN", `Herdr reports ${what} pid ${pid} but this host has no such process; nothing was signalled`);
+      return row;
+    };
+    if (info.shell_pid !== null && info.shell_pid !== undefined) {
+      const root = verified(info.shell_pid, "the pane shell");
+      if (!SHELL_NAMES.has(root.comm)) out.push({ ...root, depth: 0 });
+      walk(root.pid, 1);
+      return out;
+    }
+    if (!Array.isArray(info.foreground_processes)) throw oatsError("E_SESSION_UNKNOWN", "Herdr returned neither a pane shell pid nor foreground processes");
+    for (const p of info.foreground_processes) {
+      const row = verified(p.pid, `foreground process ${p.name || "?"}`);
+      if (SHELL_NAMES.has(row.comm)) { walk(row.pid, 1); continue; }
+      if (!out.some((o) => o.pid === row.pid)) { out.push({ ...row, depth: 0 }); walk(row.pid, 1); }
+    }
+    return out;
+  }
+  const row = tmuxOn(target.socket, ["list-panes", "-t", `=${target.session}:=${target.window}`, "-F", "#{pane_pid}"], io).trim().split("\n")[0];
+  if (!/^\d+$/.test(row || "")) throw oatsError("E_SESSION_UNKNOWN", "tmux returned no pane process id");
+  const panePid = Number(row);
+  const rows = ps();
+  const byParent = new Map();
+  for (const r of rows) { if (!byParent.has(r.ppid)) byParent.set(r.ppid, []); byParent.get(r.ppid).push(r); }
+  const out = [];
+  const walk = (pid, depth) => { for (const child of byParent.get(pid) || []) { out.push({ ...child, depth }); walk(child.pid, depth + 1); } };
+  walk(panePid, 1);
+  return out;
+}
+/** Ask the harness under `target` to end: SIGTERM to every process found
+ *  under the pane's launcher, one by one, topmost first (no process-group
+ *  signalling: the launcher shell must survive to become the fallback
+ *  shell), then a bounded wait for the signalled processes to be gone and
+ *  the session to read as stopped or a bare shell. Nothing is escalated: a
+ *  harness still there when the wait ends is reported as such, still
+ *  running. Elapsed time is never taken as exit. */
+export function stopHarness(target, { graceMs = 20000, signal = "SIGTERM", io = {}, kill = process.kill, sleep } = {}) {
+  const wait = sleep || ((ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms));
+  const before = inspectSessionTarget(target, io);
+  if (!before.present || before.state === "shell" || before.state === "stopped") return { requested: [], signal, sentAt: null, observedAt: new Date().toISOString(), exited: true, waitedMs: 0, state: before.state, note: "nothing was running" };
+  const procs = harnessProcesses(target, io);
+  if (!procs.length) throw oatsError("E_SESSION_UNKNOWN", `the session reads as ${before.state} but no harness process was found under its pane; nothing was signalled`);
+  const requested = [];
+  const sentAt = new Date().toISOString();
+  for (const r of procs) {
+    try { kill(r.pid, signal); requested.push({ pid: r.pid, pgid: r.pgid, comm: r.comm, signal }); }
+    catch (e) { if (e.code !== "ESRCH") throw oatsError("E_SESSION_STOP_FAILED", `could not signal ${r.comm} (pid ${r.pid}): ${e.message}`); requested.push({ pid: r.pid, pgid: r.pgid, comm: r.comm, signal, note: "already gone" }); }
+  }
+  const started = Date.now();
+  const alive = (pid) => { try { kill(pid, 0); return true; } catch (e) { return e.code === "EPERM"; } };
+  let st = before;
+  while (Date.now() - started <= graceMs) {
+    wait(250);
+    try { st = inspectSessionTarget(target, io); } catch { st = { present: true, state: "unknown" }; }
+    const gone = requested.every((r) => !alive(r.pid));
+    if (gone && (!st.present || st.state === "shell" || st.state === "stopped")) return { requested, signal, sentAt, observedAt: new Date().toISOString(), exited: true, waitedMs: Date.now() - started, state: st.state };
+  }
+  return { requested, signal, sentAt, observedAt: null, exited: false, waitedMs: Date.now() - started, state: st.state, stillRunning: requested.filter((r) => alive(r.pid)).map((r) => r.pid) };
+}
+
+/** A recipe from a home that predates recipes: only the kernel's own
+ *  generated shapes are recognized (identity env, the binary, the runtime's
+ *  template flags, --model, yolo, the task prompt); other environment is
+ *  kept with provenance "legacy-command"; any other argument is reported as
+ *  unclassified and the caller refuses unless a provider can prepare the
+ *  launch anew. Never a general shell interpretation. */
+export function recipeFromLegacyCommand(meta, home) {
+  const { tokens, binary } = parseLaunchCommand(meta.command);
+  // Which capability owned an environment name at spawn: the home's recorded
+  // capability declarations (environment names and namespaces), never a
+  // re-run of a spawn hook.
+  const declared = Array.isArray(meta.capabilityRuntime) ? meta.capabilityRuntime : [];
+  const ownerOf = (name) => declared.find((c) => (c.environment || []).includes(name) || (c.environmentNamespaces || []).some((ns) => name.startsWith(ns)));
+  const runtime = meta.runtime;
+  if (!LAUNCH_RUNTIMES.includes(runtime)) throw oatsError("E_LAUNCH_COMMAND_UNSUPPORTED", `instance records runtime ${JSON.stringify(runtime)}, which this kernel cannot relaunch`);
+  const env = {}, hookEnv = {}, envNames = [];
+  for (const t of tokens.slice(0, binary)) {
+    if (t.kind === "envref") { env[t.name] = { fromEnv: t.source }; continue; }
+    if (IDENTITY_LAUNCH_ENV.has(t.name)) continue;
+    hookEnv[t.name] = t.value; envNames.push(t.name);
+  }
+  const words = tokens.slice(binary + 1);
+  const value = (i) => words[i]?.kind === "word" ? words[i].value : undefined;
+  let i = 0, model = null, yolo, sawPrompt = false;
+  const extras = [];
+  const expect = (...seq) => { for (const w of seq) { if (value(i) !== w) throw oatsError("E_LAUNCH_LEGACY", `the recorded ${runtime} command is not the kernel's generated shape (expected ${JSON.stringify(w)} at argument ${i + 1}); it cannot be converted`); i++; } };
+  if (runtime === "pi") {
+    expect("--no-skills", "--skill", join(home, ".agents", "skills"), "--no-context-files", "--no-prompt-templates", "--append-system-prompt", join(home, "AGENTS.md"), "--approve", "--name", meta.instance);
+    if (value(i) === "--model") { model = value(i + 1) ?? null; i += 2; }
+    expect("@TASK.md"); sawPrompt = true;
+  } else {
+    if (runtime === "codex") {
+      expect("--cd", home);
+      if (value(i) === "--yolo") { yolo = true; i++; if (value(i) === "-c" && /^projects=\{/.test(value(i + 1) || "")) i += 2; }
+    } else if (value(i) === "--dangerously-skip-permissions") { yolo = true; i++; }
+    if (value(i) === "--model") { model = value(i + 1) ?? null; i += 2; }
+  }
+  for (; i < words.length; i++) {
+    const t = words[i];
+    if (t.kind === "sep") { const p = words[i + 1]; if (p?.kind === "prompt" && i + 2 === words.length) { sawPrompt = true; i = words.length; break; } }
+    if (t.kind === "prompt" && runtime !== "pi") { sawPrompt = true; continue; }
+    extras.push(t.kind === "sep" ? "--" : t.value ?? t.text);
+  }
+  if (!sawPrompt) throw oatsError("E_LAUNCH_LEGACY", `the recorded ${runtime} command carries no task prompt in the kernel's shape; it cannot be converted`);
+  const recipe = {
+    version: LAUNCH_RECIPE_VERSION, runtime, launchConfig: null, launchConfigSource: null,
+    executable: tokens[binary].value, executableDeclared: null, executableResolvedFrom: "recorded",
+    args: [], env, model: model || meta.model || null, ...(yolo !== undefined ? { yolo } : meta.yolo !== undefined ? { yolo: meta.yolo } : {}),
+    hooks: { launch: extras.length ? { [runtime]: extras.map((a) => (a === "--" ? a : shq(a))).join(" ") } : {}, env: hookEnv, contributions: (() => {
+      const rows = [];
+      for (const name of envNames.sort()) {
+        const owner = ownerOf(name);
+        const row = rows.find((r) => r.capability === (owner?.id || null));
+        if (row) { row.env.push(name); continue; }
+        rows.push(owner
+          ? { capability: owner.id, layer: owner.layer || null, level: owner.level || null, settings: { ...(owner.settings || {}) }, trust: { trusted: !!owner.trust?.trusted, integrity: owner.trust?.integrity || null }, launch: {}, env: [name], source: "legacy-command" }
+          : { capability: null, source: "legacy-command", launch: {}, env: [name] });
+      }
+      if (extras.length) rows.push({ capability: null, source: "legacy-command", launch: { [runtime]: extras.map((a) => (a === "--" ? a : shq(a))).join(" ") }, env: [] });
+      return rows;
+    })() },
+    prompt: LAUNCH_PROMPT, legacy: { convertedFrom: "command", unclassified: extras },
+  };
+  return { recipe, extras };
+}
+/** Capability contributions for a start of an existing home: the recorded
+ *  ones, refreshed by any capability that declares a `launch` hook (asked
+ *  for the target runtime; side-effect-free by contract; spawn hooks are
+ *  never re-run). A runtime change needs the new runtime's launch arguments
+ *  from every capability that contributed runtime-specific ones. */
+/** The providers captured for a home: every recorded capability binding
+ *  (meta.capabilityRuntime) united with every recorded contribution's id,
+ *  each with its contribution (if it made one) and its captured settings.
+ *  Already-recorded metadata; a provider bound to the scope after the spawn
+ *  is not in it. */
+export function capturedProviders(meta, frozen) {
+  const contributions = (frozen?.hooks?.contributions || []).filter((c) => c.capability);
+  const bindings = Array.isArray(meta?.capabilityRuntime) ? meta.capabilityRuntime : [];
+  const ids = [...new Set([...bindings.map((b) => b.id), ...contributions.map((c) => c.capability)])].filter(Boolean);
+  return ids.map((id) => {
+    const contribution = contributions.find((c) => c.capability === id) || null;
+    const binding = bindings.find((b) => b.id === id) || null;
+    return { id, contribution, binding, settings: contribution?.settings ?? binding?.settings ?? {} };
+  });
+}
+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 = [];
+  // The providers that took part in this home's launch are the CAPTURED ones
+  // (its recorded contributions). Each is resolved by id through the scope's
+  // current installed manifest and trust, whatever the scope's bindings say
+  // now: a captured provider that is no longer installed, or no longer
+  // trusted, refuses the start; a provider bound to the scope after the
+  // spawn is never adopted. A captured provider that declares a launch hook
+  // prepares the target runtime under its CAPTURED settings.
+  const ctx = contextDir || meta.repo;
+  const withLaunchHook = [];
+  for (const p of capturedProviders(meta, frozen)) {
+    const manifest = ctx ? capabilityManifest(p.id, ctx) : undefined;
+    if (!manifest) throw oatsError("E_LAUNCH_PREPARATION", `${p.id} was part of this home's launch at spawn but is no longer installed in the scope; reinstall it (oats install) or respawn the instance; nothing was stopped`);
+    const trust = capabilityTrust(manifest, ctx);
+    if (!trust.trusted) throw oatsError("E_LAUNCH_PREPARATION", `${p.id} was part of this home's launch at spawn but is no longer trusted in the scope (${trust.reason || "not trusted"}); re-trust it (oats trust) or respawn the instance; nothing was stopped`);
+    const hooks = manifestHookCommands(manifest);
+    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", { 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
+    // spawn runner holds it across providers: a refreshed provider may
+    // replace its own previous keys, never a key another provider retains.
+    const refreshedIds = new Set((res.contributions || []).map((c) => c.capability));
+    const retainedOwner = new Map();
+    for (const c of contributions) if (c.capability && !refreshedIds.has(c.capability)) for (const name of c.env || []) retainedOwner.set(name, c.capability);
+    for (const c of res.contributions || []) for (const name of c.env || []) {
+      if (retainedOwner.has(name)) throw oatsError("E_LAUNCH_PREPARATION", `${c.capability}'s launch hook set ${name}, which ${retainedOwner.get(name)} contributed at spawn and retains; one provider owns an environment name; nothing was stopped`);
+    }
+    for (const c of res.contributions || []) {
+      const idx = contributions.findIndex((x) => x.capability === c.capability);
+      // The provider's previous contribution goes whole, its env names
+      // included, before its new (validated) one is merged: an empty answer
+      // is a replacement too.
+      for (const name of contributions[idx]?.env || []) delete env[name];
+      const row = { ...c, source: "launch-hook" };
+      if (idx >= 0) contributions[idx] = row; else contributions.push(row);
+      refreshed.push(c.capability);
+    }
+    Object.assign(env, res.env || {});
+  }
+  const unprepared = contributions.filter((c) => c.capability !== null && !refreshed.includes(c.capability) && c.launch && c.launch[frozen.runtime] !== undefined && c.launch[runtime] === undefined).map((c) => c.capability);
+  const legacyArgs = contributions.filter((c) => c.capability === null && c.launch && Object.keys(c.launch).length);
+  if (legacyArgs.length && !refreshed.length) throw oatsError("E_LAUNCH_LEGACY", `the recorded command carries arguments this kernel cannot attribute (${legacyArgs.map((c) => c.launch[frozen.runtime] || Object.values(c.launch)[0]).join(" ")}); no captured capability declares a launch hook to prepare the launch anew, so the start is refused; respawn the instance, or have the provider declare a launch hook`);
+  if (unprepared.length) throw oatsError("E_LAUNCH_PREPARATION", `${unprepared.join(", ")} contributed ${frozen.runtime} launch arguments at spawn and none for ${runtime}; change that capability's setting (for example its delivery mode), or the provider must declare a launch hook; nothing was stopped`);
+  const launch = {};
+  for (const c of contributions) { if (c.capability === null && refreshed.length) continue; for (const [rt, args] of Object.entries(c.launch || {})) if (args) launch[rt] = `${launch[rt] ? `${launch[rt]} ` : ""}${args}`; }
+  return { launch, env, contributions: contributions.filter((c) => !(c.capability === null && refreshed.length)), refreshed };
+}
+
 /** Start a stopped instance again in its existing home: no new home, no
  *  spawn hooks, no identity work. The persisted launch command runs in the
  *  recorded tmux session (on the recorded socket) or Herdr server, the
@@ -6611,9 +7426,23 @@ function writeJsonAtomic(path, value, mode) {
  *  gate: a target that is present (or a retained dead pane) is recorded and
  *  adopted, an exited target has its metadata reconciled before restarting,
  *  and a target that cannot be observed refuses and keeps the receipt. */
+/** Stop the running harness of an existing home and start it again in place
+ *  (a selection may change the configuration, runtime, model or yolo): one
+ *  per-home lock and pending receipt across stop and launch, every preflight
+ *  before the stop, a bounded SIGTERM with no escalation, factual receipts.
+ *  Not a retirement: home, work, identity and notes stay. */
+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");
@@ -6631,7 +7460,8 @@ export function startInstanceSession(home, o = {}) {
   // The independent receipt first (retire and session consult it), then the
   // mutable metadata; both tmp+rename. A failure between them is what the
   // pending receipt exists for.
-  const record = (meta, { id, backend, target, model, command, startedAt, reused }, clearPending = true) => {
+  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}`); }
@@ -6640,16 +7470,17 @@ export function startInstanceSession(home, o = {}) {
       ? { launched: true, sessionTarget: target }
       : { launched: true, tmux: { session: target.session, window: target.window, socket: resolve(target.socket) } };
     writeJsonAtomic(baselinePath, baseline, 0o600);
-    if (o.io?.failBeforeMetadataWrite) throw new Error("injected metadata write failure");
+    if (o.io?.failBeforeMetadataWrite && reused !== "adopted") throw new Error("injected metadata write failure"); // the write after THIS start's allocation
     const recorded = meta.startId === id;
     const restarts = (Array.isArray(meta.restarts) ? meta.restarts : []).slice(recorded ? -20 : -19);
     if (!recorded) restarts.push({ startedAt, model: model ?? null, reused });
-    const next = { ...meta, model, command, launched: true, startId: id, restarts, restartCount: (meta.restartCount || 0) + (recorded ? 0 : 1) };
+    const next = { ...meta, model, command, launched: true, startId: id, restarts, restartCount: (meta.restartCount || 0) + (recorded ? 0 : 1),
+      ...(launch ? { launch } : {}), ...(newRuntime ? { runtime: newRuntime } : {}), ...(newYolo !== undefined ? { yolo: newYolo } : {}) };
     if (backend === "herdr") { next.sessionTarget = target; delete next.tmux; }
     else { next.tmux = { session: target.session, window: target.window, socket: resolve(target.socket) }; delete next.sessionTarget; }
     writeJsonAtomic(metaPath, next);
     if (clearPending) rmSync(pendingPath, { force: true });
-    return { instance: meta.instance, agent: meta.agent, home: realHome, runtime: meta.runtime, backend, model: model ?? null, target, startedAt, restartCount: next.restartCount, reused };
+    return { instance: meta.instance, agent: meta.agent, home: realHome, runtime: next.runtime, backend, model: model ?? null, launchConfig: next.launch?.launchConfig ?? null, yolo: next.yolo ?? null, target, startedAt, restartCount: next.restartCount, reused, ...(stop ? { stop } : {}) };
   };
   try { mkdirSync(lock); }
   catch (e) {
@@ -6671,13 +7502,18 @@ export function startInstanceSession(home, o = {}) {
         : pt?.backend === "tmux" && [pt.session, pt.window, pt.socket].every((v) => typeof v === "string" && v.length > 0) && isAbsolute(pt.socket);
       let validCommand = false;
       try { parseLaunchCommand(pending?.command); validCommand = true; } catch { /* preserve invalid receipt below */ }
-      const validReceipt = validTarget && validCommand
+      let validLaunch = true;
+      if (pending?.launch !== undefined) { try { assertLaunchRecipe(pending.launch, "the pending start"); } catch { validLaunch = false; } }
+      if (pending?.runtime !== undefined && !LAUNCH_RUNTIMES.includes(pending.runtime)) validLaunch = false;
+      if (pending?.yolo !== undefined && typeof pending.yolo !== "boolean") validLaunch = false;
+      const validReceipt = validTarget && validCommand && validLaunch
         && typeof pending.id === "string" && /^[a-zA-Z0-9-]{1,80}$/.test(pending.id)
         && (pending.model === null || (typeof pending.model === "string" && !!pending.model.trim() && !pending.model.includes("\0")))
         && typeof pending.startedAt === "string" && Number.isFinite(Date.parse(pending.startedAt));
       if (!validReceipt) throw oatsError("E_SESSION_UNKNOWN", `an earlier start left an unreadable or invalid receipt at ${pendingPath}; inspect it before retrying; nothing was started`);
       const pbackend = pending.target.backend === "herdr" ? "herdr" : "tmux";
       let st;
+      checkRoots();
       try { st = inspectSessionTarget(pending.target, o.io); }
       catch (e) {
         if (pbackend === "tmux" && lostTmuxServer(e)) st = { present: false, state: "stopped" };
@@ -6695,9 +7531,15 @@ export function startInstanceSession(home, o = {}) {
       const meta = readMeta();
       const done = record(meta, { ...pending, backend: pbackend, model: pending.model ?? undefined, reused: "adopted" }, !st.present || st.state === "shell");
       if (st.present && st.state !== "shell") {
-        if (o.model != null && String(o.model).trim() && resolveModelPreference(String(o.model), meta.runtime) !== done.model) throw oatsError("E_SESSION_RUNNING", `${meta.instance} is already running with its previously requested model; its target was recovered, but the new model was not applied`);
-        if (meta.startId === pending.id) throw oatsError("E_SESSION_RUNNING", `${meta.instance} is already running; nothing was started`);
-        return done;
+        if (o.restart) { rmSync(pendingPath, { force: true }); }
+        else {
+          // The recovered target runs what the receipt says; a choice made
+          // now (model, configuration, runtime, yolo) was not applied to it.
+          if (o.model != null && String(o.model).trim() && resolveModelPreference(String(o.model), done.runtime || meta.runtime) !== done.model) throw oatsError("E_SESSION_RUNNING", `${meta.instance} is already running with its previously requested model; its target was recovered, but the new model was not applied`);
+          if (o.launchConfig !== undefined || o.runtime !== undefined || o.yolo !== undefined) throw oatsError("E_SESSION_RUNNING", `${meta.instance} is already running (its pending start was recovered); the requested launch configuration, runtime or yolo was not applied; stop it, or use session restart`);
+          if (meta.startId === pending.id) throw oatsError("E_SESSION_RUNNING", `${meta.instance} is already running; nothing was started`);
+          return done;
+        }
       }
     }
     // 2. The ordinary gate and observation, all under the lock.
@@ -6708,12 +7550,40 @@ export function startInstanceSession(home, o = {}) {
     const backend = meta.sessionTarget || meta.backend === "herdr" ? "herdr" : "tmux";
     let command = meta.command;
     let model = meta.model || undefined;
-    if (o.model !== undefined && o.model !== null && String(o.model).trim() !== "") {
+    // What this start launches: the frozen command (optionally with another
+    // model, re-rendered in place), or, under a selection, the recipe
+    // re-resolved against the home's current scoped configuration. Every
+    // preflight happens here, before anything is observed or stopped.
+    const selected = o.launchConfig !== undefined || o.runtime !== undefined || o.yolo !== undefined;
+    const hasRecipe = meta.launch && typeof meta.launch === "object";
+    let launchPlan = null;
+    if (selected || hasRecipe) {
+      // Every start of a home with a recipe (ordinary, model-only, or under a
+      // selection) goes through the one planner: recipe shape, the recorded
+      // or selected executable, references, capability contributions under
+      // the captured settings and current trust. A home that predates
+      // recipes is converted only when a selection asks for it.
+      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, 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() !== "") {
       const resolved = resolveModelPreference(String(o.model), runtime);
       if (!resolved) throw oatsError("E_MODEL_UNKNOWN", `model preference ${JSON.stringify(o.model)} has no entry usable by runtime ${runtime}; give a ${runtime} model id`);
       command = withLaunchModel(command, resolved);
       model = resolved;
     } else parseLaunchCommand(command);
+    // References recorded for this home must resolve on this host on every
+    // start path, and the source variables go to the pane, not the command.
+    const recipeForEnv = launchPlan?.recipe || (meta.launch && typeof meta.launch === "object" ? meta.launch : null);
+    if (recipeForEnv) { const missing = missingLaunchEnvRefs(recipeForEnv.env, o.env || process.env); if (missing.length) throw oatsError("E_LAUNCH_ENV_MISSING", `this home's launch references ${missing.join(", ")}, not set on this host; nothing was started`); }
+    const paneEnv = recipeForEnv ? launchEnvRefs(recipeForEnv, o.env || process.env) : [];
+    const paneEnvFlags = paneEnv.flatMap((r) => ["-e", `${r.name}=${r.value}`]);
+    const paneEnvExports = paneEnv.map((r) => `export ${r.name}=${shq(r.value)}; `).join("");
+    checkRoots(); // launch hooks/preparation have run; no backend has been observed
+    const planExtra = launchPlan ? { launch: launchPlan.recipe, runtime: launchPlan.runtime, yolo: launchPlan.yolo } : {};
     let target = receipt.target;
     let state = { present: false, state: "not-launched" };
     let serverGone = false;
@@ -6724,10 +7594,23 @@ export function startInstanceSession(home, o = {}) {
         else throw oatsError("E_SESSION_UNKNOWN", `cannot establish whether ${meta.instance} is running, so nothing was started: ${String(e.stderr ?? e.message ?? "").trim() || e.message}`);
       }
     }
-    if (state.present && state.state !== "shell") throw oatsError("E_SESSION_RUNNING", `${meta.instance} is running (${state.state}); nothing was started`);
+    let stopReceipt = null;
+    if (state.present && state.state !== "shell") {
+      if (!o.restart) throw oatsError("E_SESSION_RUNNING", `${meta.instance} is running (${state.state}); nothing was started`);
+      // Restart: every preflight above passed, so ask the running harness to
+      // end and wait, bounded. A harness still there afterwards is reported
+      // as running; nothing is escalated and nothing is launched.
+      stopReceipt = stopHarness(target, { graceMs: o.stopGraceMs ?? 20000, io: o.io, kill: o.io?.kill, sleep: o.io?.sleep });
+      writeJsonAtomic(join(realHome, ".oats-restart.json"), { instance: meta.instance, at: new Date().toISOString(), stop: stopReceipt, next: { runtime: launchPlan?.runtime || runtime, launchConfig: launchPlan?.recipe?.launchConfig ?? meta.launch?.launchConfig ?? null, model: model ?? null } }, 0o600);
+      if (!stopReceipt.exited) throw oatsError("E_SESSION_STOP_FAILED", `${meta.instance} was asked to stop (${stopReceipt.signal} to ${stopReceipt.requested.map((r) => `${r.comm} pid ${r.pid}`).join(", ")} at ${stopReceipt.sentAt}) and was still running after ${stopReceipt.waitedMs} ms (${stopReceipt.state}); nothing was escalated and nothing was started; stop it yourself, or retry with a longer --stop-grace. Receipt: ${join(realHome, ".oats-restart.json")}`);
+      try { state = inspectSessionTarget(target, o.io); } catch (e) { if (backend === "tmux" && lostTmuxServer(e)) { serverGone = true; state = { present: false, state: "stopped" }; } else throw oatsError("E_SESSION_UNKNOWN", `after the stop, cannot establish the state of ${meta.instance}: ${String(e.stderr ?? e.message ?? "").trim() || e.message}`); }
+      if (state.present && state.state !== "shell") throw oatsError("E_SESSION_UNKNOWN", `${meta.instance} read as stopped and then as ${state.state} again; nothing was started`);
+    }
     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`);
@@ -6738,8 +7621,9 @@ 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);
       }
-      writeJsonAtomic(pendingPath, { id, target, command, model: model ?? null, startedAt }, 0o600);
-      try { launchHerdr(target, `cd ${shq(realHome)} && ${completedCommand}; exit "$oats_start_status"`, 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); }
     } else {
       const session = target?.session || meta.tmux?.session || DEFAULT_TMUX_SESSION;
@@ -6750,21 +7634,28 @@ 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) {
-        writeJsonAtomic(pendingPath, { id, target, command, model: model ?? null, startedAt }, 0o600);
-        try { tmuxOn(socket, ["respawn-pane", "-k", "-t", state.paneId, "-c", realHome, windowCmd], o.io); }
+        checkRoots();
+        writeJsonAtomic(pendingPath, { id, target, command, model: model ?? null, startedAt, ...planExtra }, 0o600);
+        try { tmuxOn(socket, ["respawn-pane", "-k", "-t", state.paneId, "-c", realHome, ...paneEnvFlags, windowCmd], o.io); }
         catch (e) { throw launchFailure("tmux", e); }
         reused = "pane";
       } else {
         const instancesRoot = dirname(realHome);
         const hq = existsSync(dirname(dirname(instancesRoot))) ? dirname(dirname(instancesRoot)) : realHome;
+        checkRoots();
         if (!socket) {
           // Never launched (--no-launch): the default server, as spawn uses.
-          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 });
@@ -6780,8 +7671,9 @@ 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) };
-        writeJsonAtomic(pendingPath, { id, target, command, model: model ?? null, startedAt }, 0o600);
-        try { tmuxOn(socket, ["new-window", "-t", `=${session}:`, "-n", window, "-c", realHome, windowCmd], o.io); }
+        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); }
       }
       target = { backend: "tmux", session, window, socket: resolve(socket) };
@@ -6789,17 +7681,23 @@ export function startInstanceSession(home, o = {}) {
     // Keep launch evidence until the command exits or the target disappears.
     // A transient child (for example cat TASK.md) is not proof that startup
     // has finished. A later start reconciles the receipt without a watcher.
-    try { return record(meta, { id, backend, target, model, command, startedAt, reused }, false); }
+    try { return record(meta, { id, backend, target, model, command, startedAt, reused, ...planExtra, ...(stopReceipt ? { stop: stopReceipt } : {}) }, false); }
     catch (e) {
       if (e.code && String(e.code).startsWith("E_")) throw e;
       throw oatsError("E_SESSION_START_INCOMPLETE", `${meta.instance} was started (${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);
@@ -6814,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);
@@ -6826,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() } = {}) {
@@ -6933,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 {
@@ -6975,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 });
@@ -7146,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:
@@ -7193,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
@@ -7206,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.
@@ -7247,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);
@@ -7294,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);
@@ -7465,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.