@awebai/oats 0.22.16 → 0.22.19

package/lib/core.mjs

@@ -31,12 +31,13 @@ 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 { 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
@@ -210,30 +211,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 +318,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;
@@ -429,7 +507,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 +613,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 +731,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 +891,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 +4328,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");
@@ -4476,7 +4622,7 @@ function validateHookEnvironment(capabilityID, value, owners, declarations) {
 }
 
 export function runLifecycleHooks(event, { home, instance, agentName, soulDir, contextDir, workspaceDir, rootDir, resolved, priorMeta = {}, extraEnv = {} }) {
-  const results = { meta: {}, briefs: [], warnings: [], order: [], launch: {}, env: {}, failures: [] };
+  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 || [])];
@@ -4516,8 +4662,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) {
@@ -5085,13 +5239,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 +5260,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,14 +5308,306 @@ 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}`;
+}
+
+/** 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 }) {
+  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 });
+      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 === "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)`);
@@ -5166,6 +5615,12 @@ export function spawnInstance(root, agent, o = {}) {
   const launch = o.launch !== false;
   const repoAbs = resolveRepo(root, o.repo || agent.repo);
   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 +5923,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,12 +5931,21 @@ 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") : "");
@@ -5805,6 +6269,13 @@ 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`);
     }
+    {
+      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`
@@ -5821,84 +6292,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,7 +6372,7 @@ ${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;
 
@@ -5977,7 +6384,8 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
       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);
+      try { launchHerdr(spawnHerdr, `${launchEnvExports(recipe, process.env)}${cmdline}`); }
+      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
@@ -5996,7 +6404,8 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
       // agent exits (e.g. Ctrl-C) instead of tmux killing the window.
       const windowCmd = `${cmdline}; 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");
@@ -6032,7 +6441,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;
@@ -6077,7 +6486,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 } : {}) };
 
       });
   };
@@ -6512,6 +6921,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 +6954,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 +6996,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 = {} }) {
+  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", { 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,6 +7255,12 @@ 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");
   const realHome = realPathOrNearest(home);
@@ -6631,7 +7281,7 @@ 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) => {
     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 +7290,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,7 +7322,11 @@ 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));
@@ -6695,9 +7350,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 +7369,39 @@ 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 });
+      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("");
+    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,7 +7412,18 @@ 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)}`;
@@ -6738,8 +7437,8 @@ 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); }
+      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,8 +7449,8 @@ 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); }
+        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 {
@@ -6780,8 +7479,8 @@ 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); }
+        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,7 +7488,7 @@ 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`);