@awebai/oats 0.25.9 → 0.27.0

package/lib/servers.mjs

@@ -21,8 +21,8 @@ import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
-import { parseStrictJson } from "./portable-values.mjs";
-import { capturedSelector } from "./captured-selector.mjs";
+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");
@@ -225,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: probe.operationsApi === 1 ? 1 : null,
+    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,
@@ -405,14 +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
-    // for local souls).
+    // 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).
@@ -486,7 +496,7 @@ export function routeCommand(serverId, cmd, oatsArgs, io = {}) {
     return { envelope: envelope.ok ? { ...envelope, result: { ...envelope.result, server: serverId, target, snapshots: listSnapshots(serverId) } } : envelope, stderr };
   }
   if (OPERATIONS_COMMANDS.has(cmd)) {
-    // The operations contract (inspect, operation run, use, soul set): the
+    // The operations contract (inspect, operation run): the
     // remote must advertise it before anything is sent. An explicit --dir is
     // the exact member context the caller chose and travels as is; without
     // one, a --home selection is left to the host (the home is its own
@@ -505,14 +515,14 @@ export function routeCommand(serverId, cmd, oatsArgs, io = {}) {
       if (ii >= 0) { args.splice(ii, 2); if (valueOf("--home") === undefined) args.push("--home", route.home); }
     }
     const remote = checkRemote(target, io);
-    if (!Array.isArray(remote.features) || !remote.features.includes("operations") || remote.operationsApi !== 1) {
+    if (!Array.isArray(remote.features) || !remote.features.includes("operations") || ![1, 2].includes(remote.operationsApi)) {
       throw serverError("E_REMOTE_INCOMPATIBLE", `remote oats ${remote.version} at ${target.sshHost} does not advertise the operations contract (kernels from ${OPERATIONS_REMOTE_VERSION} do); upgrade it there; nothing was sent`);
     }
     const scoped = args.includes("--dir") || args.includes("--home") ? args : [...args, "--dir", target.workspace];
     const { envelope, stderr } = runRemote(target, json([cmd, ...scoped]), io);
     return { envelope: envelope.result && typeof envelope.result === "object" ? { ...envelope, result: { ...envelope.result, server: serverId, ...(route ? { route: { home: route.home, instance: route.snapshot?.instance || null, frozen: !!route.snapshot } } : {}) } } : envelope, stderr };
   }
-  throw serverError("E_USAGE", `--server routes spawn, retire, status, session, okf harvest, schedule, inspect, operation, use and soul only (not ${cmd})`);
+  throw serverError("E_USAGE", `--server routes spawn, retire, status, session, okf harvest, schedule, inspect and operation only (not ${cmd})`);
 }
 
 // ------------------------------------------------------------------- roster
@@ -578,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 });
@@ -586,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,
@@ -599,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;
   }
