@awebai/oats 0.26.0 → 0.27.0

package/lib/deprecation.mjs

@@ -0,0 +1,24 @@
+/** lib/deprecation.mjs — the one deprecated-name warning a command answers with.
+ *
+ * runtime → harness (0.27.0, lead decision call 6): persisted inputs and CLI flags
+ * written before 0.27.0 keep working — read either, write new — and every read of
+ * the old spelling is noted here. A command answers with ONE warning naming what
+ * it read (the JSON envelope's `warnings[]`, or stderr in text mode), never more.
+ */
+const sources = new Set();
+
+/** Note one read of `runtime` where `harness` is meant; `where` names the key's home. */
+export function noteRuntimeName(where) { sources.add(where); }
+
+/** The command's one `deprecated-runtime-name` warning, or null when nothing old was read. */
+export function runtimeNameWarning() {
+  if (!sources.size) return null;
+  const list = [...sources];
+  return {
+    code: "deprecated-runtime-name", key: "runtime", replacement: "harness", sources: list,
+    message: `\`runtime\` was renamed to \`harness\` in 0.27.0; the old name is still read here (${list.join("; ")}) and a later release drops it`,
+  };
+}
+
+/** For tests: forget what was noted. */
+export function resetRuntimeNames() { sources.clear(); }

package/lib/instance-inspect.mjs

