@awebai/oats 0.26.0 → 0.27.1

package/lib/core.mjs

@@ -24,7 +24,7 @@
  * soul.yaml (flat key: value):
  *   name, description, kind (persistent|local), type (optional agent-type/family, targeted by config),
  *   repo (path rel. to workspace or absolute),
- *   work (worktree|checkout|attached|workspace|directory), runtime (pi|claude|codex), model (pi model pattern, optional)
+ *   work (worktree|checkout|attached|workspace|directory), harness (pi|claude|codex), model (pi model pattern, optional)
  *   (attached as soul default is for service agents — spawn must supply workDir)
  */
 import { execFileSync, execSync, spawn as spawnProcess, spawnSync } from "node:child_process";
@@ -36,6 +36,7 @@ import { accessSync, constants as fsConstants } from "node:fs";
 import { createHash, randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { initializeNativeHistory, prepareNativeStart } from "../packages/record/lib/native-history.mjs";
+import { noteRuntimeName } from "./deprecation.mjs";
 import { attachSessionTarget } from "./session-viewer.mjs";
 import { inspectSessionTarget, inputSessionTarget } from "./session-input.mjs";
 import { appendEvent } from "./instance-events.mjs";
@@ -133,7 +134,7 @@ export const PACKAGED_SKILLS_DIR = join(PKG_ROOT, "skills");
 // ---------- shell helpers ----------
 function sh(cmdline) { return execSync(cmdline, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim(); }
 function shTry(cmdline) { try { return sh(cmdline); } catch { return undefined; } }
-/** A native PROBE (a runtime binary asked about its catalogue or packages) under
+/** A native PROBE (a harness binary asked about its catalogue or packages) under
  *  a preview: bounded by what is left of the shared preflight budget, run in its
  *  own process group and group-killed on timeout. Cheap lookups (`command -v`)
  *  are not probes and never draw from the budget. Outside a preview: shTry. */
@@ -501,14 +502,17 @@ export const LAYERS = ["knowledge", "messaging", "tasks"];
 
 
 // ---------- launch configurations ----------
-// A named way to start a harness, independent of any soul: the runtime, an
+// A named way to start a harness, independent of any soul: the harness, 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 by the host under `launch-configs:` in the
 // deployment's oats-local.yaml (lead decision 2: a spawn-time HOST choice,
 // never a soul field). 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"]);
+export const LAUNCH_HARNESSES = ["pi", "claude", "codex"];
+export const LAUNCH_CONFIG_KEYS = new Set(["harness", "runtime", "executable", "args", "env", "model", "yolo"]);
+/** A launch configuration's harness: `harness`, or `runtime`, its pre-0.27 name (0.26.0
+ *  deployments wrote it) — read either (lead call 6). */
+export const launchConfigHarness = (entry) => (Object.hasOwn(entry, "harness") ? entry.harness : entry.runtime);
 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
@@ -521,8 +525,9 @@ export function validateLaunchConfig(name, entry, where) {
   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(", ")}`);
+  for (const key of Object.keys(entry)) if (!LAUNCH_CONFIG_KEYS.has(key)) bad(`has an unsupported key ${JSON.stringify(key)} (harness, executable, args, env, model, yolo)`);
+  if (Object.hasOwn(entry, "harness") && Object.hasOwn(entry, "runtime") && entry.harness !== entry.runtime) bad(`names harness ${JSON.stringify(entry.harness)} and runtime ${JSON.stringify(entry.runtime)}: \`runtime\` is the pre-0.27 name of \`harness\` — keep one`);
+  if (!LAUNCH_HARNESSES.includes(launchConfigHarness(entry))) bad(`needs harness: one of ${LAUNCH_HARNESSES.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) {
@@ -563,7 +568,8 @@ export function launchConfigsAt(dir) {
   validateLaunchConfigs(map, found.path);
   const source = dirname(found.path);
   for (const [name, entry] of Object.entries(map || {})) {
-    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, shadows: [] };
+    if (!Object.hasOwn(entry, "harness")) noteRuntimeName(`launch-configs.${name}.runtime in ${found.path}`);
+    out[name] = { name, harness: launchConfigHarness(entry), ...(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, shadows: [] };
   }
   return out;
 }
@@ -640,6 +646,18 @@ function validateCapabilityManifest(m, mf) {
  *
  * `__proto__` starts with `_`, so a JSON document's own `__proto__` key is
  * dropped here too rather than re-assigned through the inherited setter. */
+/** A flat soul.yaml names its harness `harness:` (0.27.0) or, as released
+ *  souls and capability-defined agents do (oats.aweb 1.13.1), `runtime:` —
+ *  set both, read either until no released package writes `runtime`. Both,
+ *  disagreeing, is refused. Returns the soul with `harness` only. */
+export function soulHarnessField(soul, file) {
+  if (!soul || !Object.hasOwn(soul, "runtime")) return soul;
+  const { runtime, ...rest } = soul;
+  if (Object.hasOwn(soul, "harness") && soul.harness !== runtime) {
+    throw oatsError("E_BAD_MANIFEST", `${file} declares harness: ${soul.harness} and runtime: ${runtime}; \`runtime\` is the pre-0.27 name of \`harness\` — keep one`, { file, harness: soul.harness, runtime });
+  }
+  return { ...rest, harness: Object.hasOwn(soul, "harness") ? soul.harness : runtime };
+}
 export function stripInternalAnnotations(parsed) {
   const out = {};
   for (const key of Object.keys(parsed)) if (!key.startsWith("_")) out[key] = parsed[key];
@@ -1150,7 +1168,7 @@ export function planInstanceResources({ resolved, soulDir, agent, contextDir, co
   return expected;
 }
 
-// ---------- runtime packages (satisfied by a runtime's own package manager) ----------
+// ---------- harness packages (satisfied by a harness's own package manager) ----------
 
 /** pi's config dir, officially relocatable via PI_CODING_AGENT_DIR (pi
  * docs/usage.md). Hard-coding ~/.pi/agent reports an installed package as
@@ -1160,14 +1178,14 @@ export function planInstanceResources({ resolved, soulDir, agent, contextDir, co
  * package root sends lookups to the wrong tree (reviewer-ad1b9f0). */
 const piAgentDir = (env = process.env) => env.PI_CODING_AGENT_DIR || join(env.HOME || "", ".pi", "agent");
 
-/** Runtimes whose own package manager can satisfy a requirement. A runtime
- * package is NOT a command on PATH: it is registered with the runtime, so both
- * detection and post-install verification read that runtime's package list.
- * Null-prototype: `runtime:` comes from a soul or a package manifest, and
- * `RUNTIME_PACKAGE_MANAGERS[runtime]` must answer for the runtimes declared
+/** Harnesses whose own package manager can satisfy a requirement. A harness
+ * package is NOT a command on PATH: it is registered with the harness, so both
+ * detection and post-install verification read that harness's package list.
+ * Null-prototype: `harness:` comes from a soul or a package manifest, and
+ * `HARNESS_PACKAGE_MANAGERS[harness]` must answer for the harnesses declared
  * here and for nothing else — an inherited `constructor` would pass the
- * unknown-runtime gate and then be dereferenced as a manager. */
-export const RUNTIME_PACKAGE_MANAGERS = {
+ * unknown-harness gate and then be dereferenced as a manager. */
+export const HARNESS_PACKAGE_MANAGERS = {
   __proto__: null,
   pi: {
     scope: "user-level (pi packages)",
@@ -1253,15 +1271,15 @@ export const RUNTIME_PACKAGE_MANAGERS = {
     /** The executable is CONTEXT-SELECTED (oats-claude-config may name a wrapper
      * such as `claude-personal`). Probing and installing through the literal
      * `claude` would inspect a DIFFERENT account's plugins than the session
-     * actually launches with — passing preflight while the real runtime lacks
+     * actually launches with — passing preflight while the real harness lacks
      * the channel, or rejecting one that has it (reviewer-6f1bb9c). */
     bin: (opts) => opts?.bin || "claude",
-    argv: (spec, req, opts) => [RUNTIME_PACKAGE_MANAGERS.claude.bin(opts), "plugin", "install", String(spec)],
+    argv: (spec, req, opts) => [HARNESS_PACKAGE_MANAGERS.claude.bin(opts), "plugin", "install", String(spec)],
     /** A marketplace must be registered before installing from it, so the plan
      * is a SEQUENCE. Both steps are shown at the consent prompt: agreeing to a
      * plugin also means agreeing to the source it comes from. */
     steps: (spec, req, opts) => {
-      const bin = RUNTIME_PACKAGE_MANAGERS.claude.bin(opts);
+      const bin = HARNESS_PACKAGE_MANAGERS.claude.bin(opts);
       return [
         ...(req?.marketplace ? [[bin, "plugin", "marketplace", "add", String(req.marketplace)]] : []),
         [bin, "plugin", "install", String(spec)],
@@ -1275,7 +1293,7 @@ export const RUNTIME_PACKAGE_MANAGERS = {
     list: (env = process.env, opts = {}) => {
       let out;
       try {
-        out = probeExecFile(RUNTIME_PACKAGE_MANAGERS.claude.bin(opts), ["plugin", "list", "--json"],
+        out = probeExecFile(HARNESS_PACKAGE_MANAGERS.claude.bin(opts), ["plugin", "list", "--json"],
           { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 60000, env });
       } catch { return []; }
       let rows;
@@ -1292,7 +1310,7 @@ export const RUNTIME_PACKAGE_MANAGERS = {
           const owner = realPathOrNearest(r.projectPath);
           return target === owner || target.startsWith(owner + sep);
         })
-        // verifiedPresent is the "this runtime confirms presence without naming a
+        // verifiedPresent is the "this harness confirms presence without naming a
         // location" override, NOT a blanket exemption: Claude DOES report
         // installPath, and setting it unconditionally meant a stale registration
         // whose install directory had been deleted still satisfied the spawn
@@ -1318,13 +1336,13 @@ export function packageSpecIdentity(spec) {
   return `${prefix}${scoped ? "@" : ""}${at >= 0 ? body.slice(0, at) : body}`;
 }
 
-/** What the runtime reports about a required package: is it there, where did it
+/** What the harness reports about a required package: is it there, where did it
  * land, and does the user's entry filter its resources? A settings row alone is
  * NOT proof the capability's extension will load (reviewer-8518c49). */
-/** The installed version of a runtime package: neither pi's nor Claude's
+/** The installed version of a harness package: neither pi's nor Claude's
  *  listing reports one, so it is read from the package.json under the
  *  install directory the listing names; undefined when there is none. */
-export function installedRuntimePackageVersion(runtime, spec, status) {
+export function installedHarnessPackageVersion(harness, spec, status) {
   const dir = status?.dir;
   if (dir && existsSync(join(dir, "package.json"))) {
     try {
@@ -1342,11 +1360,11 @@ export function compareVersionTriples(a, b) {
   return 0;
 }
 
-export function runtimePackageStatus(runtime, spec, env = process.env, opts = {}) {
-  const mgr = RUNTIME_PACKAGE_MANAGERS[runtime];
+export function harnessPackageStatus(harness, spec, env = process.env, opts = {}) {
+  const mgr = HARNESS_PACKAGE_MANAGERS[harness];
   if (!mgr) return { installed: false };
-  const want = runtimePackageIdentity(runtime, spec);
-  const row = mgr.list(env, opts).find((r) => runtimePackageIdentity(runtime, r.source) === want);
+  const want = harnessPackageIdentity(harness, spec);
+  const row = mgr.list(env, opts).find((r) => harnessPackageIdentity(harness, r.source) === want);
   if (!row) return { installed: false };
   const filter = mgr.resourceFilter ? mgr.resourceFilter(spec, env) : undefined;
   return {
@@ -1357,7 +1375,7 @@ export function runtimePackageStatus(runtime, spec, env = process.env, opts = {}
     // No resolved directory means the package is configured but NOT installed:
     // pi omits the path line entirely in that case, so treating a missing line
     // as "fine" let a stale row through. A named directory that does not exist
-    // is the same condition, reported the same way. A runtime that confirms
+    // is the same condition, reported the same way. A harness that confirms
     // presence without naming a directory (Claude's plugin list) says so via
     // verifiedPresent, so it is not judged by a path it never reports.
     missingFiles: row.verifiedPresent ? false : (!row.dir || !existsSync(row.dir)),
@@ -1370,22 +1388,22 @@ export function runtimePackageStatus(runtime, spec, env = process.env, opts = {}
     extensionsDisabled: !!filter?.disabled,
   };
 }
-/** The identity of a runtime package, per that runtime's own naming. */
-export function runtimePackageIdentity(runtime, spec) {
-  const mgr = RUNTIME_PACKAGE_MANAGERS[runtime];
+/** The identity of a harness package, per that harness's own naming. */
+export function harnessPackageIdentity(harness, spec) {
+  const mgr = HARNESS_PACKAGE_MANAGERS[harness];
   return mgr?.identity ? mgr.identity(spec) : packageSpecIdentity(spec);
 }
 
-/** Gate: a runtime package spec must be a plain source token — no shell syntax,
+/** Gate: a harness package spec must be a plain source token — no shell syntax,
  * whitespace, path traversal, or option-looking leading dash. Fail closed. */
-export function safeRuntimePackageSpec(spec, runtime = "pi") {
-  const mgr = RUNTIME_PACKAGE_MANAGERS[runtime];
+export function safeHarnessPackageSpec(spec, harness = "pi") {
+  const mgr = HARNESS_PACKAGE_MANAGERS[harness];
   return mgr?.safeSpec ? mgr.safeSpec(spec) : false;
 }
 /** A marketplace/source token a requirement may register before installing.
  * No shell syntax, whitespace, traversal or leading dash — it is passed as argv,
  * but a hostile value would still name an attacker-chosen source. */
-export function safeRuntimeSourceRef(ref) {
+export function safeHarnessSourceRef(ref) {
   return typeof ref === "string" && /^[a-z0-9][\w.-]*(\/[a-z0-9][\w.-]*)*$/i.test(ref);
 }
 
@@ -1396,9 +1414,9 @@ export function safeRuntimeSourceRef(ref) {
  * plus the team/workspace facts (teamEnv: OATS_TEAM_SCOPE/_ID/_LABEL, OATS_WORKSPACE_NAME/_KEY);
  * cwd = the instance home. A hook may print JSON { meta, brief, warning, launch, env } — meta
  * is persisted per capability in instance.json (and fed back as OATS_META at retire), brief
- * is added to TASK.md, warning surfaces in the spawn result; launch maps runtime → extra
+ * is added to TASK.md, warning surfaces in the spawn result; launch maps harness → extra
  * launch-command arguments (spawn IS session start: the command built here is stored in
- * instance.json and runs in the tmux window; a capability integrating a runtime — e.g.
+ * instance.json and runs in the tmux window; a capability integrating a harness — e.g.
  * aweb's Claude Code channel plugin — contributes its flags this way). A hook the
  * capability declares REQUIRED fails the spawn and rolls it back; every other
  * hook failure is advisory and only warns. `env` contributes string environment
@@ -1417,10 +1435,10 @@ function validateHookEnvironment(capabilityID, value, owners, declarations) {
     throw new HookEnvironmentContractError(`${capabilityID} hook env requires a dotted lowercase alphanumeric vendor component; hyphen, @, and / forms cannot claim an environment namespace`);
   }
   const prefix = `${vendorComponent.toUpperCase()}_`;
-  // The runtime half of the same contract the manifest validator enforces:
+  // The harness half of the same contract the manifest validator enforces:
   // a hook may set names under its vendor prefix or under a namespace its
   // trusted manifest declared (environmentNamespaces), and only names the
-  // manifest listed. Manifest and runtime must permit exactly the same set.
+  // manifest listed. Manifest and harness must permit exactly the same set.
   const declared = declarations.get(capabilityID) || { names: new Set(), namespaces: [] };
   const allowed = [prefix, ...(declared.namespaces || [])];
   const accepted = {};
@@ -1577,8 +1595,8 @@ export function runLifecycleHooks(event, { home, instance, agentName, soulDir, s
       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.
+      // harnesses it answered launch args for, and which env names, under
+      // which settings and trust. A later start or harness 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)) {
@@ -1652,7 +1670,7 @@ function readSoul(agentDir, soulDir = soulOf(agentDir)) {
     try { const v = parseConfigData(text, { format: "yaml" }).value; if (v && typeof v === "object" && !Array.isArray(v)) parsed = v; }
     catch { /* unreadable as YAML: the flat view is what the classic readers saw */ }
   }
-  const soul = stripInternalAnnotations(parsed);
+  const soul = soulHarnessField(stripInternalAnnotations(parsed), p);
   soul._dir = agentDir;
   soul.name = soul.name || basename(agentDir);
   return soul;
@@ -1680,7 +1698,7 @@ function capabilityAgentMetadata(manifest, rel) {
   if (!soulDir || !soulFile) return undefined;
   // Read only contained identity metadata to decide whether this provider owns
   // the requested name. Full tree containment + trust happen after a match.
-  const soul = stripInternalAnnotations(withConfigFile(soulFile, () => parseYamlFlat(readFileSync(soulFile, "utf8"))));
+  const soul = soulHarnessField(stripInternalAnnotations(withConfigFile(soulFile, () => parseYamlFlat(readFileSync(soulFile, "utf8")))), soulFile);
   return { soulDir, soul, name: soul.name || basename(soulDir) };
 }
 /**
@@ -1928,7 +1946,7 @@ export function tmuxWindows(session = DEFAULT_TMUX_SESSION) {
 
 /**
  * Spawn an instance of `agent` (as returned by findAgent/listAgents).
- * o: { instance?, purpose?, name?, repo?, work?, runtime?, model?, task?, taskFile?, branch?, launch?, tmuxSession? }
+ * o: { instance?, purpose?, name?, repo?, work?, harness?, model?, task?, taskFile?, branch?, launch?, tmuxSession? }
  */
 /** The claude binary for a context: closest `oats-claude-config` (a one-line file
  * naming the binary, e.g. "claude-personal") walking up from contextDir wins; no
@@ -1949,15 +1967,15 @@ export function resolveClaudeBinary(contextDir) {
 }
 
 /** Resolve a model preference LIST (comma-separated "provider/id[:thinking]" patterns)
- * to the first entry whose provider/model is actually available to the runtime.
+ * to the first entry whose provider/model is actually available to the harness.
  * pi: checked against `pi --list-models <pattern>` (authenticated providers).
  * claude: pi-style patterns are translated (anthropic/<id> → <id>) or dropped —
  * claude takes aliases/bare claude-* ids only; nothing usable → "" (claude default).
  * codex: translate openai/openai-codex entries to native ids, otherwise use its default.
  * Probe failures: first entry wins (pi errors loudly at launch). */
-export function resolveModelPreference(model, runtime = "pi") {
+export function resolveModelPreference(model, harness = "pi") {
   const prefs = String(model || "").split(",").map((s) => s.trim()).filter(Boolean);
-  if (runtime === "codex") {
+  if (harness === "codex") {
     for (const pref of prefs) {
       const bare = pref.replace(/:[a-z]+$/i, "");
       if (!bare.includes("/")) return bare;
@@ -1966,10 +1984,10 @@ export function resolveModelPreference(model, runtime = "pi") {
     }
     return ""; // let Codex use its configured model rather than another provider's id
   }
-  if (runtime === "claude") {
+  if (harness === "claude") {
     // Claude accepts its aliases and bare claude-* ids — NOT pi-style
     // "provider/model[:thinking]" patterns. Agents whose soul default is a
-    // pi model are routinely runtime-overridden to claude; passing the pi
+    // pi model are routinely harness-overridden to claude; passing the pi
     // pattern through makes claude reject the model at launch (operator
     // report, dev-coordinator-claude-sessions). Translate anthropic-provider
     // entries to the bare id (strip provider + :thinking) and drop other
@@ -1983,7 +2001,7 @@ export function resolveModelPreference(model, runtime = "pi") {
     return "";
   }
   if (prefs.length <= 1) return prefs[0] || "";
-  if (runtime !== "pi") return prefs[0];
+  if (harness !== "pi") return prefs[0];
   for (const pref of prefs) {
     const bare = pref.replace(/:[a-z]+$/i, ""); // strip :<thinking> for the catalog probe
     const [provider, ...rest] = bare.split("/");
@@ -2003,9 +2021,9 @@ export function resolveModelPreference(model, runtime = "pi") {
 // "unrelated" is the no-link default (normalized away before recording).
 export const RELATIONS = ["child", "sibling", "parent", "unrelated"];
 
-/** Verify the runtime packages that ACTIVE capabilities require for `runtime`.
+/** Verify the harness packages that ACTIVE capabilities require for `harness`.
  *
- * Each comes from a declared runtime-package requirement, so the capability has
+ * Each comes from a declared harness-package requirement, so the capability has
  * stated the dependency and the user has consented to install it (`oats install`).
  * We verify PRESENCE and record provenance; we deliberately do NOT resolve the
  * extension's entry file. pi owns that resolution — its manifest supports globs
@@ -2017,7 +2035,13 @@ 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, { bin, env } = {}) {
+/** A harness-package requirement names its harness `harness` (0.27.0) or, as
+ *  released manifests do (oats.aweb), `runtime`: read either, exactly one. */
+export function requirementHarness(row) {
+  if (!row || typeof row !== "object") return undefined;
+  return Object.hasOwn(row, "harness") ? row.harness : row.runtime;
+}
+function verifyHarnessPackages(harness, resolved, contextDir, { bin, env } = {}) {
   const probeEnv = env || process.env;
   const found = [];
   const problems = [];
@@ -2026,61 +2050,63 @@ function verifyRuntimePackages(runtime, resolved, contextDir, { bin, env } = {})
   // `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) } : {}) };
+  const probeOpts = { context: contextDir, ...(bin ? { bin } : harness === "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;
+      if (!raw || typeof raw !== "object") continue;
+      if (Object.hasOwn(raw, "harness") && Object.hasOwn(raw, "runtime")) { problems.push(`${cap.id}: a requirement declares both \`harness\` and \`runtime\` (its pre-0.27 name); keep one`); continue; }
+      if (requirementHarness(raw) !== harness) continue;
       // A requirement may be conditional on the capability's effective
       // settings (`when: { delivery: "channel" }`): rows whose condition does
       // not hold are not requirements of this spawn at all.
       if (raw.when !== undefined && (!raw.when || typeof raw.when !== "object" || Array.isArray(raw.when))) { problems.push(`${cap.id}: a requirement's \`when\` must be an object of setting names to values`); continue; }
       if (raw.when && !Object.entries(raw.when).every(([k, v]) => String(cap.settings?.[k] ?? "") === String(v))) continue;
       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, probeEnv, probeOpts);
-      const mgr = RUNTIME_PACKAGE_MANAGERS[runtime];
+      if (!safeHarnessPackageSpec(spec, harness)) { problems.push(`${cap.id}: ${harness} package spec is not a plain source token (${JSON.stringify(spec)})`); continue; }
+      if (raw.marketplace !== undefined && !safeHarnessSourceRef(raw.marketplace)) { problems.push(`${cap.id}: marketplace is not a plain source reference (${JSON.stringify(raw.marketplace)})`); continue; }
+      const status = harnessPackageStatus(harness, spec, probeEnv, probeOpts);
+      const mgr = HARNESS_PACKAGE_MANAGERS[harness];
       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(" && ");
-      const remedy = `run \`oats install --accept-requirement ${runtime}:${runtimePackageIdentity(runtime, spec)} --dir ${contextDir}\`${direct ? ` (or \`${direct}\` directly)` : ""}`;
+      const remedy = `run \`oats install --accept-requirement ${harness}:${harnessPackageIdentity(harness, spec)} --dir ${contextDir}\`${direct ? ` (or \`${direct}\` directly)` : ""}`;
       // `ifInstalled: true`: the row constrains a package that may be absent
       // (an ambient extension must honour a contract IF it is there); absence
       // satisfies it. Without the flag, absence fails as before.
-      if (!status.installed) { if (raw.ifInstalled === true) continue; problems.push(`${cap.id} requires the ${runtime} package ${spec}, which is not installed — ${remedy}`); continue; }
+      if (!status.installed) { if (raw.ifInstalled === true) continue; problems.push(`${cap.id} requires the ${harness} package ${spec}, which is not installed — ${remedy}`); continue; }
       // A settings row is not proof the extension loads. Both of these leave the
       // capability silently absent, which is the loss this gate exists to stop.
-      if (status.unverified) { problems.push(`${cap.id} requires the ${runtime} package ${spec}: it is configured, but OATS could not verify it is installed (${status.unverified}) — a config entry is not an installation; ${remedy}`); continue; }
+      if (status.unverified) { problems.push(`${cap.id} requires the ${harness} package ${spec}: it is configured, but OATS could not verify it is installed (${status.unverified}) — a config entry is not an installation; ${remedy}`); continue; }
       if (status.missingFiles) {
         problems.push(status.dir
-          ? `${cap.id} requires the ${runtime} package ${spec}: ${runtime} lists it at ${status.dir}, but nothing is installed there — ${remedy}`
-          : `${cap.id} requires the ${runtime} package ${spec}: ${runtime} has it configured but reports no installed location, so it was never installed — ${remedy}`);
+          ? `${cap.id} requires the ${harness} package ${spec}: ${harness} lists it at ${status.dir}, but nothing is installed there — ${remedy}`
+          : `${cap.id} requires the ${harness} package ${spec}: ${harness} has it configured but reports no installed location, so it was never installed — ${remedy}`);
         continue;
       }
-      if (status.disabled) { problems.push(`${cap.id} requires the ${runtime} package ${spec}, which is installed but DISABLED, so it will not load — enable it (\`${probeOpts.bin || runtime} plugin enable ${spec}\` for Claude), or drop the capability for this soul`); continue; }
-      if (status.extensionsDisabled) { problems.push(`${cap.id} requires the ${runtime} package ${spec}, but your ${runtime} settings entry sets "extensions": [], which loads none of them — remove that filter, or drop the capability for this soul`); continue; }
+      if (status.disabled) { problems.push(`${cap.id} requires the ${harness} package ${spec}, which is installed but DISABLED, so it will not load — enable it (\`${probeOpts.bin || harness} plugin enable ${spec}\` for Claude), or drop the capability for this soul`); continue; }
+      if (status.extensionsDisabled) { problems.push(`${cap.id} requires the ${harness} package ${spec}, but your ${harness} settings entry sets "extensions": [], which loads none of them — remove that filter, or drop the capability for this soul`); continue; }
       // A floor on the installed version (`minVersion`), checked once presence
       // and loadability are settled: a package whose manifest states an older
       // version, or none, fails closed with the same remedy, since an old
       // extension that ignores a newer contract (AWEB_DELIVERY) is exactly
       // what the floor guards.
       if (raw.minVersion) {
-        const have = installedRuntimePackageVersion(runtime, spec, status);
-        if (!have) { problems.push(`${cap.id} requires the ${runtime} package ${spec} at ${raw.minVersion} or later, but its installed version cannot be established (no package manifest under its install directory) — ${remedy}`); continue; }
-        if (compareVersionTriples(have, raw.minVersion) < 0) { problems.push(`${cap.id} requires the ${runtime} package ${spec} at ${raw.minVersion} or later; ${have} is installed — ${remedy}`); continue; }
+        const have = installedHarnessPackageVersion(harness, spec, status);
+        if (!have) { problems.push(`${cap.id} requires the ${harness} package ${spec} at ${raw.minVersion} or later, but its installed version cannot be established (no package manifest under its install directory) — ${remedy}`); continue; }
+        if (compareVersionTriples(have, raw.minVersion) < 0) { problems.push(`${cap.id} requires the ${harness} package ${spec} at ${raw.minVersion} or later; ${have} is installed — ${remedy}`); continue; }
       }
       if (status.extensionsFilter?.length) {
         // Unverifiable, not merely auditable: proving the filter selects this
         // capability's extension means implementing pi's glob semantics, and
         // guessing here is how an instance ends up promising a channel it does
         // not have. A filter on other resource kinds (skills) is unaffected.
-        problems.push(`${cap.id} requires the ${runtime} package ${spec}, but your ${runtime} settings entry filters its extensions (${status.extensionsFilter.map((e) => JSON.stringify(e)).join(", ")}). OATS cannot verify that filter selects the required extension without reimplementing ${runtime}'s matcher — remove the "extensions" filter for this package (a skills-only filter is fine), or drop the capability for this soul`);
+        problems.push(`${cap.id} requires the ${harness} package ${spec}, but your ${harness} settings entry filters its extensions (${status.extensionsFilter.map((e) => JSON.stringify(e)).join(", ")}). OATS cannot verify that filter selects the required extension without reimplementing ${harness}'s matcher — remove the "extensions" filter for this package (a skills-only filter is fine), or drop the capability for this soul`);
         continue;
       }
-      found.push({ capability: cap.id, runtime, package: spec, identity: runtimePackageIdentity(runtime, spec), dir: status.dir, filtered: status.filtered });
+      found.push({ capability: cap.id, harness, package: spec, identity: harnessPackageIdentity(harness, spec), dir: status.dir, filtered: status.filtered });
     }
   }
   if (problems.length) {
-    throw oatsError("E_RUNTIME_RESOURCE_MISSING", `this instance runs on ${runtime}, and its active capabilities require runtime packages that are not installed:\n${problems.map((p) => `  ${p}`).join("\n")}`);
+    throw oatsError("E_HARNESS_RESOURCE_MISSING", `this instance runs on ${harness}, and its active capabilities require harness packages that are not installed:\n${problems.map((p) => `  ${p}`).join("\n")}`);
   }
   const seen = new Set();
   return found.filter((x) => (seen.has(x.identity) ? false : seen.add(x.identity))).sort((a, b) => a.identity.localeCompare(b.identity));
@@ -2089,16 +2115,37 @@ function verifyRuntimePackages(runtime, resolved, contextDir, { bin, env } = {})
 // ---------- 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
+// switch harness 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;
+// before recipes existed when no configuration is selected. Version 2 (0.27.0)
+// names the harness `harness`; version 1 (0.26.0 homes) said `runtime` and is
+// read as version 2 (upgradeLaunchRecipe); the next start or restart rewrites it.
+export const LAUNCH_RECIPE_VERSION = 2;
+/** A recorded recipe as this kernel reads it: version 1 `{runtime}` (0.26.0) is
+ *  version 2 `{harness}` (lead call 6: read either, write new). Anything else is
+ *  returned as it is, for assertLaunchRecipe to judge. */
+export function upgradeLaunchRecipe(recipe) {
+  if (!isPlainObject(recipe) || recipe.version !== 1 || Object.hasOwn(recipe, "harness")) return recipe;
+  const { runtime, ...rest } = recipe;
+  return { ...rest, version: LAUNCH_RECIPE_VERSION, harness: runtime };
+}
+/** A home's instance.json as this kernel reads it: 0.26.0 recorded `runtime` and a
+ *  version-1 recipe; both read as `harness` (lead call 6). Every reader of a home's
+ *  harness goes through here; the next start or restart writes the new names. */
+export function upgradeHomeMeta(meta, home) {
+  if (!isPlainObject(meta)) return meta;
+  const old = Object.hasOwn(meta, "runtime") || (isPlainObject(meta.launch) && meta.launch.version === 1 && !Object.hasOwn(meta.launch, "harness"));
+  if (!old) return meta;
+  noteRuntimeName(`instance.json of ${home || meta.home || meta.instance} (a 0.26.0 home: its next start or restart records harness)`);
+  const { runtime, ...rest } = meta;
+  return { ...rest, ...(runtime !== undefined || meta.harness !== undefined ? { harness: meta.harness ?? runtime } : {}), ...(meta.launch !== undefined ? { launch: upgradeLaunchRecipe(meta.launch) } : {}) };
+}
 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 deployment directory when relative) or the
- *  runtime's default (claude through oats-claude-config). Never executed. */
-export function resolveLaunchExecutable({ runtime, declared, declaringDir, contextDir }) {
+ *  harness's default (claude through oats-claude-config). Never executed. */
+export function resolveLaunchExecutable({ harness, declared, declaringDir, contextDir }) {
   if (declared) {
     if (declared.includes("/")) {
       const path = isAbsolute(declared) ? declared : resolve(declaringDir || contextDir, declared);
@@ -2107,10 +2154,10 @@ export function resolveLaunchExecutable({ runtime, declared, declaringDir, conte
     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 claudeBin = harness === "claude" ? resolveClaudeBinary(contextDir) : undefined;
+  const name = harness === "claude" ? claudeBin : harness;
   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)" : ""}` };
+  return { path: found || null, declared: null, resolvedFrom: harness === "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) {
@@ -2126,58 +2173,58 @@ 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
+ *  a frozen recipe's, or the soul's default), and from it the harness and
+ *  model. A named configuration is a unit: an explicit harness that disagrees
+ *  with it is refused. On an existing home, --harness 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. */
-/** Sentinel a caller passes as `model` to mean "the runtime's own default, not the configured/soul preference". */
+ *  model never crosses harnesses: explicit or configured model, else the
+ *  frozen model on the same harness, else the harness's native default. */
+/** Sentinel a caller passes as `model` to mean "the harness's own default, not the configured/soul preference". */
 export const NATIVE_DEFAULT_MODEL = "@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) {
+  if (wanted === undefined && frozen && !selection.harness) {
     // 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 };
+    config = { name: frozen.launchConfig || null, harness: frozen.harness, ...(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)`);
+    if (selection.harness && selection.harness !== config.harness) bad("E_LAUNCH_CONFIG_MISMATCH", `launch configuration ${wanted} starts ${config.harness}; --harness ${selection.harness} disagrees with it (select another configuration, or --launch-config none with --harness)`);
   }
-  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)`);
+  const harness = config?.harness || selection.harness || (frozen ? frozen.harness : agent?.harness || "pi");
+  if (!LAUNCH_HARNESSES.includes(harness)) bad("E_UNSUPPORTED_HARNESS", `unknown harness "${harness}" (pi|claude|codex)`);
   let model, modelSource;
-  // K6: an EXPLICIT "use the runtime's native default" is distinct from an
+  // K6: an EXPLICIT "use the harness's native default" is distinct from an
   // omitted model (which inherits the configuration's or soul's preference).
   const nativeDefault = selection.model === NATIVE_DEFAULT_MODEL || (selection.model && typeof selection.model === "object" && selection.model.kind === "native-default");
   const explicit = !nativeDefault && selection.model !== undefined && selection.model !== null && String(selection.model).trim() !== "";
   if (nativeDefault) {
     model = ""; modelSource = "native default (explicit)";
   } else 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`);
+    model = resolveModelPreference(String(selection.model), harness); modelSource = "explicit";
+    if (!model) bad("E_MODEL_UNKNOWN", `model preference ${JSON.stringify(selection.model)} has no entry usable by harness ${harness}; give a ${harness} 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}`);
+    model = config.frozen ? config.model : resolveModelPreference(config.model, harness); 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 harness ${harness}`);
   } 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
+    if (frozen.harness === harness) { model = frozen.model || ""; modelSource = model ? "recorded" : "native default"; }
+    else { model = ""; modelSource = "native default (harness changed)"; }
+  } else if (harness !== (agent?.harness || "pi")) {
+    // A soul's model preference belongs to the soul's harness; 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 };
+    model = ""; modelSource = "native default (harness differs from the soul's)";
+  } else { model = resolveModelPreference(agent?.model || "", harness); modelSource = model ? "soul default" : "native default"; }
+  return { config, harness, 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
@@ -2195,8 +2242,8 @@ export function launchEnvExports(recipe, env) { return launchEnvRefs(recipe, env
 
 /** 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
+ *  harness's own arguments, capability launch args, the task prompt. A
+ *  configuration's args go after the harness'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.
  *
@@ -2208,14 +2255,14 @@ export function launchEnvExports(recipe, env) { return launchEnvRefs(recipe, env
  *  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 { harness, executable, model, yolo } = recipe;
   const cfgArgs = (recipe.args || []).map(shq).join(" ");
-  const hookArgs = recipe.hooks?.launch?.[runtime] || "";
+  const hookArgs = recipe.hooks?.launch?.[harness] || "";
   const tail = `${cfgArgs ? ` ${cfgArgs}` : ""}${hookArgs ? ` ${hookArgs}` : ""}`;
   let cmdline;
-  if (runtime === "claude") {
+  if (harness === "claude") {
     cmdline = `${shq(executable)}${yolo ? " --dangerously-skip-permissions" : ""}${model ? ` --model ${shq(model)}` : ""}${tail} -- "$(cat TASK.md)"`;
-  } else if (runtime === "codex") {
+  } else if (harness === "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 {
@@ -2237,12 +2284,12 @@ export function renderLaunchRecipe(recipe, { home, instance, redact = false }) {
 /** Execution, not preview: mark pending before dispatch, then resolve native
  * storage inside the backend shell under the actual command environment.
  * The original executable/argv is exec'd unchanged after recording succeeds. */
-function nativeRecordCommand(command, home, runtime) {
+function nativeRecordCommand(command, home, harness) {
   const { tokens, binary } = parseLaunchCommand(command);
   const args = tokens.slice(binary + 1).filter(t => t.kind !== "prompt").map(t => t.value ?? t.text);
-  const id = prepareNativeStart(home, runtime);
+  const id = prepareNativeStart(home, harness);
   const recorder = join(PKG_ROOT, "packages", "record", "bin", "record-native-start.mjs");
-  const inner = `${shq(process.execPath)} ${shq(recorder)} ${shq(home)} ${shq(id)} ${shq(runtime)} ${shq(JSON.stringify(args))} && exec ${tokens.slice(binary).map(t => t.text).join(" ")}`;
+  const inner = `${shq(process.execPath)} ${shq(recorder)} ${shq(home)} ${shq(id)} ${shq(harness)} ${shq(JSON.stringify(args))} && exec ${tokens.slice(binary).map(t => t.text).join(" ")}`;
   return `${tokens.slice(0, binary).map(t => t.text).join(" ")} /bin/sh -c ${shq(inner)}`;
 }
 
@@ -2252,8 +2299,9 @@ function nativeRecordCommand(command, home, runtime) {
 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");
+  recipe = upgradeLaunchRecipe(recipe);
   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 (!LAUNCH_HARNESSES.includes(recipe.harness)) bad(`harness ${JSON.stringify(recipe.harness)}`);
   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");
@@ -2263,18 +2311,18 @@ export function assertLaunchRecipe(recipe, what) {
   if (!recipe.hooks || typeof recipe.hooks !== "object") bad("no hooks record");
   return recipe;
 }
-/** The runtime-package requirements that apply: declared for this runtime
+/** The harness-package requirements that apply: declared for this harness
  *  and, for a conditional row, holding under the provider's (captured)
  *  settings. Nothing else is probed or restricted. */
-export function applicableRequirements(runtime, providers) {
+export function applicableRequirements(harness, 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 });
+  for (const cap of providers || []) for (const r of cap.manifest?.requires || []) if (r && typeof r === "object" && requirementHarness(r) === harness && 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`;
+function requirementsWithArgsMessage(harness, providers, config) {
+  const rows = applicableRequirements(harness, providers);
+  return `launch configuration ${config?.name || "(recorded)"} passes arguments (${config.args.map((a) => JSON.stringify(a)).join(", ")}) that the ${harness} 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
@@ -2294,28 +2342,28 @@ export function planLaunch({ home, instance, meta, contextDir, agentLike, select
   // found walking up from the home) — never the context directory, which may be a
   // member clone outside the deployment.
   const chosen = resolveLaunchSelection({ launchConfigs: launchConfigs || (home ? launchConfigsAt(home) : resolvedCfg?.launchConfigs) || {}, agent: agentLike, frozen, selection });
-  const { config, runtime, model, modelSource } = chosen;
+  const { config, harness, 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 });
+    : resolveLaunchExecutable({ harness, 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.
+  if (exeProblem) fail("executable", "E_LAUNCH_EXECUTABLE", `launch configuration ${config?.name || "(harness default)"}: ${exeProblem}`); else problems.push({ check: "executable", ok: true, detail: `${executable.path} (${executable.resolvedFrom})` });
+  // Capability contributions: recorded at spawn with provenance; a harness
+  // switch needs the new harness's launch args from the same capabilities.
   let hooks = { launch: {}, env: {}, contributions: [], pending: true };
   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
+    // launch hook; a harness change needs the new harness's arguments from
+    // every capability that gave harness-specific ones; recorded arguments
     // of a capability the scope no longer trusts are not reused.
     try {
-      hooks = prepareLaunchHooks({ frozen, runtime, resolvedCfg, home, meta, contextDir, assertRoots });
+      hooks = prepareLaunchHooks({ frozen, harness, resolvedCfg, home, meta, contextDir, assertRoots });
       const current = new Map((resolvedCfg?.capabilities || []).map((c) => [c.id, c]));
       const untrusted = hooks.contributions.filter((c) => c.capability && current.has(c.capability) && !current.get(c.capability).trust?.trusted).map((c) => c.capability);
       const inactive = hooks.contributions.filter((c) => c.capability && !current.has(c.capability)).map((c) => c.capability);
       if (untrusted.length) fail("capabilities", "E_LAUNCH_PREPARATION", `${untrusted.join(", ")} contributed to this launch at spawn but is no longer trusted in the scope; respawn the instance; 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(", ")}` : ""}` });
+      else problems.push({ check: "capabilities", ok: true, detail: `${harness !== frozen.harness ? "prepared for the new harness" : "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") throw e;
       fail("capabilities", e.code, e.message);
@@ -2333,41 +2381,41 @@ export function planLaunch({ home, instance, meta, contextDir, agentLike, select
   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
+  // Harness 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
+  // executable, only when some requirement is declared for this harness 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 dir = launchManifestDir(home, meta); const manifest = dir ? capabilityManifest(p.id, dir) : undefined; return manifest ? { id: p.id, manifest, settings: p.settings } : null; }).filter(Boolean)
       : (resolvedCfg?.capabilities || []);
-    const declared = applicableRequirements(runtime, providers).length > 0;
+    const declared = applicableRequirements(harness, 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));
+      fail("harness-packages", "E_LAUNCH_PROBE_UNSUPPORTED", requirementsWithArgsMessage(harness, 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" });
+        verifyHarnessPackages(harness, { capabilities: providers }, contextDir, { ...(config?.executable || config?.frozen ? { bin: executable.path } : {}), env: launchEffectiveEnv({ base: env, hooksEnv: hooks.env, configEnv }) });
+        problems.push({ check: "harness-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("harness-packages", "E_HARNESS_PACKAGE", e.message); }
+    } else problems.push({ check: "harness-packages", ok: true, detail: "no harness package requirement declared for this harness; 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,
+    version: LAUNCH_RECIPE_VERSION, harness, launchConfig: config?.name || null, launchConfigSource: config?.source || null,
+    executable: executable.path || executable.declared || harness, 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, ...(hooks.meta ? { hookMeta: hooks.meta } : {}) };
+  const selectionSource = frozen ? (config?.frozen || (!config && !selection.launchConfig && !selection.harness) ? "frozen" : "config") : "config";
+  return { recipe, command, harness, model: model || undefined, modelSource, yolo, config, executable, preflight: problems, ok: problems.every((c) => c.ok), selectionSource, frozen, ...(hooks.meta ? { hookMeta: hooks.meta } : {}) };
 }
 /** The environment a planned launch runs under: the host's base, the
  *  capabilities' validated env, the configuration's literals and its
@@ -2460,17 +2508,17 @@ function* spawnBody(root, agent, o = {}) {
   const repoAbs = preparedDeployment ?? resolveExecutionContext(root, repoTarget, work);
   if (!repoAbs) throw oatsError("E_BAD_ARGS", `${agent.name}: no repository for a ${work} instance — pass --repo${work === "attached" ? " (the work tree's owner records none)" : ""}`);
   // Launch selection: a named configuration (explicit, or the soul's
-  // launch-config default), or none; the runtime and model follow from it.
-  // K6b: a preview's native probes (model catalogue, runtime packages) share
+  // launch-config default), or none; the harness and model follow from it.
+  // K6b: a preview's native probes (model catalogue, harness packages) share
   // ONE budget from here to the return; each probe is group-killed on timeout.
   const preflightStarted = Date.now(), preflightBudgetMs = o.preview === true ? (Number(process.env.OATS_PREVIEW_PREFLIGHT_BUDGET_MS) || 20000) : undefined;
   let preflight = { status: "complete", budgetMs: preflightBudgetMs ?? null };
   if (o.preview === true) previewPreflightBudget = { deadline: preflightStarted + preflightBudgetMs };
   let launchSelection;
-  try { launchSelection = resolveLaunchSelection({ launchConfigs: launchConfigsAt(root), agent, selection: { launchConfig: o.launchConfig, runtime: o.runtime, model: o.model } }); }
+  try { launchSelection = resolveLaunchSelection({ launchConfigs: launchConfigsAt(root), agent, selection: { launchConfig: o.launchConfig, harness: o.harness, model: o.model } }); }
   catch (e) { previewPreflightBudget = null; throw e; }
   const launchConfig = launchSelection.config;
-  const runtime = launchSelection.runtime;
+  const harness = launchSelection.harness;
   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
@@ -2807,17 +2855,17 @@ function* spawnBody(root, agent, o = {}) {
   const resolvedCfg = composition.resolved;
   const yolo = resolveYolo(o.yolo ?? launchSelection.configuredYolo);
   const expectedResources = planInstanceResources({ resolved: resolvedCfg, soulDir, agent, contextDir: repoAbs, composition, prepared: o.prepared });
-  // Runtime extensions selected by ACTIVE capabilities for THIS instance's
-  // runtime. Strict launch disables ambient extension discovery, so each one has
-  // to be named by path — and a required runtime package that is not installed
+  // Harness extensions selected by ACTIVE capabilities for THIS instance's
+  // harness. Strict launch disables ambient extension discovery, so each one has
+  // to be named by path — and a required harness package that is not installed
   // must fail here, loudly, rather than produce an instance that silently lost
-  // its channel. `--runtime` can override a soul default long after install-time
+  // its channel. `--harness` can override a soul default long after install-time
   // reconciliation, so this spawn-time check is the authoritative one.
 
   // Prerequisites must fail before creating a home, worktree, or identity.
-  const executable = resolveLaunchExecutable({ runtime, declared: launchConfig?.executable, declaringDir: launchConfig?.source, contextDir: repoAbs });
+  const executable = resolveLaunchExecutable({ harness, 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 bad = checkLaunchExecutable(executable.path); if (bad) throw oatsError("E_LAUNCH_EXECUTABLE", `launch configuration ${launchConfig?.name || "(harness 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`);
@@ -2826,8 +2874,8 @@ function* spawnBody(root, agent, o = {}) {
   // 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 ((launchConfig?.args || []).length && applicableRequirements(harness, resolvedCfg.capabilities).length) throw oatsError("E_LAUNCH_PROBE_UNSUPPORTED", `${requirementsWithArgsMessage(harness, resolvedCfg.capabilities, launchConfig)}; nothing was created`);
+  const harnessPackages = verifyHarnessPackages(harness, resolvedCfg, repoAbs, { ...(launchConfig?.executable ? { bin } : {}), env: launchEffectiveEnv({ base: process.env, configEnv: launchConfig?.env || {} }) });
   // Backend presence/startup (ensureHerdr) happens AFTER the decision fence
   // and the exclusive placement reservation below — a stale or losing apply
   // must not start a daemon. Preview never starts one either.
@@ -2857,7 +2905,7 @@ function* spawnBody(root, agent, o = {}) {
   // launch (inherited defaults re-resolved at apply must not drift silently).
   const buildDecision = () => {
     const d = { instance, home, branch: plannedBranch, base: plannedBase,
-      effective: { repo: repoAbs, work, runtime, model: model || null, launchConfig: launchConfig?.name ?? null, yolo: yolo ?? null, backend, // backend regardless of --no-launch: the decision is what WOULD launch
+      effective: { repo: repoAbs, work, harness, model: model || null, launchConfig: launchConfig?.name ?? null, yolo: yolo ?? null, backend, // backend regardless of --no-launch: the decision is what WOULD launch
         childSpawns: ownChildPolicy.allowed, relation: relation ? { kind: relation, anchor: { instance: relativeTo ?? null, agentsRoot: anchorHome ? dirname(dirname(dirname(anchorHome))) : null } } : null } };
     // Workspace model: the decision binds WHAT WILL BE MATERIALIZED — the
     // resolution revision (member commits, package commits, payloads). A member
@@ -2900,7 +2948,7 @@ function* spawnBody(root, agent, o = {}) {
       subject: o.subject ?? { soul: agent.name, agentsRoot: root, context: null },
       decision, preflight,
       backendStatus: launch ? { name: backend, installed: !!which(backend), started: false } : null,
-      runtime, model: model || null, modelSource: launchSelection.modelSource ?? null, launchConfig: launchConfig?.name ?? null, yolo, backend,
+      harness, model: model || null, modelSource: launchSelection.modelSource ?? null, launchConfig: launchConfig?.name ?? null, yolo, backend,
       branch: plannedBranch, base: plannedBase, worktree: work === "worktree" ? join(home, "work") : null,
       relation: relation || null, parentInstance: parentInstance && parentInstance !== instance ? parentInstance : null,
       policy: { childSpawns: ownChildPolicy }, executable: bin, capabilities: preparedCapabilities,
@@ -2944,7 +2992,7 @@ function* spawnBody(root, agent, o = {}) {
       throw Object.assign(oatsError("E_PLACEMENT_TAKEN", `${instance} was taken by a concurrent spawn of another soul (${other}); nothing was created by this call — preview again`), { instance, home: other });
     }
   }
-  // TOCTOU: the placement checks above ran BEFORE composition and the runtime
+  // TOCTOU: the placement checks above ran BEFORE composition and the harness
   // package preflight, both of which shell out — a window in which anything able
   // to write in the agent directory can swap `instances/` for a link elsewhere,
   // and mkdirSync follows it (reviewer-a6aa1c5). Re-assert on the directory that
@@ -3229,7 +3277,7 @@ function* spawnBody(root, agent, o = {}) {
   const hookRes = runLifecycleHooks("spawn", {
     home, instance, agentName: agent.name, soulDir: homeSoulTarget, soulId: preparedSoulId, contextDir: repoAbs,
     workspaceDir: workspaceOf(root), rootDir: root, resolved: resolvedCfg,
-    extraEnv: { OATS_TASK: task, OATS_REPO: repoAbs, OATS_BRANCH: branch || "", OATS_WORK: work, OATS_RUNTIME: runtime, OATS_KIND: agent.kind || "persistent" },
+    extraEnv: { OATS_TASK: task, OATS_REPO: repoAbs, OATS_BRANCH: branch || "", OATS_WORK: work, OATS_HARNESS: harness, OATS_RUNTIME: harness, OATS_KIND: agent.kind || "persistent" },
   });
   warnings.push(...hookRes.warnings);
   // Which capability hooks RAN (in order) and how each ended — recorded on the
@@ -3258,7 +3306,7 @@ function* spawnBody(root, agent, o = {}) {
     const outstandingHooks = new Set();
     const outstandingGit = new Set();
     // A failed new-window command may still have created its window. Verify
-    // quiescence before removing credentials or work that runtime may be using.
+    // quiescence before removing credentials or work that harness may be using.
     if (windowMayExist && spawnHerdr) {
       try { stopHerdr(spawnHerdr); }
       catch (e) {
@@ -3387,7 +3435,7 @@ function* spawnBody(root, agent, o = {}) {
     let note;
     if (outstandingHooks.size || outstandingGit.size) {
       // Preserve credentials and the original hook receipt until cleanup
-      // succeeds. The runtime is stopped; Git cleanup was independently safe.
+      // succeeds. The harness is stopped; Git cleanup was independently safe.
       note = quarantineInstanceHome({
         home, instance, agent, soulDir: homeSoulTarget, soulId: preparedSoulId, incomplete,
         failed,
@@ -3434,15 +3482,15 @@ function* spawnBody(root, agent, o = {}) {
 You are instance "${instance}" of agent "${agent.name}".
 - Home: ${home}
 - Work tree: ./work — ${workDesc}
-- 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" : ""}
+- Do all repository work inside ./work. Read ./work/AGENTS.md or ./work/CLAUDE.md first if present.${briefLines}${harness === "codex" ? "\n## Harness 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: 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
+    // tmux window. Capabilities contributed harness-specific arguments and
     // environment through their spawn hook; both are recorded with provenance.
     const recipe = {
-      version: LAUNCH_RECIPE_VERSION, runtime,
+      version: LAUNCH_RECIPE_VERSION, harness,
       launchConfig: launchConfig?.name || null, launchConfigSource: launchConfig?.source || null,
       executable: bin, executableDeclared: executable.declared, executableResolvedFrom: executable.resolvedFrom,
       args: [...(launchConfig?.args || [])], env: { ...(launchConfig?.env || {}) },
@@ -3458,7 +3506,7 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
     const moduleSkills = (materializeOutcome?.skills || []).map((row) => ({ name: row.name, source: `module:${row.module}`, from: join(home, row.from) }));
     const meta = {
       agent: agent.name, kind: agent.kind || "persistent", instance, home, soulDir: homeSoulTarget,
-      repo: repoAbs, work, branch, runtime, model: model || undefined,
+      repo: repoAbs, work, branch, harness, model: model || undefined,
       ...(yolo !== undefined ? { yolo } : {}),
       parentInstance: parentInstance && parentInstance !== instance ? parentInstance : undefined,
       siblingInstance: siblingInstance && siblingInstance !== instance ? siblingInstance : undefined,
@@ -3493,19 +3541,19 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
           instructions: composition.blocks.map((b) => ({ source: b.source, file: b.file })),
           // `filtered` records that the operator's settings entry narrows this
           // package's resources. A non-empty filter is a deliberate choice whose
-          // glob semantics belong to the runtime, so it is auditable here rather
+          // glob semantics belong to the harness, so it is auditable here rather
           // than second-guessed at spawn.
-          runtimePackages: runtimePackages.map((x) => ({ capability: x.capability, runtime: x.runtime, package: x.package, dir: x.dir, filtered: x.filtered, loadedBy: "runtime-discovery" })),
+          harnessPackages: harnessPackages.map((x) => ({ capability: x.capability, harness: x.harness, package: x.package, dir: x.dir, filtered: x.filtered, loadedBy: "harness-discovery" })),
           // What this instance ACTUALLY sees beyond the OATS-composed set. Recorded
           // so the deviation from strict composition is auditable instead of
           // implied — the honest contract, not an aspiration.
-          runtimePosture: runtime === "claude"
+          harnessPosture: harness === "claude"
             ? {
               oatsComposed: "skills via .claude/skills -> ../.agents/skills; instructions via CLAUDE.md -> AGENTS.md",
               ambient: ["user skills", "project and ancestor skills to the repository root", "user and project plugins", "user and project settings", "user and ancestor CLAUDE.md"],
               why: "founder ruling: Claude Code's own global and per-repo configuration stays enabled — it is powerful, and the operator decides. An all-OATS setup is the way to opt out.",
             }
-            : runtime === "codex" ? {
+            : harness === "codex" ? {
               oatsComposed: "skills via .agents/skills; instructions via AGENTS.md; task via initial prompt",
               ambient: ["user and ancestor instructions", "user, project, admin and system skills", "user and project configuration and MCP servers"],
               why: yolo ? "Codex keeps native configuration with approval prompts and sandbox disabled by the OATS yolo setting." : "Codex keeps the operator's native configuration and approval policy, including approval handling for work paths outside the home.",
@@ -3544,7 +3592,7 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
 
     spawnTmux = meta.tmux;
     if (work === "directory") assertDirectoryRoots(home, homeReal);
-    const executionCommand = launch ? nativeRecordCommand(cmdline, home, runtime) : null;
+    const executionCommand = launch ? nativeRecordCommand(cmdline, home, harness) : null;
     if (launch && backend === "herdr") {
       windowMayExist = true;
       spawnHerdr = allocateHerdr(herdrBase, { home, instance });
@@ -3565,7 +3613,7 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
       meta.tmux.socket = tmuxSocket(session);
       meta.launched = true;
       // Commit the final child metadata and its independent byte authority before
-      // the managed runtime can write. No child-home transition follows launch.
+      // the managed harness can write. No child-home transition follows launch.
       writeFileSync(join(home, "instance.json"), JSON.stringify(meta, null, 2) + "\n");
       writeRetirementBaseline(home, join(home, "work"), work, resolvedCfg.capabilities, { launched: true, tmux: meta.tmux });
       // Wrap the command so the window drops into an interactive shell when the
@@ -3609,8 +3657,8 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
       }
     }
 
-    appendEvent(home, { kind: "spawned", data: { agent: agent.name, work, branch: branch ?? null, runtime, model: model || null, parentInstance: meta.parentInstance ?? null, relation: relation ?? null, launched: launch, hooks: hookReceipt(hookRes) } });
-    if (launch) appendEvent(home, { kind: "launched", data: { runtime, backend, launchConfig: launchConfig?.name ?? null } });
+    appendEvent(home, { kind: "spawned", data: { agent: agent.name, work, branch: branch ?? null, harness, model: model || null, parentInstance: meta.parentInstance ?? null, relation: relation ?? null, launched: launch, hooks: hookReceipt(hookRes) } });
+    if (launch) appendEvent(home, { kind: "launched", data: { harness, backend, launchConfig: launchConfig?.name ?? null } });
     if (o.idempotencyKey !== undefined) {
       // Only now is the spawn a finished receipt a same-key retry may replay.
       meta.spawnCompleted = true;
@@ -3632,8 +3680,8 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
 export function servedIdentityOf(meta) {
   const cm = meta?.capabilityMeta;
   if (!cm || typeof cm !== "object") return null;
-  const runtime = Array.isArray(meta.capabilityRuntime) ? meta.capabilityRuntime : [];
-  const messaging = runtime.filter((c) => c && c.layer === "messaging").map((c) => c.id);
+  const harness = Array.isArray(meta.capabilityRuntime) ? meta.capabilityRuntime : [];
+  const messaging = harness.filter((c) => c && c.layer === "messaging").map((c) => c.id);
   const pick = (ids) => { for (const id of ids) { const v = cm[id]?.identity; if (v && typeof v === "object" && !Array.isArray(v)) return { ...v, provider: id }; } return null; };
   return pick(messaging) ?? pick(Object.keys(cm));
 }
@@ -3656,7 +3704,7 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION) {
         const metaPath = join(instancesDir, e.name, "instance.json");
         const home = join(instancesDir, e.name);
         const meta = existsSync(metaPath)
-          ? JSON.parse(readFileSync(metaPath, "utf8"))
+          ? upgradeHomeMeta(JSON.parse(readFileSync(metaPath, "utf8")), home)
           : { instance: e.name, home };
         // A home retained by an incomplete rollback is NOT a live instance: it
         // is preserved state awaiting cleanup, and must read that way.
@@ -4450,10 +4498,10 @@ export function capturedProviders(meta, frozen) {
 }
 /** 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. */
-export function prepareLaunchHooks({ frozen, runtime, resolvedCfg, home, meta, contextDir, extraEnv = {}, assertRoots }) {
+ *  for the target harness; side-effect-free by contract; spawn hooks are
+ *  never re-run). A harness change needs the new harness's launch arguments
+ *  from every capability that contributed harness-specific ones. */
+export function prepareLaunchHooks({ frozen, harness, resolvedCfg, home, meta, contextDir, extraEnv = {}, assertRoots }) {
   const contributions = (frozen.hooks?.contributions || []).map((c) => ({ ...c }));
   const env = { ...(frozen.hooks?.env || {}) };
   const refreshed = [];
@@ -4463,7 +4511,7 @@ export function prepareLaunchHooks({ frozen, runtime, resolvedCfg, home, meta, c
   // 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.
+  // prepares the target harness under its CAPTURED settings.
   const ctx = launchManifestDir(home, meta);
   const withLaunchHook = [];
   let hookMeta;
@@ -4476,9 +4524,9 @@ export function prepareLaunchHooks({ frozen, runtime, resolvedCfg, home, meta, c
     if (hooks.launch) withLaunchHook.push({ id: p.id, capability: p.id, manifest, layer: p.contribution?.layer ?? p.binding?.layer ?? manifest.layer ?? null, level: p.contribution?.level ?? p.binding?.level ?? null, settings: p.settings, hooks, trust, environment: [...(manifest.environment || [])], environmentNamespaces: [...(manifest.environmentNamespaces || [])], missingRequires: [] });
   }
   if (withLaunchHook.length) {
-    const res = runLifecycleHooks("launch", { assertRoots, home, instance: meta.instance, agentName: meta.agent, soulDir: instanceSoulDir(home, meta), contextDir: ctx, rootDir: dirname(dirname(dirname(home))), resolved: { ...(resolvedCfg || {}), capabilities: withLaunchHook }, priorMeta: meta.capabilityMeta || {}, extraEnv: { OATS_RUNTIME: runtime, OATS_PREVIOUS_RUNTIME: frozen.runtime || "", ...extraEnv } });
+    const res = runLifecycleHooks("launch", { assertRoots, home, instance: meta.instance, agentName: meta.agent, soulDir: instanceSoulDir(home, meta), contextDir: ctx, rootDir: dirname(dirname(dirname(home))), resolved: { ...(resolvedCfg || {}), capabilities: withLaunchHook }, priorMeta: meta.capabilityMeta || {}, extraEnv: { OATS_HARNESS: harness, OATS_PREVIOUS_HARNESS: frozen.harness || "", OATS_RUNTIME: harness, OATS_PREVIOUS_RUNTIME: frozen.harness || "", ...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  ")}`);
+    if (failed.length) throw oatsError("E_LAUNCH_PREPARATION", `a capability could not prepare the ${harness} 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.
@@ -4506,8 +4554,8 @@ export function prepareLaunchHooks({ frozen, runtime, resolvedCfg, home, meta, c
     // retire undid the wrong one. Carry it to the caller; the start records it.
     hookMeta = res.meta && Object.keys(res.meta).length ? res.meta : undefined;
   }
-  const unprepared = contributions.filter((c) => !refreshed.includes(c.capability) && c.launch && c.launch[frozen.runtime] !== undefined && c.launch[runtime] === undefined).map((c) => c.capability);
-  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 unprepared = contributions.filter((c) => !refreshed.includes(c.capability) && c.launch && c.launch[frozen.harness] !== undefined && c.launch[harness] === undefined).map((c) => c.capability);
+  if (unprepared.length) throw oatsError("E_LAUNCH_PREPARATION", `${unprepared.join(", ")} contributed ${frozen.harness} launch arguments at spawn and none for ${harness}; 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) { for (const [rt, args] of Object.entries(c.launch || {})) if (args) launch[rt] = `${launch[rt] ? `${launch[rt]} ` : ""}${args}`; }
   return { launch, env, contributions, refreshed, ...(hookMeta ? { meta: hookMeta } : {}) };
@@ -4559,7 +4607,7 @@ export function startInstanceSession(home, o = {}) {
   const lock = join(realHome, ".oats-start.lock");
   const pendingPath = join(realHome, ".oats-start-pending.json");
   const exitedPath = join(realHome, ".oats-start-exited");
-  const readMeta = () => { try { return JSON.parse(readFileSync(metaPath, "utf8")); } catch (e) { throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `cannot read ${metaPath}: ${e.message}`); } };
+  const readMeta = () => { try { return upgradeHomeMeta(JSON.parse(readFileSync(metaPath, "utf8")), realHome); } catch (e) { throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `cannot read ${metaPath}: ${e.message}`); } };
   // Workspace-model homes only (lead decision c3 Q2): a home an earlier kernel
   // spawned records no modules, and there is no scope configuration left to
   // re-resolve it against. Retire still works on it.
@@ -4575,7 +4623,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, launch, runtime: newRuntime, yolo: newYolo, stop, nativeRecordId, hookMeta }, clearPending = true) => {
+  const record = (meta, { id, backend, target, model, command, startedAt, reused, launch, harness: newHarness, yolo: newYolo, stop, nativeRecordId, hookMeta }, clearPending = true) => {
     checkRoots();
     const baselinePath = retirementBaselinePath(realHome);
     let baseline;
@@ -4590,7 +4638,7 @@ export function startInstanceSession(home, o = {}) {
     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),
-      ...(launch ? { launch } : {}), ...(newRuntime ? { runtime: newRuntime } : {}), ...(newYolo !== undefined ? { yolo: newYolo } : {}),
+      ...(launch ? { launch } : {}), ...(newHarness ? { harness: newHarness } : {}), ...(newYolo !== undefined ? { yolo: newYolo } : {}),
       // Launch-hook meta lands per capability over the spawn's record; a hook
       // that answered without meta keeps its previous entry (retire reads it).
       ...(hookMeta ? { capabilityMeta: { ...(meta.capabilityMeta || {}), ...hookMeta } } : {}) };
@@ -4598,7 +4646,7 @@ export function startInstanceSession(home, o = {}) {
     else { next.tmux = { session: target.session, window: target.window, socket: resolve(target.socket) }; delete next.sessionTarget; }
     writeJsonAtomic(metaPath, next);
     if (clearPending) { checkRoots(); rmSync(pendingPath, { force: true }); }
-    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, ...(nativeRecordId ? { nativeRecordId } : {}), ...(stop ? { stop } : {}) };
+    return { instance: meta.instance, agent: meta.agent, home: realHome, harness: next.harness, backend, model: model ?? null, launchConfig: next.launch?.launchConfig ?? null, yolo: next.yolo ?? null, target, startedAt, restartCount: next.restartCount, reused, ...(nativeRecordId ? { nativeRecordId } : {}), ...(stop ? { stop } : {}) };
   };
   try { mkdirSync(lock); }
   catch (e) {
@@ -4622,7 +4670,7 @@ export function startInstanceSession(home, o = {}) {
       try { parseLaunchCommand(pending?.command); validCommand = true; } catch { /* preserve invalid receipt below */ }
       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?.harness !== undefined && !LAUNCH_HARNESSES.includes(pending.harness)) 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)
@@ -4652,9 +4700,9 @@ export function startInstanceSession(home, o = {}) {
         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`);
+          // now (model, configuration, harness, yolo) was not applied to it.
+          if (o.model != null && String(o.model).trim() && resolveModelPreference(String(o.model), done.harness || meta.harness) !== done.model) throw oatsError("E_SESSION_RUNNING", `${meta.instance} is already running with its previously requested model; its target was recovered, but the new model was not applied`);
+          if (o.launchConfig !== undefined || o.harness !== undefined || o.yolo !== undefined) throw oatsError("E_SESSION_RUNNING", `${meta.instance} is already running (its pending start was recovered); the requested launch configuration, harness or yolo was not applied; stop it, or use session restart`);
           if (meta.startId === pending.id) throw oatsError("E_SESSION_RUNNING", `${meta.instance} is already running; nothing was started`);
           return done;
         }
@@ -4663,8 +4711,8 @@ export function startInstanceSession(home, o = {}) {
     // 2. The ordinary gate and observation, all under the lock.
     const receipt = instanceSessionTarget(realHome);
     const meta = readMeta();
-    const runtime = meta.runtime;
-    if (!["pi", "claude", "codex"].includes(runtime)) throw oatsError("E_LAUNCH_COMMAND_UNSUPPORTED", `instance ${meta.instance || realHome} records runtime ${JSON.stringify(runtime)}, which this kernel cannot relaunch`);
+    const harness = meta.harness;
+    if (!["pi", "claude", "codex"].includes(harness)) throw oatsError("E_LAUNCH_COMMAND_UNSUPPORTED", `instance ${meta.instance || realHome} records harness ${JSON.stringify(harness)}, which this kernel cannot relaunch`);
     const backend = meta.sessionTarget || meta.backend === "herdr" ? "herdr" : "tmux";
     let command = meta.command;
     let model = meta.model || undefined;
@@ -4672,7 +4720,7 @@ export function startInstanceSession(home, o = {}) {
     // 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 selected = o.launchConfig !== undefined || o.harness !== undefined || o.yolo !== undefined;
     const hasRecipe = meta.launch && typeof meta.launch === "object";
     let launchPlan = null;
     if (selected || hasRecipe) {
@@ -4686,12 +4734,12 @@ export function startInstanceSession(home, o = {}) {
       // launch hook re-checks joined memberships against them (teams contract decision 6).
       const resolvedCfg = resolvedFromHome(realHome, meta, { teams: o.teams, teamsSource: o.teamsSource });
       let agent; try { agent = findAgent(dirname(dirname(dirname(realHome))), meta.agent); } catch { agent = undefined; }
-      const plan = planLaunch({ home: realHome, instance: meta.instance, meta, contextDir: context, agentLike: agent || { runtime: meta.runtime, model: meta.model, yolo: meta.yolo }, selection: { launchConfig: o.launchConfig, runtime: o.runtime, model: o.model, yolo: o.yolo }, resolvedCfg, env: o.env || process.env, assertRoots: checkRoots });
-      launchPlan = { recipe: plan.recipe, command: plan.command, runtime: plan.runtime, model: plan.model, yolo: plan.yolo, ...(plan.hookMeta ? { hookMeta: plan.hookMeta } : {}) };
+      const plan = planLaunch({ home: realHome, instance: meta.instance, meta, contextDir: context, agentLike: agent || { harness: meta.harness, model: meta.model, yolo: meta.yolo }, selection: { launchConfig: o.launchConfig, harness: o.harness, model: o.model, yolo: o.yolo }, resolvedCfg, env: o.env || process.env, assertRoots: checkRoots });
+      launchPlan = { recipe: plan.recipe, command: plan.command, harness: plan.harness, model: plan.model, yolo: plan.yolo, ...(plan.hookMeta ? { hookMeta: plan.hookMeta } : {}) };
       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`);
+      const resolved = resolveModelPreference(String(o.model), harness);
+      if (!resolved) throw oatsError("E_MODEL_UNKNOWN", `model preference ${JSON.stringify(o.model)} has no entry usable by harness ${harness}; give a ${harness} model id`);
       command = withLaunchModel(command, resolved);
       model = resolved;
     } else parseLaunchCommand(command);
@@ -4703,7 +4751,7 @@ export function startInstanceSession(home, o = {}) {
     const paneEnvFlags = paneEnv.flatMap((r) => ["-e", `${r.name}=${r.value}`]);
     const paneEnvExports = paneEnv.map((r) => `export ${r.name}=${shq(r.value)}; `).join("");
     checkRoots(); // launch hooks/preparation have run; no backend has been observed
-    const planExtra = launchPlan ? { launch: launchPlan.recipe, runtime: launchPlan.runtime, yolo: launchPlan.yolo,
+    const planExtra = launchPlan ? { launch: launchPlan.recipe, harness: launchPlan.harness, yolo: launchPlan.yolo,
       ...(launchPlan.hookMeta ? { hookMeta: launchPlan.hookMeta } : {}) } : {};
     let target = receipt.target;
     let state = { present: false, state: "not-launched" };
@@ -4722,7 +4770,7 @@ export function startInstanceSession(home, o = {}) {
       // 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);
+      writeJsonAtomic(join(realHome, ".oats-restart.json"), { instance: meta.instance, at: new Date().toISOString(), stop: stopReceipt, next: { harness: launchPlan?.harness || harness, launchConfig: launchPlan?.recipe?.launchConfig ?? meta.launch?.launchConfig ?? null, model: model ?? null } }, 0o600);
       appendEvent(realHome, { kind: stopReceipt.exited ? "restarted" : "stop-refused", data: { phase: "restart-stop", signal: stopReceipt.signal, waitedMs: stopReceipt.waitedMs, stillRunning: stopReceipt.stillRunning ?? [] } });
       if (!stopReceipt.exited) throw oatsError("E_SESSION_STOP_FAILED", `${meta.instance} was asked to stop (${stopReceipt.signal} to ${stopReceipt.requested.map((r) => `${r.comm} pid ${r.pid}`).join(", ")} at ${stopReceipt.sentAt}) and was still running after ${stopReceipt.waitedMs} ms (${stopReceipt.state}); nothing was escalated and nothing was started; stop it yourself, or retry with a longer --stop-grace. Receipt: ${join(realHome, ".oats-restart.json")}`);
       try { state = inspectSessionTarget(target, o.io); } catch (e) { if (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}`); }
@@ -4731,7 +4779,7 @@ export function startInstanceSession(home, o = {}) {
     const startedAt = new Date().toISOString();
     const id = randomUUID();
     checkRoots();
-    const executionCommand = nativeRecordCommand(command, realHome, launchPlan?.runtime || runtime);
+    const executionCommand = nativeRecordCommand(command, realHome, launchPlan?.harness || harness);
     const completedCommand = `${executionCommand}; oats_start_status=$?; printf '%s\\n' ${shq(id)} > ${shq(exitedPath)}`;
     let reused = "new";
     if (backend === "herdr") {
@@ -4998,7 +5046,7 @@ function preserveRetirementWork(observation, meta, instance) {
   const staging = mkdtempSync(join(recoveryRoot, `.${instance}-`));
   const recovery = join(recoveryRoot, basename(staging).slice(1));
   try {
-    // A home-only change (notes, runtime files, credentials) needs a home
+    // A home-only change (notes, harness files, credentials) needs a home
     // snapshot, not another copy of an otherwise disposable clean worktree.
     // In-progress Git operations retain the full standalone recovery even
     // when porcelain status has no changed paths.
@@ -5093,7 +5141,7 @@ process.exitCode = completeDeferredRetirement(JSON.parse(process.env.OATS_RETIRE
 /** Self-retire (aweb-abep): persist intent, then hand the retirement to a
  *  detached process that runs it as an ORDINARY external retirement after the
  *  caller's window has died. Nothing destructive happens in the caller: no
- *  inspection, no hooks, no removal — the runtime is still alive, and the
+ *  inspection, no hooks, no removal — the harness is still alive, and the
  *  quiesce rule stays intact. The child owns its own process group so the
  *  tmux window kill (SIGHUP to the pane's group) cannot take it down, and the
  *  caller's instance env is stripped so the child is an external operator,
@@ -5293,19 +5341,19 @@ export function retireInstance(root, name, o = {}) {
   const directory = meta.work === "directory";
   const isWorktree = !directory && (meta.work === "worktree" ||
     (existsSync(workPath) && !lstatSync(workPath).isSymbolicLink()));
-  // A live runtime cannot establish a stable final work inspection of itself,
+  // A live harness cannot establish a stable final work inspection of itself,
   // so self-retire never inspects, runs hooks, or removes anything here. It
   // persists the intent and hands the whole retirement to a detached process
-  // that runs it as an ordinary EXTERNAL retirement once the runtime is gone
+  // that runs it as an ordinary EXTERNAL retirement once the harness is gone
   // (aweb-abep). `--keep-dir` keeps the old in-process path: nothing to inspect.
   if (self && (!o.keepDir || meta.sessionTarget)) {
     return scheduleDeferredSelfRetirement(root, found, name, o, session);
   }
   // First inspection is non-destructive. Only after it succeeds may OATS quiesce
-  // the managed runtime; recovery copying never races a live managed Pi.
+  // the managed harness; recovery copying never races a live managed Pi.
   const branchDeletion = { delete: !!(o.deleteBranch || quarantine), repo: meta.repo, branch: meta.branch };
   const initialObservation = inspectRetirementWork(found.home, workPath, isWorktree, { branchDeletion, directory });
-  // Runtime identity is destructive authority. The mutable child metadata may
+  // Harness identity is destructive authority. The mutable child metadata may
   // describe it for humans, but only the independent baseline can authorize the
   // endpoint that proves quiescence.
   let runtimeAuthority;