@@ -656,7 +666,7 @@ export function inspectRemote(serverId, { instance, home } = {}, io = {}) {
 export const SESSION_START_REMOTE_VERSION = "0.22.9";
 /** The kernel version whose probe first advertises the operations contract. */
 export const OPERATIONS_REMOTE_VERSION = "0.22.16";
-const OPERATIONS_COMMANDS = new Set(["inspect", "operation", "use", "soul"]);
+const OPERATIONS_COMMANDS = new Set(["inspect", "operation"]);
 
 /** `session start` on the execution host for a remote instance: the same
  *  route resolution as inspect, refused before any mutation when the remote
@@ -669,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");
@@ -695,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);
@@ -703,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 };
 }
@@ -713,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");
@@ -731,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");
@@ -751,10 +771,14 @@ 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 } : {}) };
 }
 
+/** The definition keys of a captured (versioned) schedule, removed in 0.26 (as lib/schedule.mjs refuses them). */
+const CAPTURED_SCHEDULE_KEYS = ["definitionVersion", "recurrencePolicy", "execution", "preparation"];
 /** `oats schedule ...` on the execution host: schedules are host-owned, so
  *  every subcommand runs in the server's registered workspace; refused
  *  before any remote mutation when the remote kernel does not advertise
@@ -767,14 +791,22 @@ export function scheduleRemote(serverId, oatsArgs, io = {}) {
   if (["add", "update"].includes(oatsArgs[0])) {
     const indexes = oatsArgs.flatMap((arg, index) => arg === "--spec-json" ? [index] : []);
     if (indexes.length > 1) throw serverError("E_BAD_ARGS", "remote schedule spec must be unambiguous");
-    let versioned = oatsArgs.includes("--file"); // Cannot classify remote file bytes here.
     if (indexes.length) {
       const spec = parseStrictJson(oatsArgs[indexes[0] + 1]);
       if (!spec || typeof spec !== "object" || Array.isArray(spec)) throw serverError("E_BAD_ARGS", "remote schedule spec must be an object");
-      versioned ||= ["definitionVersion", "recurrencePolicy", "execution", "preparation"].some(key => Object.hasOwn(spec, key));
-      if (Array.isArray(spec.argv)) versioned ||= !!capturedSelector(spec.argv.slice(1), {});
+      // Captured (versioned) schedules were removed in 0.26: refused here, as a local add
+      // 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));
+      }
     }
-    if (versioned && remote.scheduleApi !== 2) throw serverError("E_REMOTE_INCOMPATIBLE", "captured schedule mutation requires advertised scheduleApi 2; no request was forwarded");
   }
   const args = ["schedule", ...oatsArgs.filter((a) => a !== "--json"), "--dir", target.workspace, "--json"];
   const { envelope, stderr } = runRemote(target, args, io);

package/lib/{portable-shape.mjs → shape.mjs}

@@ -1,7 +1,8 @@
-/** Small shape checks shared by portable document/record codecs. Call only on
- * decoded or canonical-data-validated values; these helpers do not resolve policy. */
+/** Small shape checks for decoded documents (capability manifests' binding
+ * declarations). Call only on decoded or canonical-data-validated values; these
+ * helpers do not resolve policy. */
 import { oatsError } from "./errors.mjs";
-import { scalarString } from "./portable-values.mjs";
+import { scalarString } from "./canonical-json.mjs";
 
 export const pointerKey = (key) => key.replace(/~/g, "~0").replace(/\//g, "~1");
 export function invalidShape(pointer, message, code = "invalid-declaration") {

package/lib/tree-copy.mjs

@@ -0,0 +1,44 @@
+/** Tree mechanics only: the kernel's catchable recursive copy (spawn, retire and
+ * work recovery). No acquisition, selection, trust, lock or lifecycle policy. */
+import {
+  chmodSync, copyFileSync, lstatSync, mkdirSync, readdirSync, readlinkSync, symlinkSync,
+} from "node:fs";
+import { join } from "node:path";
+import { oatsError } from "./errors.mjs";
+
+/** Recursively copy a tree the way `cpSync(..., { recursive: true })` would —
+ * except catchably.
+ *
+ * Node 22's recursive `cpSync` performs its recursion in native code, and on
+ * macOS an unreadable directory inside the tree surfaces as an uncaught libc++
+ * `filesystem_error` that TERMINATES THE PROCESS. No JS `catch` or `finally`
+ * runs, so a transaction using it can never clean up staging or roll back the
+ * store, the lock and the ignore file. Every package-, capability- and
+ * user-shaped tree in the engine therefore goes through this hand-walk instead,
+ * where an EACCES is an ordinary throwable error.
+ *
+ * Semantics chosen to be safe rather than maximally faithful:
+ * - deterministic traversal (sorted entries), so two copies of one tree hash
+ *   identically;
+ * - symlinks are recreated VERBATIM — never followed, never rewritten — because
+ *   the bytes about to be hashed must be the bytes the author wrote;
+ * - FIFOs, sockets and device nodes are rejected fail-closed: they are not
+ *   distributable content, and copying them has no defined meaning here;
+ * - directory modes are applied AFTER their children, so a read-only source
+ *   directory cannot block writing its own contents. */
+export function copyTreeSafe(src, dest) {
+  const st = lstatSync(src);
+  if (st.isSymbolicLink()) { symlinkSync(readlinkSync(src), dest); return; }
+  if (st.isFile()) { copyFileSync(src, dest); chmodSync(dest, st.mode & 0o7777); return; }
+  if (!st.isDirectory()) {
+    throw oatsError("invalid-source", `${src} is not a regular file, directory or symlink (${st.isFIFO() ? "FIFO" : st.isSocket() ? "socket" : st.isBlockDevice() || st.isCharacterDevice() ? "device node" : "unsupported file type"}) — package and capability trees carry distributable content only`);
+  }
+  mkdirSync(dest, { recursive: true });
+  for (const e of readdirSync(src, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    copyTreeSafe(join(src, e.name), join(dest, e.name));
+  }
+  chmodSync(dest, st.mode & 0o7777);
+}
+
+
+

package/lib/workspace.mjs

@@ -16,6 +16,7 @@ import { parseConfigData } from "./config-data.mjs";
 import { oatsError } from "./errors.mjs";
 import * as defaultRemote from "./remote.mjs";
 import { bindRemote, classifyPackageValue } from "./packages.mjs";
+import { manifestContractProblems } from "./capability-contract.mjs";
 
 /* ───────────────────────────── errors ─────────────────────────────────── */
 
@@ -293,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;
 }
 
@@ -335,14 +343,24 @@ function schemaError(kind, origin, problems, value) {
 
 /* ───────────────────────────── public API ─────────────────────────────── */
 
-/** Walk up from dir to find oats-local.yaml → { path, local } | E_LOCAL_MISSING. */
+/** What a 0.25 `oats-config.yaml` held, and where each piece lives now (0.26.0 removed the file). */
+export const LEGACY_CONFIG_MIGRATION = "oats-config.yaml is no longer read (removed in 0.26.0): launch-configs moved to the deployment's oats-local.yaml; "
+  + "capability bindings, layers and team moved to oats-workspace.yaml (defaults, teams) and each soul's soul.yaml in its member repository; "
+  + "agents-md-injection, skill-overrides, work-modes and yolo are removed (yolo is --yolo or a launch configuration's yolo). Move what you still need, then delete the file";
+
+/** Walk up from dir to find oats-local.yaml → { path, local } | E_LOCAL_MISSING.
+ *  A 0.25 `oats-config.yaml` between `dir` and the deployment (inclusive) is refused
+ *  (E_CONFIG_BROKEN, naming the migration): nothing reads it, so it must not look
+ *  like configuration. Above the deployment is not this deployment's business. */
 export function loadLocal(dir) {
   let current = resolve(dir);
-  const visited = [];
+  const visited = [], legacy = [];
   for (;;) {
     const candidate = join(current, "oats-local.yaml");
     visited.push(candidate);
+    if (existsSync(join(current, "oats-config.yaml"))) legacy.push(join(current, "oats-config.yaml"));
     if (existsSync(candidate)) {
+      if (legacy.length) throw fail("E_CONFIG_BROKEN", `${legacy.join(", ")}: ${LEGACY_CONFIG_MIGRATION}`, { dir: resolve(dir), deployment: current, files: legacy, reason: "legacy-config" });
       const origin = { kind: "local", path: candidate };
       const read = readDeclaration("local", readFileSync(candidate), origin);
       if (read.problems) throw schemaError("local", origin, read.problems, read.value);
@@ -352,7 +370,7 @@ export function loadLocal(dir) {
     if (parent === current) break;
     current = parent;
   }
-  throw fail("E_LOCAL_MISSING", `no oats-local.yaml found walking up from ${resolve(dir)}`, { dir: resolve(dir), searched: visited });
+  throw fail("E_LOCAL_MISSING", `no oats-local.yaml found walking up from ${resolve(dir)}${legacy.length ? ` (${legacy[0]} is a 0.25 deployment's configuration, which 0.26.0 no longer reads: retire its instances with 0.25, then \`oats onboard\` it)` : ""}`, { dir: resolve(dir), searched: visited, ...(legacy.length ? { legacy } : {}) });
 }
 
 /** Observe the workspace host: → { key, url, commit, workspace, observedAt }. */
@@ -374,6 +392,47 @@ export async function observeWorkspace(ref, { at, remote: injected, remoteOption
   return { key: obs.key, url: obs.url, ref, commit: obs.commit, workspace: read.value, observedAt: obs.observedAt };
 }
 
+/**
+ * A soul's team labels as its repository declares them NOW, without a workspace discovery (teams
+ * contract decision 6, the live teams of an existing home): the workspace host has already been read
+ * (`wsObs`, observeWorkspace); this reads the soul's own repo once — a member at its current commit
+ * (`souls/<name>/soul.yaml`, and `oats-membership.yaml` only when the soul declares no `team`), or an
+ * `external[]` soul at its pinned commit (its entry's `team` wins, as in discovery).
+ * → labels (primary first), or null when the workspace no longer lists the soul's repo.
+ * Membership is not re-confirmed here: the home's soul was confirmed at spawn; this reads labels only.
+ */
+export async function observeSoulLabels(wsObs, { name, repoKey }, { remote: injected, remoteOptions } = {}) {
+  const remote = remoteOf({ remote: injected, remoteOptions });
+  const workspace = wsObs.workspace;
+  const readSoul = async (ref, commit, path) => {
+    const file = `${path.replace(/\/+$/, "")}/soul.yaml`;
+    const { bytes } = await remote.readRemoteFile(ref, commit, file);
+    const read = readDeclaration("soul", bytes, { kind: "soul", repoKey, commit, path: file });
+    if (read.problems) throw schemaError("soul", { kind: "soul", repoKey, commit, path: file }, read.problems, read.value);
+    return read.value;
+  };
+  for (const entry of workspace.external || []) {
+    const pin = entry.source.lastIndexOf("@");
+    let key; try { key = refKey(remote, entry.source.slice(0, pin)); } catch { continue; }
+    if (key !== repoKey) continue;
+    if (typeof entry.team === "string") return [entry.team];
+    const soul = await readSoul(entry.source.slice(0, pin), entry.source.slice(pin + 1), entry.soul);
+    if (soul.name !== name) continue;
+    return labelList(soul.team) ?? [];
+  }
+  const memberRef = (workspace.members || []).find((ref) => { try { return refKey(remote, ref) === repoKey; } catch { return false; } });
+  if (!memberRef) return null;
+  const obs = await remote.observeRemote(memberRef);
+  const soul = await readSoul(memberRef, obs.commit, `souls/${name}`);
+  const own = labelList(soul.team);
+  if (own) return own;
+  try {
+    const { bytes } = await remote.readRemoteFile(memberRef, obs.commit, "oats-membership.yaml");
+    const read = readDeclaration("membership", bytes, { kind: "membership", repoKey, commit: obs.commit, path: "oats-membership.yaml" });
+    return read.problems ? [] : labelList(read.value.team) ?? [];
+  } catch (e) { if (e?.code === "E_REMOTE_PATH_MISSING") return []; throw e; }
+}
+
 const unconfirmed = (key, reason, detail, extra = {}) => ({ key, confirmed: false, reason, detail, ...extra });
 
 /**
@@ -422,21 +481,28 @@ export async function confirmMembership(workspaceObs, memberRef, { remote: injec
     const caseOnly = backlinkKey.toLowerCase() === workspaceObs.key.toLowerCase();
     return unconfirmed(key, "backlink-elsewhere", `${key}@${obs.commit.slice(0, 12)} names workspace ${backlinkKey}, not ${workspaceObs.key}${caseOnly ? " (the keys differ only by letter case: repo paths are case-sensitive identities; spell the workspace ref exactly as the workspace lists itself)" : ""}`, { commit: obs.commit, backlink: backlinkKey, ...(caseOnly ? { caseOnly: true } : {}) });
   }
-  return { key, commit: obs.commit, confirmed: true, team: read.value.team ?? null };
+  const labels = labelList(read.value.team) ?? [];
+  return { key, commit: obs.commit, confirmed: true, team: labels[0] ?? null, labels };
 }
 
 /* ───────────────────────────── enumeration ────────────────────────────── */
 
 const SOUL_FILE = /^([^/]+)\/soul\.yaml$/;
 const CAP_FILE = /^([^/]+)\/oats\.json$/;
-const teamOf = (item, fallback) => (typeof item?.team === "string" ? item.team : fallback ?? null);
+/** A declared `team` as a label list (teams contract 2026-09-25: a label or a non-empty list of distinct
+ *  labels, the first the primary); null when the item declares none. */
+const labelList = (team) => (typeof team === "string" ? [team] : Array.isArray(team) ? team.filter((l) => typeof l === "string") : null);
+/** The item's labels, else the repo default's (oats-membership.yaml). */
+const labelsOf = (item, fallback) => labelList(item?.team) ?? [...(fallback || [])];
+/** Each label with the path it is declared at: `/team` for one label, `/team/<i>` in a list. */
+const labelPaths = (item, labels, file) => labels.map((label, i) => [label, Array.isArray(item?.team) ? `${file}#/team/${i}` : `${file}#/team`]);
 
 /**
  * Enumerate souls/*\/soul.yaml and capabilities/*\/oats.json of one repo at one commit.
  * Validates each item; collects problems instead of aborting.
  * → { souls: [SoulEntry], capabilities: [CapEntry], problems: [{ code, path, message, repoKey }] }
  */
-async function enumerateRepo(remote, ref, key, commit, { defaultTeam = null, teams = null } = {}) {
+async function enumerateRepo(remote, ref, key, commit, { defaultLabels = [], teams = null } = {}) {
   const souls = [];
   const capabilities = [];
   const problems = [];
@@ -467,9 +533,10 @@ async function enumerateRepo(remote, ref, key, commit, { defaultTeam = null, tea
     if (definition.name !== m[1]) problem("E_WORKSPACE_SCHEMA", `${file}#/name`, `soul name ${show(definition.name)} does not match its directory ${show(m[1])}`);
     if (soulNames.has(definition.name)) { problem("E_WORKSPACE_SCHEMA", `${file}#/name`, `soul name ${show(definition.name)} is already declared by ${soulNames.get(definition.name)}; the second declaration is not listed`); continue; }
     soulNames.set(definition.name, file);
-    const team = teamOf(definition, defaultTeam);
-    checkTeam(team, `${file}#/team`);
-    souls.push({ name: definition.name, path, repoKey: key, commit, team, private: definition.private === true, definition });
+    const labels = labelsOf(definition, defaultLabels);
+    for (const [label, at] of labelPaths(definition, labels, file)) checkTeam(label, at);
+    // Souls have no private mode since 0.26.0: `private` is accepted, warned (soul-private-ignored) and never hides a soul.
+    souls.push({ name: definition.name, path, repoKey: key, commit, team: labels[0] ?? null, labels, private: false, definition });
   }
   const capNames = new Map();
   for (const entry of await list("capabilities")) {
@@ -497,9 +564,13 @@ async function enumerateRepo(remote, ref, key, commit, { defaultTeam = null, tea
       },
     }, manifest);
     if (shape.length) { for (const p of shape) problem("E_WORKSPACE_SCHEMA", `${file}#${p.path}`, p.message); continue; }
+    // The kernel contract (launch environment, hooks): a manifest the kernel could not run is not listed.
+    const contract = manifestContractProblems(manifest);
+    if (contract.length) { for (const p of contract) problem("E_WORKSPACE_SCHEMA", `${file}#${p.pointer}`, p.message); continue; }
     if (capNames.has(manifest.capability)) { problem("E_WORKSPACE_SCHEMA", `${file}#/capability`, `capability ${show(manifest.capability)} is already declared by ${capNames.get(manifest.capability)}; the second declaration is not listed`); continue; }
     capNames.set(manifest.capability, file);
-    const team = teamOf(manifest, defaultTeam);
+    // A capability is LISTED under one team (its own `team:`, else the repo default's primary); it joins none.
+    const team = typeof manifest.team === "string" ? manifest.team : defaultLabels[0] ?? null;
     checkTeam(team, `${file}#/team`);
     capabilities.push({ name: manifest.capability, path, repoKey: key, commit, team, private: manifest.private === true, manifest });
   }
@@ -537,7 +608,7 @@ export async function discoverRepo(ref, { at, remote: injected, remoteOptions }
   } catch (e) {
     if (e?.code !== "E_REMOTE_PATH_MISSING") throw e;
   }
-  const items = await enumerateRepo(remote, ref, obs.key, obs.commit, { defaultTeam: membership?.team ?? null, teams: null });
+  const items = await enumerateRepo(remote, ref, obs.key, obs.commit, { defaultLabels: labelList(membership?.team) ?? [], teams: null });
   return { key: obs.key, commit: obs.commit, membership, ...items, problems: [...problems, ...items.problems] };
 }
 
@@ -557,7 +628,7 @@ export async function discoverWorkspace(ref, { at, local, remote: injected, remo
   const members = [];
   for (const memberRef of workspace.members || []) {
     const confirmation = await confirmMembership(wsObs, memberRef, { remote });
-    const row = { key: confirmation.key, commit: confirmation.commit ?? null, confirmed: confirmation.confirmed, team: confirmation.team ?? null, souls: [], capabilities: [], publishes: null };
+    const row = { key: confirmation.key, commit: confirmation.commit ?? null, confirmed: confirmation.confirmed, team: confirmation.team ?? null, labels: confirmation.labels ?? [], souls: [], capabilities: [], publishes: null };
     if (!confirmation.confirmed) {
       // Contract: an unconfirmed member contributes nothing but its row.
       row.reason = confirmation.reason;
@@ -565,8 +636,10 @@ export async function discoverWorkspace(ref, { at, local, remote: injected, remo
       members.push(row);
       continue;
     }
-    if (row.team !== null && !teams.includes(row.team)) problems.push({ code: "E_TEAM_UNKNOWN", repoKey: row.key, path: "oats-membership.yaml#/team", message: `team ${show(row.team)} is not declared in the workspace's teams (${teams.join(", ") || "none"})` });
-    const items = await enumerateRepo(remote, memberRef, row.key, row.commit, { defaultTeam: row.team, teams });
+    for (const [i, label] of row.labels.entries()) {
+      if (!teams.includes(label)) problems.push({ code: "E_TEAM_UNKNOWN", repoKey: row.key, path: row.labels.length > 1 ? `oats-membership.yaml#/team/${i}` : "oats-membership.yaml#/team", message: `team ${show(label)} is not declared in the workspace's teams (${teams.join(", ") || "none"})` });
+    }
+    const items = await enumerateRepo(remote, memberRef, row.key, row.commit, { defaultLabels: row.labels, teams });
     row.souls = items.souls;
     row.capabilities = items.capabilities;
     row.publishes = items.publishes;
@@ -593,11 +666,50 @@ export async function discoverWorkspace(ref, { at, local, remote: injected, remo
     }
     const read = readDeclaration("soul", bytes, { kind: "soul", repoKey: key, commit, path: file });
     if (read.problems) { for (const p of read.problems) pushProblem("E_WORKSPACE_SCHEMA", `${file}#${p.path}`, `${p.message}${schemaHint("soul", read.value)}`); continue; }
-    const team = teamOf(entry, null) ?? teamOf(read.value, null);
-    if (team !== null && !teams.includes(team)) pushProblem("E_TEAM_UNKNOWN", `${file}#/team`, `team ${show(team)} is not declared in the workspace's teams`);
-    externalRows.push({ source: entry.source, key, commit, soul: { name: read.value.name, path: entry.soul, repoKey: key, commit, team, private: read.value.private === true, definition: read.value } });
+    // The workspace's `external[].team` (one label) overrides the soul's own labels.
+    const labels = labelList(entry.team) ?? labelList(read.value.team) ?? [];
+    for (const label of labels) if (!teams.includes(label)) pushProblem("E_TEAM_UNKNOWN", `${file}#/team`, `team ${show(label)} is not declared in the workspace's teams`);
+    externalRows.push({ source: entry.source, key, commit, soul: { name: read.value.name, path: entry.soul, repoKey: key, commit, team: labels[0] ?? null, labels, private: false, definition: read.value } });
   }
-  return { workspace, key: wsObs.key, url: wsObs.url, commit: wsObs.commit, observedAt: wsObs.observedAt, local: local ?? null, members, external: externalRows, problems };
+  return { workspace, key: wsObs.key, url: wsObs.url, commit: wsObs.commit, observedAt: wsObs.observedAt, local: local ?? null, members, external: externalRows, problems, warnings: [...unmappedLabelWarnings(workspace, members, externalRows, teams), ...privateSoulWarnings([...members.filter((m) => m.confirmed).flatMap((m) => m.souls), ...externalRows.map((e) => e.soul)])] };
+}
+
+/** Teams contract decision 5: a soul label the workspace declares in `teams:` but does not map in
+ *  `messaging.byTeam` is a WARNING, not a problem — the label stays eligible-but-unmapped and the
+ *  messaging provider falls back to the personal team for it. (An undeclared label is E_TEAM_UNKNOWN.)
+ *  ONE warning per unmapped label, naming its souls (a personal-only workspace would otherwise print
+ *  a line per soul): { code, label, souls, paths, message }, sorted by label. */
+const byCodepointOrder = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+function unmappedLabelWarnings(workspace, members, externalRows, teams) {
+  const byTeam = isObject(workspace?.messaging) && isObject(workspace.messaging.byTeam) ? workspace.messaging.byTeam : {};
+  const byLabel = new Map();
+  const souls = [...members.filter((m) => m.confirmed).flatMap((m) => m.souls), ...externalRows.map((e) => e.soul)];
+  for (const soul of souls) {
+    for (const label of soul.labels || []) {
+      if (!teams.includes(label) || Object.hasOwn(byTeam, label)) continue;
+      const row = byLabel.get(label) || { souls: [], paths: [] };
+      row.souls.push(soul.name); row.paths.push(`${soul.repoKey}:${soul.path}/soul.yaml#/team`);
+      byLabel.set(label, row);
+    }
+  }
+  return [...byLabel.keys()].sort(byCodepointOrder).map((label) => {
+    const { souls: names, paths } = byLabel.get(label);
+    const order = names.map((n, i) => i).sort((x, y) => byCodepointOrder(names[x], names[y]) || byCodepointOrder(paths[x], paths[y]));
+    const sorted = order.map((i) => names[i]);
+    return { code: "unmapped-team-label", label, souls: sorted, paths: order.map((i) => paths[i]),
+      message: `team ${show(label)} has no messaging.byTeam entry; its souls (${sorted.join(", ")}) fall back to the personal team for it` };
+  });
+}
+
+/** `private:` in a soul.yaml has no effect since 0.26.0 (human decision 2026-09-25): every soul of a
+ *  confirmed member, and every external soul, is listed and spawnable. The field is still ACCEPTED
+ *  (existing files keep validating) and named by ONE warning per soul that carries it:
+ *  { code: "soul-private-ignored", soul, repoKey, path, message }, sorted by soul name, then path. */
+function privateSoulWarnings(souls) {
+  return souls.filter((s) => s.definition && Object.hasOwn(s.definition, "private"))
+    .map((s) => ({ code: "soul-private-ignored", soul: s.name, repoKey: s.repoKey, path: `${s.repoKey}:${s.path}/soul.yaml#/private`,
+      message: `\`private\` has no effect on a soul since 0.26.0; remove it from ${s.path}/soul.yaml` }))
+    .sort((a, b) => byCodepointOrder(a.soul, b.soul) || byCodepointOrder(a.path, b.path));
 }
 
 /**
@@ -648,7 +760,7 @@ export function standaloneRepo(ref, commit, discovery, { remote: injected } = {}
   });
   return {
     standalone: true, key, commit: source.commit ?? commit ?? null, workspace: null,
-    members: [{ key, commit: source.commit ?? commit ?? null, confirmed: false, reason: "cannot-read", detail: `workspace of ${key} cannot be read; standalone view`, team: source.team ?? source.membership?.team ?? null, souls, capabilities, publishes: source.publishes ?? null }],
-    external: [], problems,
+    members: [{ key, commit: source.commit ?? commit ?? null, confirmed: false, reason: "cannot-read", detail: `workspace of ${key} cannot be read; standalone view`, team: source.team ?? labelList(source.membership?.team)?.[0] ?? null, souls, capabilities, publishes: source.publishes ?? null }],
+    external: [], problems, warnings: privateSoulWarnings(souls),
   };
 }