@@ -14,7 +14,7 @@ import { spawnSync } from "node:child_process";
 import { accessSync, constants as fsConstants, existsSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { capabilityManifests, instanceSoulDir, manifestOperations, parseYamlNested, servedIdentityOf, teamEnv, withConfigFile } from "./core.mjs";
+import { capabilityManifests, instanceSoulDir, manifestOperations, parseYamlNested, servedIdentityOf, teamEnv, upgradeHomeMeta, withConfigFile } from "./core.mjs";
 import { discoverOrStandalone, findSoulEntry, liveTeams, prepareInstance } from "./instance-resolution.mjs";
 import { declaredSettings } from "./capability-contract.mjs";
 import { kernelCompatibility, teamLabelsOf, teamsOf } from "./resolve.mjs";
@@ -75,6 +75,7 @@ function readTextCapped(file, cap = 200_000) {
  *  messaging provider (a non-messaging operation) gets the record at no remote cost. */
 export async function homeTarget(home, meta, { remoteOptions, discover = true, live: readLive = true } = {}) {
   const realHome = real(home);
+  meta = upgradeHomeMeta(meta, realHome);
   // Only the home's own module copies: without <home>/.oats/modules the kernel's
   // manifest lookup would fall through to a classic config chain — never here.
   let manifests = {}; const loadProblems = [];
@@ -190,7 +191,7 @@ function capabilityRows(t) {
 function soulRow(t) {
   const s = t.soul, def = obj(s.definition) ? s.definition : {};
   return { soulsApi: SOULS_API, name: s.name, repoKey: s.repoKey, commit: s.commit, team: s.team, kind: s.external === true ? "external" : s.external === false ? "member" : null, path: s.path,
-    description: def.description ?? null, work: def.work ?? null, runtime: def.runtime ?? null, model: def.model ?? null,
+    description: def.description ?? null, work: def.work ?? null, harness: def.harness ?? null, model: def.model ?? null,
     declarations: declarationsOf(s.definition), declarationProblems: s.problems,
     instructions: s.soulDir ? readTextCapped(join(s.soulDir, "AGENTS.md")) : null };
 }
@@ -210,7 +211,7 @@ export function inspectDocument(t, { kernel }) {
     // live for a home (`teamsSource: "recorded"` when its workspace could not be read now).
     teams: t.teams ?? null, teamsSource: t.teamsSource ?? null,
     knowledge: kcap ? { provider: kcap.id, version: kcap.version, operations: kcap.operations.map((o) => ({ name: o.name, kind: o.kind, available: o.available, reason: o.reason })) } : { provider: null, version: null, operations: [] },
-    instance: m ? { home: t.home, instance: m.instance, agent: m.agent, runtime: m.runtime || null, model: m.model ?? null, yolo: m.yolo ?? null, launched: !!m.launched, createdAt: m.createdAt || null,
+    instance: m ? { home: t.home, instance: m.instance, agent: m.agent, harness: m.harness || null, model: m.model ?? null, yolo: m.yolo ?? null, launched: !!m.launched, createdAt: m.createdAt || null,
       resolution: m.workspace?.resolution ?? null, soulDir: t.soul.soulDir, instructions: { ...readTextCapped(join(t.home, "AGENTS.md")), sources: m.instructions || [] } } : null,
     ...(m ? { identity: servedIdentityOf(m) } : {}),
     problems: [...t.soul.problems, ...(t.discoveryError ? [t.discoveryError] : []),

package/lib/process-group.mjs

@@ -1,5 +1,5 @@
 /** Kill a detached child's whole process group (e.g. git + its remote helper /
- *  ssh, or a runtime probe + what it forked). ONLY for a child that was actually
+ *  ssh, or a harness probe + what it forked). ONLY for a child that was actually
  *  spawned: a failed spawn (ENOENT) reports `pid: 0`, and `process.kill(-0)` /
  *  `process.kill(0)` address the CALLER's own process group — the operator's
  *  shell, tmux session or Desktop backend. Returns whether anything was signalled. */

package/lib/remote.mjs

@@ -581,7 +581,7 @@ function posixNormalize(p) {
 }
 /**
  * The ONE symlink an OATS tree may carry (decision 13): a `CLAUDE.md` whose target
- * is `AGENTS.md` beside it — the Claude-runtime alias of the canonical
+ * is `AGENTS.md` beside it — the Claude-harness alias of the canonical
  * instructions. Souls carry it at their root; a capability's agents/<name>/ dirs
  * carry it too. Anything else stays refused. The rule is on the PATH (any depth,
  * basename CLAUDE.md); fetchRemoteTree still enforces the target constraint

package/lib/schedule.mjs

@@ -28,12 +28,13 @@ import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Cron } from "croner";
 import { loadLocal } from "./workspace.mjs";
+import { noteRuntimeName } from "./deprecation.mjs";
 import { RESERVED_LAUNCH_ENV, MAX_INSTANCE_NAME, findAgent, findInstanceHomes, inspectInstanceSession, inputInstanceSession, startInstanceSession, retirePendingMarkerPath } from "./core.mjs";
 
 export const SCHEDULE_FILE = "oats-schedules.json";
 export const SCHEDULE_API = 2;
 const ID_RE = /^[a-z0-9-]{1,40}$/;
-const RUNTIMES = new Set(["pi", "claude", "codex"]);
+const HARNESSES = new Set(["pi", "claude", "codex"]);
 const BACKENDS = new Set(["tmux", "herdr"]);
 const MESSAGE_MAX = 256 * 1024;
 const OATS_BIN = join(dirname(fileURLToPath(import.meta.url)), "..", "bin", "oats.mjs");
@@ -58,6 +59,10 @@ export function scheduleExecutionStatus(def, intent, lock) {
 /** The definition keys of a captured (versioned) schedule. That path was removed in 0.26. */
 export const CAPTURED_SCHEDULE_KEYS = Object.freeze(["definitionVersion", "recurrencePolicy", "execution", "preparation"]);
 const CAPTURED_SCHEDULE_REMOVED = "captured schedules are refused (the captured/portable path was removed in 0.26); remove this job, or re-add it without definitionVersion, recurrencePolicy, execution and preparation";
+/** runtime → harness (0.27.0, lead call 6: read either, write new): a definition's
+ *  `runtime` is its `harness`. Stored jobs are read with the new name (readDefinitions)
+ *  and the next write stores it; a job naming both, differently, is invalid on its own. */
+export const HARNESS_CONFLICT = "harness and runtime (its pre-0.27 name) disagree: keep harness: and remove runtime:";
 export function shapeError(def) {
   if (!def || typeof def !== "object" || Array.isArray(def)) return "definition is not an object";
   if (!["spawn", "command", "wake", "operation"].includes(def.kind)) return `kind ${JSON.stringify(def.kind)} is not spawn, command, wake or operation`;
@@ -69,6 +74,7 @@ export function shapeError(def) {
   // A stored captured (versioned) definition is never evaluated or run (removed in 0.26): it reads
   // as invalid, migration required, on that job only.
   if (CAPTURED_SCHEDULE_KEYS.some((key) => def[key] !== undefined)) return CAPTURED_SCHEDULE_REMOVED;
+  if (def.runtime !== undefined && def.harness !== undefined && def.runtime !== def.harness) return HARNESS_CONFLICT;
   return null;
 }
 
@@ -133,6 +139,14 @@ function writeJson(path, value) {
 }
 export function readDefinitions(ws) {
   const doc = readJsonBounded(definitionsPath(ws), { version: 1, jobs: {} }, "definitions").value;
+  if (doc.jobs && typeof doc.jobs === "object" && !Array.isArray(doc.jobs)) {
+    for (const [id, def] of Object.entries(doc.jobs)) {
+      if (!def || typeof def !== "object" || Array.isArray(def) || def.runtime === undefined) continue;
+      noteRuntimeName(`schedule ${id} in ${definitionsPath(ws)} (its next save records harness)`);
+      if (def.harness === undefined) { const { runtime, ...rest } = def; doc.jobs[id] = { ...rest, harness: runtime }; }
+      else if (def.harness === def.runtime) { const { runtime, ...rest } = def; void runtime; doc.jobs[id] = rest; }
+    }
+  }
   if (![1, 2].includes(doc.version) || typeof doc.jobs !== "object" || doc.jobs === null || Array.isArray(doc.jobs)) throw scheduleError("E_SCHEDULE_INVALID", `${definitionsPath(ws)} must be {version: 1|2, jobs: {}}`, { field: "file" });
   return doc;
 }
@@ -297,7 +311,12 @@ export function validateDefinition(ws, def, { checkAgent = true } = {}) {
       if (derived.length > MAX_INSTANCE_NAME) throw scheduleError("E_SCHEDULE_INVALID", `${out.purpose !== undefined ? "purpose" : "id"}: runs would be named ${out.agent}-${stem}-<YYYYMMDDHHMM> (${derived.length} characters); instance names are at most ${MAX_INSTANCE_NAME} characters — shorten the ${out.purpose !== undefined ? "purpose" : "schedule id (or set a shorter purpose)"}`, { field: out.purpose !== undefined ? "purpose" : "id" }); }
     if (typeof def.task !== "string" || !def.task.trim()) throw scheduleError("E_SCHEDULE_INVALID", "task: non-empty text", { field: "task" });
     out.task = def.task;
-    if (def.runtime !== undefined) { if (!RUNTIMES.has(def.runtime)) throw scheduleError("E_SCHEDULE_INVALID", "runtime: pi, claude or codex", { field: "runtime" }); out.runtime = def.runtime; }
+    if (def.runtime !== undefined) {
+      if (def.harness !== undefined && def.harness !== def.runtime) throw scheduleError("E_SCHEDULE_INVALID", HARNESS_CONFLICT, { field: "runtime" });
+      noteRuntimeName(`schedule ${id}: runtime (written as harness)`);
+      def = { ...def, harness: def.runtime };
+    }
+    if (def.harness !== undefined) { if (!HARNESSES.has(def.harness)) throw scheduleError("E_SCHEDULE_INVALID", "harness: pi, claude or codex", { field: "harness" }); out.harness = def.harness; }
     if (def.model !== undefined) { if (typeof def.model !== "string") throw scheduleError("E_SCHEDULE_INVALID", "model: string", { field: "model" }); out.model = def.model; }
     if (def.yolo !== undefined) { if (typeof def.yolo !== "boolean") throw scheduleError("E_SCHEDULE_INVALID", "yolo: boolean", { field: "yolo" }); out.yolo = def.yolo; }
     if (def.wake !== undefined) {
@@ -352,13 +371,13 @@ export function nextRunAfter(def, from) { const n = cronOf(def).nextRun(from); r
 /** Due exactly at this minute: the first run after (minute - 1 s) is this minute. */
 export function dueAt(def, minute) { const n = cronOf(def).nextRun(new Date(minute.getTime() - 1000)); return !!n && n.getTime() === minute.getTime(); }
 export function purposeSuffix(minute) { return minute.toISOString().slice(0, 16).replace(/[-T:]/g, ""); }
-/** Ordering key for admission: when this job last launched a runtime. */
+/** Ordering key for admission: when this job last launched a harness. */
 export function launchOrderKey(js) { return String(js?.lastLaunchedAt || ""); }
 
 // ---------------------------------------------------------- observation
 
 /** What a run's instance looks like now. Home gone = ended; a home that is
- *  retiring is still there (its runtime may be alive pending teardown) and
+ *  retiring is still there (its harness may be alive pending teardown) and
  *  keeps its slot; present but no running harness = stopped (needs
  *  attention, never removed); running = active; not inspectable = unknown. */
 export function observeHome(home, io) {
@@ -371,7 +390,7 @@ export function observeHome(home, io) {
     if (retiring) return { outcome: "active", note: "retiring: home present, teardown pending" };
     // A shell right after `session start` is that launch's startup phase
     // until its wrapper writes the exit marker for the launch id; only then
-    // (or with no start receipt at all) is a shell a finished runtime.
+    // (or with no start receipt at all) is a shell a finished harness.
     if (s.present && s.state === "shell" && startupInProgress(home)) return { outcome: "starting" };
     return { outcome: "stopped" };
   } catch (e) { return { outcome: "unknown", error: e.message }; }
@@ -417,7 +436,7 @@ function childEnv() {
   for (const key of [...RESERVED_LAUNCH_ENV,
     "OATS_DEPLOYMENT", "OATS_RESOLUTION", "OATS_CAPABILITY", "OATS_LAYER", "OATS_LEVEL", "OATS_META", "OATS_OPERATION",
     "OATS_REPO", "OATS_BRANCH", "OATS_WORK", "OATS_KIND", "OATS_TASK",
-    "OATS_RUNTIME", "OATS_PREVIOUS_RUNTIME", "OATS_RETIRE_INTENT",
+    "OATS_HARNESS", "OATS_PREVIOUS_HARNESS", "OATS_RUNTIME", "OATS_PREVIOUS_RUNTIME", "OATS_RETIRE_INTENT",
     "OATS_TEAM_NAME", "OATS_TEAM_ID", "OATS_TEAM_SCOPE",
   ]) delete env[key];
   return env;
@@ -443,7 +462,7 @@ export function workspaceSpawnContext(ws) {
 function spawnViaCli(ws, root, agent, opts, context, io) {
   if (context.error) throw scheduleError(context.error.code, `this deployment realizes a workspace (${context.dir}) but its oats-local.yaml cannot be read: ${context.error.message}`);
   const argv = ["spawn", agent.name, "--dir", context.dir, "--agents-root", root, "--purpose", opts.purpose, "--json"];
-  if (opts.runtime) argv.push("--runtime", opts.runtime);
+  if (opts.harness) argv.push("--harness", opts.harness);
   if (opts.model) argv.push("--model", opts.model);
   if (opts.backend) argv.push("--backend", opts.backend);
   if (opts.repo) argv.push("--repo", opts.repo);
@@ -479,7 +498,7 @@ function spawnViaCli(ws, root, agent, opts, context, io) {
 function launchSpawn(ws, def, minute, io) {
   const { root, agent } = resolveScheduledAgent(ws, def);
   const purpose = `${def.purpose || def.id}-${purposeSuffix(minute)}`;
-  const opts = { task: def.task.trimEnd() + scheduleBlock(def, minute), purpose, runtime: def.runtime, model: def.model, yolo: def.yolo, backend: def.backend, repo: def.repo, launch: io?.noLaunch === true ? false : true };
+  const opts = { task: def.task.trimEnd() + scheduleBlock(def, minute), purpose, harness: def.harness, model: def.model, yolo: def.yolo, backend: def.backend, repo: def.repo, launch: io?.noLaunch === true ? false : true };
   let r;
   if (io?.spawn) r = io.spawn(root, agent, opts);
   else r = spawnViaCli(ws, root, agent, opts, workspaceSpawnContext(ws), io);
@@ -561,7 +580,7 @@ function validateActiveExecution(js, lock) {
 }
 /** One wake. `startIfStopped` false between due minutes (a harness that
  *  keeps exiting is not restarted every minute); `canStart` false when the
- *  host bound is reached (a new runtime takes a slot; a delivery does not). */
+ *  host bound is reached (a new harness takes a slot; a delivery does not). */
 /** A failure message that reports effects the kernel could not undo or
  *  confirm (spawn compensation's "rollback INCOMPLETE", a quarantined or
  *  retained home): the launch's effects are unconfirmed, never a confirmed
@@ -580,14 +599,14 @@ function performWake(def, io, { startIfStopped = true, canStart = true, reserve
     // The slot is persisted BEFORE the start call and kept on ANY start
     // exception: an error code does not prove nothing was allocated (core
     // can refuse while recording, after the session exists). The next
-    // observation releases it once the runtime is proven stopped or absent;
+    // observation releases it once the harness is proven stopped or absent;
     // at worst a refused start occupies a slot for one tick.
     if (reserve && !reserve()) return { kind: "wake", action: "skipped", reason: "the job's slot is held by another process; delivery pending", pending: true };
     try {
       const r = (io?.start || startInstanceSession)(def.home);
-      return { kind: "wake", action: "started", instance: r.instance, target: r.target, home: def.home, incarnation: incarnationOfHome(def.home), reason: "session was stopped; the message is pending until the session is active", pending: true, startedRuntime: true };
+      return { kind: "wake", action: "started", instance: r.instance, target: r.target, home: def.home, incarnation: incarnationOfHome(def.home), reason: "session was stopped; the message is pending until the session is active", pending: true, startedHarness: true };
     } catch (e) {
-      return { kind: "wake", action: "skipped", reason: `start did not complete (${e.code || "error"}): ${e.message}; the slot is kept until the session is observed stopped or absent`, error: e.message, errorCode: e.code, pending: true, startedRuntime: "unconfirmed" };
+      return { kind: "wake", action: "skipped", reason: `start did not complete (${e.code || "error"}): ${e.message}; the slot is kept until the session is observed stopped or absent`, error: e.message, errorCode: e.code, pending: true, startedHarness: "unconfirmed" };
     }
   }
   try {
@@ -602,9 +621,9 @@ function performWake(def, io, { startIfStopped = true, canStart = true, reserve
 
 /** Observe the previous run of one job. The tracked identity is what was
  *  launched (the lock's or lastRun's home), never the current definition,
- *  so an edit cannot make a slot forget its runtime. A wake slot is held
- *  while its started runtime is active, starting, unknown or retiring and
- *  released when that runtime is proven stopped (the start receipt's exit
+ *  so an edit cannot make a slot forget its harness. A wake slot is held
+ *  while its started harness is active, starting, unknown or retiring and
+ *  released when that harness is proven stopped (the start receipt's exit
  *  marker) or its home is gone: a persistent home outliving its process
  *  does not keep a slot. */
 function observePrevious(ws, id, def, js, io, now, { mutate }) {
@@ -624,7 +643,7 @@ function observePrevious(ws, id, def, js, io, now, { mutate }) {
     if (seen.outcome === "ended" || seen.outcome === "stopped") {
       releaseJobLock(ws, id);
       if (seen.outcome === "ended") delete js.pendingWake;
-      if (lr) js.lastRun = { ...lr, ...(seen.outcome === "ended" ? { endedAt: now.toISOString() } : { stoppedAt: now.toISOString() }), note: seen.outcome === "ended" ? "started runtime ended" : "started runtime stopped; slot released" };
+      if (lr) js.lastRun = { ...lr, ...(seen.outcome === "ended" ? { endedAt: now.toISOString() } : { stoppedAt: now.toISOString() }), note: seen.outcome === "ended" ? "started harness ended" : "started harness stopped; slot released" };
     }
     return;
   }
@@ -654,7 +673,7 @@ export function tickWorkspace(ws, { now = new Date(), io, reg, wsList, dryRun =
   // `candidates` (the host tick) means the host already observed every scope.
   if (!candidates) for (const [id, def] of Object.entries(defs.jobs)) observePrevious(ws, id, def, stateOf(id), io, now, { mutate: !dryRun });
   if (observeOnly) { if (!dryRun) writeState(ws, st); return considered; }
-  // Least recently LAUNCHED first: only an actual runtime launch counts, a
+  // Least recently LAUNCHED first: only an actual harness launch counts, a
   // skipped or pending job keeps its place at the front of the line.
   const order = (candidates || Object.keys(defs.jobs)).filter((id) => Object.prototype.hasOwnProperty.call(defs.jobs, id) && (!only || id === only)).sort((a, b) => launchOrderKey(st.jobs[a]).localeCompare(launchOrderKey(st.jobs[b])) || a.localeCompare(b));
   for (const id of order) {
@@ -671,7 +690,7 @@ export function tickWorkspace(ws, { now = new Date(), io, reg, wsList, dryRun =
       const held = !!jobLockInfo(ws, id);
       const canStart = held || liveLocks(wsAll) < bound;
       const run = performWake(def, io, { startIfStopped: dueNow, canStart, reserve: () => held || acquireJobLock(ws, id, { scheduledFor: js.pendingWake.scheduledFor, wake: true, home: def.home }) });
-      if (run.startedRuntime) js.lastLaunchedAt = now.toISOString();
+      if (run.startedHarness) js.lastLaunchedAt = now.toISOString();
       if (!existsSync(def.home)) releaseJobLock(ws, id);
       js.lastRun = { ...(js.lastRun || {}), ...run, outcome: run.action, completedPending: run.action === "delivered", pendingSince: js.pendingWake.scheduledFor, startedAt: js.lastRun?.startedAt || now.toISOString() };
       if (!run.pending) delete js.pendingWake;
@@ -700,7 +719,7 @@ export function tickWorkspace(ws, { now = new Date(), io, reg, wsList, dryRun =
       // one does, and the slot is held (the job lock) until that home ends.
       const holdsSlot = !!jobLockInfo(ws, id);
       const run = performWake(def, io, { startIfStopped: true, canStart: holdsSlot || liveLocks(wsAll) < bound, reserve: () => holdsSlot || acquireJobLock(ws, id, { scheduledFor: minute.toISOString(), wake: true, home: def.home }) });
-      if (run.startedRuntime) js.lastLaunchedAt = now.toISOString();
+      if (run.startedHarness) js.lastLaunchedAt = now.toISOString();
       if (!existsSync(def.home)) releaseJobLock(ws, id);
       if (run.pending) js.pendingWake = { scheduledFor: minute.toISOString() }; else delete js.pendingWake;
       js.lastRun = { scheduledFor: minute.toISOString(), startedAt: now.toISOString(), home: def.home, ...run, outcome: run.action, ...(run.instance ? { instance: run.instance } : {}) };
@@ -856,7 +875,7 @@ function incarnationOfHome(home) { try { const m = JSON.parse(readFileSync(join(
  *  transcript: there is no reader behind this block. */
 function sessionProvenanceOf(r) {
   if (!r || typeof r !== "object") return null;
-  const delivery = r.startedRuntime ? "launched" : r.action === "delivered" || r.outcome === "delivered" || r.completedPending ? "delivered-active" : r.launched === true || r.instance ? "launched" : "none";
+  const delivery = r.startedHarness || r.startedRuntime ? "launched" : r.action === "delivered" || r.outcome === "delivered" || r.completedPending ? "delivered-active" : r.launched === true || r.instance ? "launched" : "none";
   return { instance: typeof r.instance === "string" ? r.instance : null, home: typeof r.home === "string" ? r.home : null, incarnation: typeof r.incarnation === "string" ? r.incarnation : null, server: typeof r.server === "string" ? r.server : null, delivery };
 }
 /** Read-time projection of one job's stored history: bounded to

package/lib/servers.mjs

@@ -22,6 +22,7 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { parseStrictJson } from "./canonical-json.mjs";
+import { noteRuntimeName } from "./deprecation.mjs";
 
 const OATS_HOME_DIR = () => process.env.OATS_HOME_DIR || join(homedir(), ".oats");
 export const SERVERS_FILE = () => join(OATS_HOME_DIR(), "servers.json");
@@ -224,53 +225,64 @@ export function checkRemote(target, io = {}) {
   }
   // What the remote kernel advertises it can launch. A probe without these
   // fields is a 0.22.1-class kernel: pi and claude only, no session backend
-  // choice, no launch options; nothing newer may be requested of it.
+  // choice, no launch options; nothing newer may be requested of it. The
+  // harness list is named `harnesses` since 0.27.0; an older kernel names the
+  // same list `runtimes`, and is read in its own vocabulary (lead call 6).
   const list = (k, fallback) => (Array.isArray(probe[k]) ? probe[k].map(String) : fallback);
+  const harnessKey = Array.isArray(probe.harnesses) ? "harnesses" : "runtimes";
   return {
     version: probe.version, schemaVersion: 1, desktopApi: 1,
-    runtimes: list("runtimes", ["pi", "claude"]),
+    harnesses: list(harnessKey, ["pi", "claude"]),
     sessionBackends: list("sessionBackends", []),
     launchOptions: list("launchOptions", []),
     remote: list("remote", []),
     features: list("features", []),
     operationsApi: [1, 2].includes(probe.operationsApi) ? probe.operationsApi : null,
     scheduleApi: [1, 2].includes(probe.scheduleApi) ? probe.scheduleApi : null,
-    advertised: Array.isArray(probe.runtimes),
+    advertised: Array.isArray(probe[harnessKey]),
   };
 }
 
 /** Refuse, before any mutation, a spawn that asks the remote kernel for a
- *  runtime, session backend or launch option it does not advertise. The
- *  effective runtime is the --runtime flag or the soul's default from the
+ *  harness, session backend or launch option it does not advertise. The
+ *  effective harness is the --harness flag or the soul's default from the
  *  remote roster, resolved THERE, since the local roster says nothing about
  *  that host's souls. Desktop's local support check cannot prove remote
  *  support; this is the proof. */
+/** The client speaks the host's vocabulary (0.27.0, lead call 6): a host that does not
+ *  advertise the harness feature is asked with `--runtime`, the name it reads. */
+export function hostHarnessArgs(remote, args) {
+  if ((remote?.features || []).includes("harness")) return args;
+  return args.map((a) => (a === "--harness" ? "--runtime" : a.startsWith("--harness=") ? `--runtime=${a.slice("--harness=".length)}` : a));
+}
 export function checkRemoteSupport(remote, target, oatsArgs, roster) {
   const flagOf = (name) => { const i = oatsArgs.indexOf(name); return i >= 0 && oatsArgs[i + 1] && !oatsArgs[i + 1].startsWith("--") ? oatsArgs[i + 1] : undefined; };
   const agent = oatsArgs.find((a) => !a.startsWith("--"));
   const soul = (roster?.agents || []).find((a) => a.name === agent);
-  // The effective runtime is the flag, else the soul's default as the remote
-  // roster reports it. A soul the roster does not list with a runtime (a
+  // The effective harness is the flag, else the soul's default as the remote
+  // roster reports it. A soul the roster does not list with a harness (a
   // capability-defined agent, or one with no live instance) has no default
   // this side can establish: the remote kernel validates its own default at
   // spawn, and nothing is asserted here about it.
   const namedConfig = oatsArgs.includes("--launch-config");
-  const runtime = flagOf("--runtime") || (namedConfig ? undefined : soul?.runtime);
+  // --runtime is the pre-0.27 name of --harness; a roster row from a host before 0.27 says `runtime`.
+  const chosen = flagOf("--harness") || flagOf("--runtime");
+  const harness = chosen || (namedConfig ? undefined : soul?.harness ?? soul?.runtime);
   // What the message may claim depends on what was established: an
   // advertising remote said what it supports; a silent one (before 0.22.2)
   // said nothing, and only pi and claude are assumed of it.
   const supports = remote.advertised
-    ? `it advertises runtimes ${remote.runtimes.join(", ")}${remote.sessionBackends.length ? `, session backends ${remote.sessionBackends.join(", ")}` : ", no session backend choice"}${remote.launchOptions.length ? `, launch options ${remote.launchOptions.join(", ")}` : ", no launch options"}`
-    : `it does not advertise what it supports (kernels before 0.22.2 do not), so only pi and claude on tmux with no launch options are assumed of it; upgrade it there to use more`;
+    ? `it advertises harnesses ${remote.harnesses.join(", ")}${remote.sessionBackends.length ? `, session backends ${remote.sessionBackends.join(", ")}` : ", no session backend choice"}${remote.launchOptions.length ? `, launch options ${remote.launchOptions.join(", ")}` : ", no launch options"}`
+    : `it does not advertise its harnesses (kernels before 0.22.2 do not), so only pi and claude are assumed of it${remote.sessionBackends.length ? `, with session backends ${remote.sessionBackends.join(", ")}` : " on tmux"}${remote.launchOptions.length ? ` and launch options ${remote.launchOptions.join(", ")}` : " with no launch options"}; upgrade it there to use more`;
   const refuse = (what) => { throw serverError("E_REMOTE_INCOMPATIBLE", `remote oats ${remote.version} at ${target.sshHost}: ${what} was not established as supported there (${supports})`); };
   if (namedConfig && !remote.features.includes("launch-config")) refuse("a named launch configuration (the host must advertise launch-config)");
-  if (runtime && !remote.runtimes.includes(runtime)) refuse(`runtime ${runtime}${flagOf("--runtime") ? "" : ` (the default of soul ${agent} there)`}`);
+  if (harness && !remote.harnesses.includes(harness)) refuse(`harness ${harness}${chosen ? "" : ` (the default of soul ${agent} there)`}`);
   // A wake schedule at spawn is saved by the host: it must advertise schedules.
   if (["--wake-json", "--wake-every", "--wake-cron"].some((f) => oatsArgs.includes(f)) && !remote.features.includes("schedule")) refuse("a wake schedule at spawn (the host must advertise the schedule feature)");
   const backend = flagOf("--backend");
   if (backend && !remote.sessionBackends.includes(backend)) refuse(`session backend ${backend}`);
   if (oatsArgs.includes("--yolo") && !remote.launchOptions.includes("yolo")) refuse("the yolo launch option");
-  return { runtime, backend, yolo: oatsArgs.includes("--yolo") };
+  return { harness, backend, yolo: oatsArgs.includes("--yolo") };
 }
 
 /** The remote kernel version that carries `oats session` (inspect, input,
@@ -404,13 +416,13 @@ export function routeCommand(serverId, cmd, oatsArgs, io = {}) {
     const ii = oatsArgs.indexOf("--instance");
     const explicitName = ii >= 0 && oatsArgs[ii + 1] && !oatsArgs[ii + 1].startsWith("--") ? oatsArgs[ii + 1] : undefined;
     if (explicitName && readSnapshot(serverId, explicitName)) throw serverError("E_ROUTE_EXISTS", `a saved route for ${explicitName} through server ${serverId} already exists (${readSnapshot(serverId, explicitName).home}); retire it (oats retire ${explicitName} --server ${serverId}) or drop it (oats server forget ${serverId} --instance ${explicitName}) before spawning that name again`);
-    // The remote roster: the soul's runtime default for the support check,
+    // The remote roster: the soul's harness default for the support check,
     // and the remote agents root for the snapshot (the kernel's spawn result
     // does not carry it, and guessing it from the workspace would be wrong).
     const status = runRemote(target, json(withScope(["status"])), io).envelope;
     if (!status.ok) return { envelope: status, stderr: "" };
     checkRemoteSupport(remote, target, oatsArgs, status.result);
-    const { envelope, stderr } = runRemote(target, json(withScope(["spawn", ...oatsArgs])), io);
+    const { envelope, stderr } = runRemote(target, json(withScope(["spawn", ...hostHarnessArgs(remote, oatsArgs)])), io);
     if (envelope.ok && envelope.result?.instance) {
       // A generated name can still collide with a saved route of another
       // soul on the same host (dev --purpose foo-1 vs dev-foo --purpose 1).
@@ -576,7 +588,7 @@ export function rosterGroups({ server, io = {} } = {}) {
       g.probe = { ok: true };
       g.agentsRoot = status.result.root;
       for (const a of status.result.agents || []) {
-        g.souls.push({ name: a.name, runtime: a.runtime, work: a.work, backend: a.backend, description: a.description, agentsRoot: status.result.root });
+        g.souls.push({ name: a.name, harness: a.harness ?? a.runtime, work: a.work, backend: a.backend, description: a.description, agentsRoot: status.result.root });
         // A failed deferred self-retirement needs an operator: it rides with
         // the group, named by agent and instance, as `oats status` prints it.
         for (const f of a.retireFailures || []) g.retireFailures.push({ agent: a.name, ...f });
@@ -584,7 +596,7 @@ export function rosterGroups({ server, io = {} } = {}) {
           const snap = routeOf(i);
           g.instances.push({
             server: g.server, instance: i.instance, agent: a.name, home: i.home || snap?.home, agentsRoot: status.result.root,
-            runtime: i.runtime || null, backend: i.sessionTarget?.backend || (i.tmux ? "tmux" : null),
+            harness: i.harness || i.runtime || null, backend: i.sessionTarget?.backend || (i.tmux ? "tmux" : null),
             ...(i.sessionTarget ? { sessionTarget: i.sessionTarget } : {}), ...(i.tmux ? { tmux: i.tmux } : {}),
             running: typeof i.running === "boolean" ? i.running : null, ...(i.runtimeError ? { runtimeError: i.runtimeError } : {}),
             retirePending: !!i.retirePending, rollbackIncomplete: !!i.rollbackIncomplete, savedRoute: !!snap, missingRemotely: false,
@@ -597,7 +609,7 @@ export function rosterGroups({ server, io = {} } = {}) {
     // instance is gone there (retired, or its home removed) and the route is
     // stale; with a failed probe nothing is known. Same keys as remote rows.
     for (const snap of bySnapshot.values()) {
-      g.instances.push({ server: g.server, instance: snap.instance, agent: snap.agent, home: snap.home, agentsRoot: snap.agentsRoot, runtime: snap.runtime || null, backend: null, running: null, retirePending: false, rollbackIncomplete: false, savedRoute: true, missingRemotely: g.probe?.ok === true });
+      g.instances.push({ server: g.server, instance: snap.instance, agent: snap.agent, home: snap.home, agentsRoot: snap.agentsRoot, harness: snap.harness || snap.runtime || null, backend: null, running: null, retirePending: false, rollbackIncomplete: false, savedRoute: true, missingRemotely: g.probe?.ok === true });
     }
     delete g._snapshots;
   }
@@ -667,15 +679,15 @@ export function restartRemote(serverId, choices = {}, io = {}) {
   return launchRemoteSession(serverId, "restart", choices, io);
 }
 
-function remoteLaunchArgs({ launchConfig, runtime, model, yolo } = {}) {
+function remoteLaunchArgs({ launchConfig, harness, model, yolo } = {}) {
   const args = [];
   if (launchConfig !== undefined) {
     if (typeof launchConfig !== "string" || !/^[a-z0-9][a-z0-9._-]{0,63}$/i.test(launchConfig)) throw serverError("E_BAD_ARGS", "invalid launch configuration name");
     args.push("--launch-config", launchConfig);
   }
-  if (runtime !== undefined) {
-    if (!["pi", "claude", "codex"].includes(runtime)) throw serverError("E_BAD_ARGS", "runtime must be pi, claude or codex");
-    args.push("--runtime", runtime);
+  if (harness !== undefined) {
+    if (!["pi", "claude", "codex"].includes(harness)) throw serverError("E_BAD_ARGS", "harness must be pi, claude or codex");
+    args.push("--harness", harness);
   }
   if (model !== undefined && model !== null && model !== "") {
     if (typeof model !== "string" || model.startsWith("-") || model.includes("\0")) throw serverError("E_BAD_ARGS", "invalid model name");
@@ -693,7 +705,7 @@ function requireRemoteFeature(remote, target, feature) {
 }
 
 function launchRemoteSession(serverId, action, choices, io) {
-  const { instance, home, launchConfig, runtime, yolo } = choices;
+  const { instance, home, launchConfig, harness, yolo } = choices;
   const choiceArgs = remoteLaunchArgs(choices);
   const route = resolveRoute(serverId, { instance, home }, `session ${action}`);
   const remote = requireSessionRemote(route.target, io);
@@ -701,8 +713,8 @@ function launchRemoteSession(serverId, action, choices, io) {
     throw serverError("E_REMOTE_INCOMPATIBLE", `remote oats ${remote.version} at ${route.target.sshHost} does not advertise session-start (kernels from ${SESSION_START_REMOTE_VERSION} do); upgrade it there, or start the instance on that host`);
   }
   if (action === "restart") requireRemoteFeature(remote, route.target, "session-restart");
-  if (launchConfig !== undefined || runtime !== undefined || yolo !== undefined) requireRemoteFeature(remote, route.target, "launch-config");
-  const args = ["session", action, "--home", route.home, ...choiceArgs, "--json"];
+  if (launchConfig !== undefined || harness !== undefined || yolo !== undefined) requireRemoteFeature(remote, route.target, "launch-config");
+  const args = ["session", action, "--home", route.home, ...hostHarnessArgs(remote, choiceArgs), "--json"];
   const { envelope, stderr } = runRemote(route.target, args, io);
   return { envelope: envelope.ok ? { ...envelope, result: { ...envelope.result, server: serverId, instance: instance || route.snapshot?.instance || envelope.result.instance } } : envelope, stderr, route };
 }
@@ -711,6 +723,15 @@ function launchRemoteSession(serverId, action, choices, io) {
  * its saved route. Definitions travel on stdin, never as remote file paths or
  * shell arguments. The host resolves environment references and validates the
  * definition; this client never substitutes its own environment. */
+/** A launch definition in the host's vocabulary: `harness` for a host with the harness feature,
+ *  `runtime` for one before 0.27.0. Either spelling is read here; both, disagreeing, are refused. */
+function hostLaunchDefinition(remote, definition) {
+  const { harness, runtime, ...rest } = definition; // a disagreeing pair was refused before the probe
+  if (runtime !== undefined) noteRuntimeName("runtime in the launch configuration definition (sent as the host's harness key)");
+  const value = harness ?? runtime;
+  if (value === undefined) return rest;
+  return (remote?.features || []).includes("harness") ? { ...rest, harness: value } : { ...rest, runtime: value };
+}
 export function launchConfigRemote(serverId, options = {}, io = {}) {
   const { action, name, context, instance, home, soul, agentsRoot, definition, keepEnv } = options;
   if (!["list", "set", "remove", "preview"].includes(action)) throw serverError("E_BAD_ARGS", "unknown launch configuration action");
@@ -729,6 +750,7 @@ export function launchConfigRemote(serverId, options = {}, io = {}) {
     if (!definition || typeof definition !== "object" || Array.isArray(definition)) throw serverError("E_BAD_ARGS", "specify a launch configuration object");
     if (keepEnv !== undefined && typeof keepEnv !== "boolean") throw serverError("E_BAD_ARGS", "keepEnv must be true or false");
     if (keepEnv && Object.hasOwn(definition, "env")) throw serverError("E_BAD_ARGS", "omit env when preserving the saved environment");
+    if (definition.harness !== undefined && definition.runtime !== undefined && definition.harness !== definition.runtime) throw serverError("E_BAD_ARGS", "the definition names harness and runtime (its pre-0.27 name) with different values; nothing was sent");
     input = Buffer.from(JSON.stringify(definition));
     args.push("--file", "-");
     if (keepEnv) args.push("--keep-env");
@@ -749,7 +771,9 @@ export function launchConfigRemote(serverId, options = {}, io = {}) {
   // stdin belongs only to the set operation, never its preceding version probe.
   const remote = checkRemote(target, { ...io, input: undefined });
   requireRemoteFeature(remote, target, "launch-config");
-  const { envelope, stderr } = runRemote(target, [...args, "--json"], { ...io, input });
+  // The host's vocabulary: its harness flag, and the definition's key (read either here).
+  if (input !== undefined) input = Buffer.from(JSON.stringify(hostLaunchDefinition(remote, definition)));
+  const { envelope, stderr } = runRemote(target, [...hostHarnessArgs(remote, args), "--json"], { ...io, input });
   return { envelope, stderr, target, ...(route ? { route } : {}) };
 }
 
@@ -774,6 +798,14 @@ export function scheduleRemote(serverId, oatsArgs, io = {}) {
       // refuses them, never forwarded to a remote kernel that might still accept one.
       const captured = CAPTURED_SCHEDULE_KEYS.filter((key) => Object.hasOwn(spec, key));
       if (captured.length) throw serverError("E_SCHEDULE_INVALID", `${captured.join(", ")}: captured schedules are refused (the captured/portable path was removed in 0.26); no request was forwarded`);
+      // The host's vocabulary for the spawn job's harness (read either here).
+      if (Object.hasOwn(spec, "harness") || Object.hasOwn(spec, "runtime")) {
+        const { harness, runtime, ...rest } = spec;
+        if (harness !== undefined && runtime !== undefined && harness !== runtime) throw serverError("E_SCHEDULE_INVALID", "the schedule names harness and runtime (its pre-0.27 name) with different values; no request was forwarded");
+        const value = harness ?? runtime;
+        if (runtime !== undefined) noteRuntimeName("runtime in the schedule spec (sent as the host's harness key)");
+        oatsArgs = oatsArgs.map((a, i) => (i === indexes[0] + 1 ? JSON.stringify((remote.features || []).includes("harness") ? { ...rest, harness: value } : { ...rest, runtime: value }) : a));
+      }
     }
   }
   const args = ["schedule", ...oatsArgs.filter((a) => a !== "--json"), "--dir", target.workspace, "--json"];

package/lib/workspace.mjs

@@ -294,6 +294,13 @@ function fromProblems(remote, capabilities, path, problems, { here }) {
 export function validateLocal(value) {
   const problems = validateAgainst(schemaFor("local"), value);
   if (isObject(value) && isObject(value.settings)) for (const [cap, payload] of Object.entries(value.settings)) reservedKeyProblems(payload, `/settings/${pointerKey(cap)}`, problems);
+  // runtime → harness (0.27.0, lead call 6): `runtime`, the pre-0.27 name, is still read; both,
+  // disagreeing, are refused.
+  if (isObject(value) && isObject(value["launch-configs"])) for (const [name, entry] of Object.entries(value["launch-configs"])) {
+    if (isObject(entry) && Object.hasOwn(entry, "runtime") && Object.hasOwn(entry, "harness") && entry.runtime !== entry.harness) {
+      problems.push({ path: `/launch-configs/${pointerKey(name)}/runtime`, reason: "harness-conflict", message: `harness ${show(entry.harness)} and runtime ${show(entry.runtime)} disagree: \`runtime\` is the pre-0.27 name of \`harness\` — keep one` });
+    }
+  }
   return problems;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awebai/oats",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
   "keywords": [
     "agents",

package/packages/record/lib/session-roots.mjs

@@ -16,7 +16,9 @@ export function sourceSessionEnvironment(home, base = process.env) {
   }
   const recipe = meta?.launch;
   if (recipe !== undefined) {
-    if (!recipe || recipe.version !== 1 || !["claude", "pi", "codex"].includes(recipe.runtime)) {
+    // Version 1 (a 0.26.0 home) names the harness `runtime`; version 2 `harness`.
+    const harness = recipe?.version === 2 ? recipe.harness : recipe?.version === 1 ? recipe.runtime : undefined;
+    if (!recipe || !["claude", "pi", "codex"].includes(harness)) {
       throw new Error("cannot resolve source transcript roots: unsupported recorded launch recipe");
     }
     for (const layer of [recipe.hooks?.env, recipe.env]) {
@@ -32,7 +34,7 @@ export function sourceSessionEnvironment(home, base = process.env) {
     }
     // Pi also supports a direct session-directory override. Do not certify
     // default roots when native options direct evidence somewhere else.
-    if (recipe.runtime === "pi") {
+    if (harness === "pi") {
       const args = recipe.args ?? [];
       if (!Array.isArray(args) || args.some((a) => typeof a !== "string")) throw new Error("cannot resolve source transcript roots: invalid launch arguments");
       for (let i = 0; i < args.length; i++) {
@@ -69,13 +71,13 @@ export function nativeDirectory(value, { home = homedir(), cwd = process.cwd(),
 /** Native execution-side locations, without existence filtering. Unlike a
  * background observer scan, Claude's native default is exactly ~/.claude,
  * not every .claude* profile found under an observer's HOME. */
-export function nativeLaunchLocations(runtime, { cwd, env = process.env, args = [] } = {}) {
+export function nativeLaunchLocations(harness, { cwd, env = process.env, args = [] } = {}) {
   const home = env.HOME || homedir();
   if (!isAbsolute(home)) throw new Error("native launch HOME must be absolute");
   if (!Array.isArray(args) || args.some(a => typeof a !== "string")) throw new Error("invalid native launch arguments");
-  if (runtime === "claude") return [join(nativeDirectory(env.CLAUDE_CONFIG_DIR || join(home, ".claude"), { home, cwd }), "projects")];
-  if (runtime === "codex") return [join(nativeDirectory(env.CODEX_HOME || join(home, ".codex"), { home, cwd }), "sessions")];
-  if (runtime !== "pi") throw new Error("unsupported native record runtime");
+  if (harness === "claude") return [join(nativeDirectory(env.CLAUDE_CONFIG_DIR || join(home, ".claude"), { home, cwd }), "projects")];
+  if (harness === "codex") return [join(nativeDirectory(env.CODEX_HOME || join(home, ".codex"), { home, cwd }), "sessions")];
+  if (harness !== "pi") throw new Error("unsupported native record harness");
   let sessionDir = env.PI_CODING_AGENT_SESSION_DIR;
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];

package/skills/soul-craft/SKILL.md

@@ -81,7 +81,7 @@ plus `knowledge` / `messaging` / `tasks` slots; `none` empties one). The
 soul lives in its member repository, which is also what it works on.
 
 Runtime, model and permission bypass are not soul fields: they are chosen at
-spawn (`--runtime`, `--model`, `--yolo`) or by a host's named launch
+spawn (`--harness`, `--model`, `--yolo`) or by a host's named launch
 configuration, so the same soul runs on any harness a host provides. Check a
 soul with `oats spawn <soul> --preview` before committing it.