@awebai/oats 0.25.9 → 0.26.0

package/lib/servers.mjs

@@ -21,8 +21,7 @@ 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";
 
 const OATS_HOME_DIR = () => process.env.OATS_HOME_DIR || join(homedir(), ".oats");
 export const SERVERS_FILE = () => join(OATS_HOME_DIR(), "servers.json");
@@ -234,7 +233,7 @@ export function checkRemote(target, io = {}) {
     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),
   };
@@ -407,8 +406,7 @@ export function routeCommand(serverId, cmd, oatsArgs, io = {}) {
     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,
     // 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);
@@ -486,7 +484,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 +503,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
@@ -656,7 +654,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
@@ -755,6 +753,8 @@ export function launchConfigRemote(serverId, options = {}, io = {}) {
   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 +767,14 @@ 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`);
     }
-    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 ─────────────────────────────────── */
 
@@ -335,14 +336,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 +363,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 +385,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 +474,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 +526,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 +557,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 +601,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 +621,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 +629,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 +659,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, 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 { workspace, key: wsObs.key, url: wsObs.url, commit: wsObs.commit, observedAt: wsObs.observedAt, local: local ?? null, members, external: externalRows, problems };
+  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 +753,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),
   };
 }

package/package-catalog.json

@@ -1,5 +1,5 @@
 {
-  "policy": "docs/official-marketplace.md",
+  "policy": "docs/official-catalog.md",
   "packages": {
     "oats.okf": {
       "url": "https://github.com/awebai/oats-okf.git",
@@ -8,27 +8,27 @@
     },
     "oats.aweb": {
       "url": "https://github.com/awebai/oats-aweb.git",
-      "ref": "v1.12.1",
+      "ref": "v1.13.1",
       "path": "oats-package"
     },
     "oats.jira": {
       "url": "https://github.com/awebai/oats-jira.git",
-      "ref": "v1.0.0",
+      "ref": "v1.0.1",
       "path": "oats-package"
     },
     "oats.linear": {
       "url": "https://github.com/awebai/oats-linear.git",
-      "ref": "v1.0.0",
+      "ref": "v1.0.1",
       "path": "oats-package"
     },
     "oats.authoring": {
       "url": "https://github.com/awebai/oats-authoring.git",
-      "ref": "v1.0.0",
+      "ref": "v1.0.3",
       "path": "oats-package"
     },
     "oats.dev": {
       "url": "https://github.com/awebai/oats-dev.git",
-      "ref": "v1.0.0",
+      "ref": "v1.0.1",
       "path": "oats-package"
     },
     "oats.framework": {

package/package.json

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

package/skills/integration-authoring/SKILL.md

@@ -3,7 +3,7 @@ name: integration-authoring
 description: >-
   Route custom OATS capability-package and integration work to the framework's
   integrations expert. Use when building, adapting, or debugging a reusable
-  capability, new task/messaging/knowledge integration, oats.json manifest,
+  capability, new tasks/messaging/knowledge core capability, oats.json manifest,
   lifecycle hook, or operational command—not merely activating an existing
   package. Triggers: "custom integration", "capability package", "integrate
   our tracker", "new messaging integration", "write an oats.json".
@@ -12,65 +12,73 @@ description: >-
 # Capability and integration authoring — delegate
 
 A capability package may ship skills, instance instructions, requirements,
-namespaced commands, and approved hooks. An integration is the constrained
-subtype implementing exactly one fundamental layer. Building either requires
+namespaced commands, and declared hooks. A core capability is the constrained
+kind that fills one of the knowledge, messaging or tasks positions (its
+manifest's `layer` field names which). Building either requires
 manifest, security, targeting-boundary, collision, and probe discipline; use
 the framework's **integrations-expert** soul rather than improvising.
 
-If the user only wants an existing package, use:
+If the user only wants an existing package, declare it and give it to souls;
+no build is needed:
 
-```bash
-oats install <source>            # external acquisition + exact lock; inactive
-oats trust <id>                  # only if commands/hooks exist
-oats use <id> --global|--type <t>|--soul <s>
+```yaml
+# oats-workspace.yaml (host repository): declaring the package is the trust decision
+packages:
+  vendor.review: git:github.com/vendor/review@v1.0.0
+# a soul's soul.yaml, or the workspace defaults: a capability the package exports
+# (a package may export several; the soul names each one it wants)
+capabilities:
+  vendor.review: { from: package }
 ```
 
-## 1. Locate the OATS framework repository
+Then run `oats sync` (fetch, verify integrity, lock). The oats.setup
+capability's **oats-package-pins** skill has the procedure.
+
+## 1. Verify the expert is available
+
+Run `oats souls` in the deployment and confirm it resolves the
+`integrations-expert` soul (a member repository or package provides it). If it
+is absent, ask the human which OATS deployment owns reusable package work;
+never locate or import private kernel files.
 
-Check a local pi package path, then likely locations such as
-`~/oats`; verify with `git -C <dir> remote get-url origin`. Avoid
-pi-managed git clones because updates reset them. If absent, ask where to
-clone `https://github.com/awebai/oats`.
+## 2. Spawn the expert against the package's repository
 
-## 2. Spawn the expert against the user's repository
+The package lives in its own repository. Make that repository a member of the
+workspace (or use the member that already holds it), then spawn the expert on
+it:
 
 ```bash
-node -e "
-import('<framework-repo>/lib/core.mjs').then(m => {
-  const root = '<framework-repo>/agents';
-  const a = m.findAgent(root, 'integrations-expert');
-  const r = m.spawnInstance(root, a, {
-    purpose: '<package-slug>',
-    repo: '<users-workspace-or-repo>',
-    work: 'checkout',
-    task: '<capability intent; layer if any; skills/instructions/commands/hooks; external tools; desired global/group/soul targets; distribution path>',
-  });
-  console.log('window:', r.tmux.window, '| attach:', r.attach);
-})"
+oats spawn integrations-expert --preview \
+  --purpose <package-slug> \
+  --repo <member clone of the package repository> \
+  --work worktree \
+  --task '<capability intent; layer if any; skills/instructions/commands/hooks; external tools; which souls should get it; distribution path>'
+# review the preview, then run the same command without --preview
 ```
 
-The work tree is the user's repository, where a local package belongs under
-`.agents/capabilities/<name>/`. A framework contribution belongs under
-`capabilities/<name>/` in the framework worktree; an independently published
-package uses its own repository.
+Use `--relation child --relative-to <your-instance>` only when the documented
+workflow makes the expert your child; otherwise leave the spawn unrelated. A
+package is distributed from its own repository as `oats-package/` with a
+version tag; a framework contribution belongs in the framework's repository.
 
 ## 3. Brief the design boundary
 
 Tell the expert:
 
 - whether it is additive or implements exactly one of knowledge/messaging/tasks;
-- external requirements and executable surfaces;
+- external requirements and executable surfaces (commands, hooks);
 - intended distribution and version/compatibility;
-- desired config-owned targets and settings; and
-- expected skill/instruction/scaffold collisions.
+- which souls or workspace defaults should receive it, and its settings; and
+- expected skill/instruction collisions (a duplicate skill name fails the spawn).
 
-Targets never belong in the manifest. The expert must test exact pi/Claude
-instance materialization, generated instructions, lock/trust behavior,
-command gating, deterministic hooks, and scaffold ownership as applicable.
+Which souls get a capability is declared by the workspace (`defaults`) and the
+souls (`soul.yaml` `capabilities`), never in the manifest. The expert must
+test exact pi/Claude/Codex instance materialization, generated instructions,
+command gating, deterministic hooks, and the lock's integrity check as
+applicable.
 
 ## 4. Hand off
 
-Report the tmux window (`tmux attach -t pi-agents`). The expert follows its
-package/integration craft, runs a scaffold-only probe, and leaves acquisition
-and activation commands for the user. Its durable lessons harvest back into
-its soul.
+Report the new instance (`oats status`). The expert follows its
+package/integration craft, runs a preview-only probe, and leaves the
+`packages:` pin and the `oats sync` for the user.