@awebai/oats 0.29.4 → 0.30.0

package/lib/resolve.mjs

@@ -25,13 +25,12 @@
  *
  * Composition order (soul wins; `off` removes):
  *   workspace.defaults.{knowledge,messaging,tasks} (slot defaults; a soul `none` drops them)
- *   ⊕ workspace.defaults.capabilities ⊕ workspace.defaults.byTeam[<label>].capabilities for each of the
- *   soul's team labels, in order ⊕ soul.capabilities. Two labels that give one capability different
- *   entries → E_TEAM_CONFLICT naming both (teams contract 2026-09-25, decision 2).
+ *   ⊕ workspace.defaults.capabilities ⊕ soul.capabilities. (Team labels compose nothing: 0.30 removed
+ *   defaults.byTeam, so a soul's composition is the same for every person and machine.)
  *
  * Slot `none` (contract §3, post-0.25.0 rule): a soul's `<slot>: none` EMPTIES the slot — it drops the
  * workspace's `defaults.<slot>` AND any capability of that layer the workspace defaults contributed
- * (`defaults.capabilities`, `defaults.byTeam[team]`). A layer-bearing capability the SOUL ITSELF declares
+ * (`defaults.capabilities`). A layer-bearing capability the SOUL ITSELF declares
  * next to `none` is contradictory and stays E_SLOT_CONFLICT { reason: "none" } (spell `<cap>: off` to
  * remove a default explicitly; drop the soul's own line to fill the slot).
  *
@@ -45,7 +44,7 @@
  * everything, while a preview can say WHAT changed since the previous instance (declarations | payload | both).
  *
  * Payloads (decision 14), later wins on scalars/arrays, objects deep-merge:
- *   workspace.messaging (messaging slot only; its base, `byTeam` stripped and never merged — teams amendment K)
+ *   workspace.messaging (messaging slot only)
  *   ⊕ soul.<slot> ⊕ local.settings[cap] ⊕ spawn.providers[cap]
  *
  * This module shells out to nothing. Remote access is injected (`remote`, default
@@ -58,6 +57,7 @@ import { readFileSync } from "node:fs";
 import { posix } from "node:path";
 import { oatsError as baseOatsError } from "./errors.mjs";
 import * as defaultRemote from "./remote.mjs";
+import { BY_TEAM_REMOVED, reportRows, soulKeyOf, soulTeams, teamModel } from "./teams.mjs";
 import { bindRemote, packageProviding, readPackageManifests, validateLock } from "./packages.mjs";
 import { settingValueProblems } from "./capability-contract.mjs";
 
@@ -150,14 +150,13 @@ export function payloadOrigins(layers) {
   return origins;
 }
 
-/** `byTeam` is RESERVED (decision 23): it addresses a per-team payload and is legal only at the top level of
- * workspace.messaging, where the resolver merges base ⊕ byTeam[soul.team] and strips it. In any other payload
- * layer — a soul's slot payload, local.settings[cap], spawn.providers[cap] — it would reach the provider
- * verbatim; refused at the layer's top level with E_WORKSPACE_SCHEMA reason "reserved-key" and the path named. */
-const RESERVED_KEY = "byTeam";
+/** `byTeam` was removed in 0.30 (team model v2): in any payload layer — the workspace's messaging, a soul's
+ * slot payload, local.settings[cap], spawn.providers[cap] — it would reach the provider verbatim as a dead
+ * key; refused at the layer's top level with E_WORKSPACE_SCHEMA reason "removed-key" and the path named. */
+const REMOVED_KEY = "byTeam";
 function assertNoReservedKey(value, path) {
-  if (isObject(value) && Object.hasOwn(value, RESERVED_KEY)) {
-    throw fail("E_WORKSPACE_SCHEMA", `${path}/${RESERVED_KEY}: ${show(RESERVED_KEY)} is reserved — it is legal only at the top level of the workspace file's messaging: payload (decision 23)`, { path: `${path}/${RESERVED_KEY}`, key: RESERVED_KEY, reason: "reserved-key" });
+  if (isObject(value) && Object.hasOwn(value, REMOVED_KEY)) {
+    throw fail("E_WORKSPACE_SCHEMA", `${path}/${REMOVED_KEY}: ${BY_TEAM_REMOVED}`, { path: `${path}/${REMOVED_KEY}`, key: REMOVED_KEY, reason: "removed-key" });
   }
 }
 
@@ -333,46 +332,16 @@ const choiceOf = (value, path, via) => {
   throw fail("E_WORKSPACE_SCHEMA", `${path} must be { from: <location> } or "off", got ${show(value)}`, { path, value });
 };
 
-/** A soul's team labels, primary first: `team` is a label or a list of distinct labels (teams
- *  contract 2026-09-25, decision 1). A discovery SoulEntry carries them as `labels`; an entry
- *  without them (a hand-built one) has its `team` as the only label. */
-export function teamLabelsOf(soulEntry) {
-  if (Array.isArray(soulEntry?.labels)) return soulEntry.labels.filter((l) => typeof l === "string");
-  return typeof soulEntry?.team === "string" ? [soulEntry.team] : [];
-}
-
-/**
- * The eligible teams of a soul (teams contract, decision 3): one entry per label, in soul order,
- * `{ label, team, mapped, payload }`. `payload` is workspace.messaging's base ⊕ byTeam[label] when the
- * workspace maps the label, else the base alone with `mapped: false`; `team` is the payload's team id
- * when mapped (null otherwise). Kernel-owned and delivered BESIDE a provider's settings, never inside
- * them; joining any of them is the messaging provider's explicit act. No label → [] (the workspace's default team only).
- * Pure: resolveSoul validates every carried label's entry (reserved byTeam, hostOnly keys) first.
- */
-export function teamsOf(workspace, labels) {
-  const messaging = isObject(workspace?.messaging) ? workspace.messaging : {};
-  const { byTeam, ...base } = messaging;
-  return (labels || []).map((label) => {
-    const mapped = isObject(byTeam) && Object.hasOwn(byTeam, label) && isObject(byTeam[label]);
-    const payload = mapped ? mergePayload(base, byTeam[label]) : mergePayload(base);
-    return { label, team: mapped && typeof payload.team === "string" ? payload.team : null, mapped, payload };
-  });
-}
-
 /**
  * The ordered capability map of a soul BEFORE any lookup:
- *   slot defaults (dropped where the soul says `none`) ⊕ defaults.capabilities ⊕ defaults.byTeam[label] for
- *   each label in order ⊕ soul.capabilities
+ *   slot defaults (dropped where the soul says `none`) ⊕ defaults.capabilities ⊕ soul.capabilities
  * → [{ name, from, via }] sorted by name; `off` removes the entry from every lower layer.
- * `via` is one of "defaults.<slot>" | "defaults.capabilities" | "defaults.byTeam.<label>" | "soul".
- * Two labels that give one capability different entries (`off` vs a location, or two locations) →
- * E_TEAM_CONFLICT { capability, labels: [a, b] }; identical entries are not a conflict, and a capability
- * the soul names itself is not one either (the soul's entry wins over both).
+ * `via` is one of "defaults.<slot>" | "defaults.capabilities" | "soul".
  * `offs` (optional, feature desktop-facts): receives what the soul turned off — { name, reason: "off",
  * overrides } for each capability its own `off` removed from a lower layer, and { name, reason: "slot-none",
  * slot, overrides: "workspace" } for a slot default its `<slot>: none` dropped (`overrides`: fromOfVia vocabulary).
  */
-export function composeCapabilities(workspace, soulDefinition, { team = null, labels = team === null ? [] : [team], offs = null } = {}) {
+export function composeCapabilities(workspace, soulDefinition, { offs = null } = {}) {
   const map = new Map();
   const apply = (entries, via, path) => {
     for (const [name, value] of Object.entries(entries || {})) {
@@ -392,22 +361,6 @@ export function composeCapabilities(workspace, soulDefinition, { team = null, la
     apply(d, `defaults.${slot}`, `/defaults/${slot}`);
   }
   apply(defaults.capabilities, "defaults.capabilities", "/defaults/capabilities");
-  const byLabel = new Map(); // capability -> { label, choice } of the first label that set it
-  // The soul's own entry wins over every label, so a capability the soul names settles the conflict.
-  const soulNames = new Set(Object.keys(isObject(soulDefinition?.capabilities) ? soulDefinition.capabilities : {}));
-  for (const label of labels) {
-    if (!isObject(defaults.byTeam) || !Object.hasOwn(defaults.byTeam, label) || !isObject(defaults.byTeam[label])) continue;
-    const entries = defaults.byTeam[label].capabilities, path = `/defaults/byTeam/${label}/capabilities`;
-    for (const [name, value] of Object.entries(entries || {})) {
-      const choice = choiceOf(value, `${path}/${name}`, `defaults.byTeam.${label}`);
-      const seen = byLabel.get(name);
-      if (seen && !soulNames.has(name) && canonicalJson(seen.choice) !== canonicalJson(choice)) {
-        throw fail("E_TEAM_CONFLICT", `${name}: team labels ${show(seen.label)} and ${show(label)} give it different entries (${canonicalJson(seen.choice)} vs ${canonicalJson(choice)}) in defaults.byTeam — make them agree, or name ${name} in the soul`, { capability: name, labels: [seen.label, label], entries: [seen.choice, choice], paths: [`/defaults/byTeam/${seen.label}/capabilities/${name}`, `${path}/${name}`] });
-      }
-      if (!seen) byLabel.set(name, { label, choice });
-    }
-    apply(entries, `defaults.byTeam.${label}`, path);
-  }
   apply(soulDefinition?.capabilities, "soul", "/capabilities");
   return [...map.values()].sort((a, b) => byCodepoint(a.name, b.name));
 }
@@ -599,17 +552,18 @@ export async function resolveSoul(discovery, soulEntry, { local = null, lock = n
   const workspace = isObject(discovery?.workspace) ? discovery.workspace : null;
   assertSoulDiscovered(discovery, soulEntry);
   const definition = isObject(soulEntry.definition) ? soulEntry.definition : {};
-  const labels = teamLabelsOf(soulEntry);
-  const team = labels[0] ?? null; // the PRIMARY label: the merged messaging payload and OATS_TEAM_LABEL follow it
-  const soul = { name: soulEntry.name, repoKey: soulEntry.repoKey, commit: soulEntry.commit ?? null, team, path: soulEntry.path ?? null };
+  const soul = { name: soulEntry.name, repoKey: soulEntry.repoKey, commit: soulEntry.commit ?? null, path: soulEntry.path ?? null };
+  // Team model v2: the soul's teams HERE (the committed shared teams + oats-local.yaml). An unknown
+  // label (E_TEAM_UNKNOWN) or an ineligible souls.default (E_TEAM_NOT_ELIGIBLE) refuses the soul.
+  const soulTeamsHere = soulTeams(teamModel(discovery?.standalone === true ? null : workspace, local, { workspaceKey: discovery?.key ?? null }), soulKeyOf(soulEntry));
 
   // Standalone: the soul's own repo only, workspace defaults unknown (decision 10).
   // What the soul turned off (feature desktop-facts): its own `off` over a lower layer, and a `<slot>: none`
   // that dropped a workspace default below. Provenance, like slotsFrom.
   const offs = [];
   const declared = discovery?.standalone === true
-    ? composeCapabilities(null, { ...definition, capabilities: soulEntry.capabilities ?? definition.capabilities }, { labels, offs })
-    : composeCapabilities(workspace, definition, { labels, offs });
+    ? composeCapabilities(null, { ...definition, capabilities: soulEntry.capabilities ?? definition.capabilities }, { offs })
+    : composeCapabilities(workspace, definition, { offs });
   const turnedOff = offs;
 
   const modules = [];
@@ -727,21 +681,11 @@ export async function resolveSoul(discovery, soulEntry, { local = null, lock = n
     // provider receives one merged payload without provenance and cannot enforce this itself.
     const hostOnly = hostOnlyKeys(m.manifest);
     const committed = (payload, path, origin) => { assertNoHostOnlyKey(payload, path, hostOnly, m.name); add(payload, origin); };
+    // The provider's settings are base ⊕ soul ⊕ host ⊕ spawn. Teams are not settings: they reach the
+    // provider beside them (OATS_DEFAULT_TEAM*, OATS_TEAMS).
     if (m.layer === "messaging" && isObject(workspace?.messaging)) {
-      // Decision 23 as amended by K (teams contract, co-lead ruling): the provider's settings are
-      // base ⊕ soul ⊕ host ⊕ spawn. No byTeam[<label>] is merged, the primary's included: each
-      // label's base ⊕ byTeam[label] is delivered only in its `teams` entry (teamsOf → OATS_TEAMS),
-      // so settings.team is the default team a host, soul or spawn set. `byTeam` never reaches the
-      // provider, and the primary team's own payload may still not nest one.
-      const { byTeam, ...base } = workspace.messaging;
-      committed(base, "/messaging", { kind: "workspace", at: "oats-workspace.yaml#/messaging" });
-      // Every label's entry still reaches the provider, in OATS_TEAMS (teamsOf), so each one the soul
-      // carries — the primary's and every other — may nest no byTeam and carry no hostOnly key.
-      for (const label of labels) {
-        if (!isObject(byTeam) || !Object.hasOwn(byTeam, label) || !isObject(byTeam[label])) continue;
-        assertNoReservedKey(byTeam[label], `/messaging/byTeam/${label}`);
-        assertNoHostOnlyKey(byTeam[label], `/messaging/byTeam/${label}`, hostOnly, m.name);
-      }
+      assertNoReservedKey(workspace.messaging, "/messaging");
+      committed(workspace.messaging, "/messaging", { kind: "workspace", at: "oats-workspace.yaml#/messaging" });
     }
     if (m.layer && isObject(definition[m.layer])) { assertNoReservedKey(definition[m.layer], `/${m.layer}`); committed(definition[m.layer], `/${m.layer}`, { kind: "soul", at: `soul.yaml#/${m.layer}` }); }
     if (Object.hasOwn(settings, m.name) && isObject(settings[m.name])) { assertNoReservedKey(settings[m.name], `/settings/${m.name}`); add(settings[m.name], { kind: "host", at: `oats-local.yaml#/settings/${m.name}` }); } // the host layer: hostOnly keys are legal here
@@ -805,23 +749,21 @@ export async function resolveSoul(discovery, soulEntry, { local = null, lock = n
   const payloadRevision = revisionOf(payloads);
   const revision = revisionOf({ declRevision, payloadRevision });
   // payloadOrigins is provenance only: it is derived from the same inputs the two revisions already
-  // bind, so it does not enter either fingerprint. `teams` (the eligible teams, teams contract
-  // decision 3) is live messaging state, not composition: it stays out of both fingerprints too, so a
-  // single-label soul's revision is what it was.
+  // bind, so it does not enter either fingerprint. `teams` / `defaultTeam` (team model v2) are
+  // deployment-local messaging state, not composition: they stay out of both fingerprints too.
   // `slotsFrom` (where each filled slot's capability came from) is provenance, like payloadOrigins: outside
   // both fingerprints, so the same capability reached another way is not a composition change. So are
   // `capabilitiesFrom` (the same per composed capability) and `turnedOff` (feature desktop-facts).
-  const teams = teamsOf(discovery?.standalone === true ? null : workspace, labels);
+  const teams = reportRows(soulTeamsHere.teams), defaultTeam = soulTeamsHere.defaultTeam;
   const capabilitiesFrom = Object.fromEntries(modules.map((m) => [m.name, fromOfVia(viaOf.get(m.name))]));
   turnedOff.sort((a, b) => byCodepoint(a.name, b.name));
-  return deepFreeze({ ...decl, payloads, payloadOrigins: origins, teams, slotsFrom, capabilitiesFrom, turnedOff, declRevision, payloadRevision, revision });
+  return deepFreeze({ ...decl, payloads, payloadOrigins: origins, teams, defaultTeam, slotsFrom, capabilitiesFrom, turnedOff, declRevision, payloadRevision, revision });
 }
 
 /** Where a composed capability came from, as the Desktop names it (`layers.<layer>.from`): the soul's own
- *  entry → "soul"; defaults.<slot> or defaults.capabilities → "workspace"; defaults.byTeam.<label> → "team:<label>". */
+ *  entry → "soul"; defaults.<slot> or defaults.capabilities → "workspace". */
 export function fromOfVia(via) {
   if (via === "soul") return "soul";
-  if (typeof via === "string" && via.startsWith("defaults.byTeam.")) return `team:${via.slice("defaults.byTeam.".length)}`;
   if (typeof via === "string" && via.startsWith("defaults.")) return "workspace";
   return null;
 }

package/lib/schedule.mjs

@@ -507,7 +507,7 @@ export function childEnv() {
     "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_HARNESS", "OATS_PREVIOUS_HARNESS", "OATS_RUNTIME", "OATS_PREVIOUS_RUNTIME", "OATS_RETIRE_INTENT",
-    "OATS_TEAM_NAME", "OATS_TEAM_ID", "OATS_TEAM_SCOPE", "OATS_TRIGGER_EVENT_FILE",
+    "OATS_TEAM_NAME", "OATS_TEAM_SCOPE", "OATS_TEAM_ID", "OATS_TEAM_LABEL", "OATS_TEAM_LABELS", "OATS_DEFAULT_TEAM", "OATS_DEFAULT_TEAM_ID", "OATS_DEFAULT_TEAM_FROM", "OATS_TEAMS", "OATS_TEAMS_SOURCE", "OATS_TRIGGER_EVENT_FILE",
   ]) delete env[key];
   return env;
 }

package/lib/teams-verbs.mjs

@@ -0,0 +1,195 @@
+/**
+ * The team model v2 verbs (docs/desktop-cli-api.md, `oats teams`, `oats soul teams`): CONFIG ONLY — they
+ * never call a provider. Each reads the deployment's oats-local.yaml and the committed shared teams, and a
+ * mutation rewrites oats-local.yaml in place (comments and every other key kept), after validating the
+ * result: the local schema, and no label reference the write would leave unknown or ineligible.
+ */
+import { readFileSync } from "node:fs";
+import YAML from "yaml";
+import { parseConfigData } from "./config-data.mjs";
+import { oatsError } from "./errors.mjs";
+import { validateLocal } from "./workspace.mjs";
+import { LOCAL_FILE, TEAM_ID_RE, pointerKey, soulTeams, teamModel, teamProblems, teamReferences } from "./teams.mjs";
+import { writeFileAtomic } from "./packages.mjs";
+
+export const TEAMS_API = 1, SOUL_TEAMS_API = 1;
+const LABEL_RE = /^[a-z0-9][a-z0-9._-]*$/;
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const byCodepoint = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+function fail(code, message, details) { const e = oatsError(code, message, details); e.details = details; return e; }
+
+/** Whether a messaging layer is active in this deployment: the workspace fills the messaging slot. */
+const messagingActive = (workspace) => isObject(workspace?.defaults?.messaging);
+
+/** `oats teams --json`. `ctx`: { deployment, local, workspace (the committed file, or null), workspaceKey }. */
+export function teamsDocument(ctx) {
+  const model = teamModel(ctx.workspace, ctx.local, { workspaceKey: ctx.workspaceKey });
+  const teams = [...model.labels.values()].sort((a, b) => byCodepoint(a.label, b.label))
+    .map((d) => ({ label: d.label, team: d.team, description: d.description, from: d.from, default: d.label === model.defaultTeam, at: d.at }));
+  return {
+    teamsApi: TEAMS_API, deployment: ctx.deployment, defaultTeam: model.defaultTeam, teams,
+    souls: { teams: structuredClone(model.souls.teams), default: structuredClone(model.souls.default) },
+    problems: teamProblems(model, { messaging: messagingActive(ctx.workspace) }),
+  };
+}
+
+/** `oats soul teams <soul>|'*' --json`: `key` is the soul's key ("*" for every soul), `soul` its name. */
+export function soulTeamsDocument(ctx, { soul, key }) {
+  const model = teamModel(ctx.workspace, ctx.local, { workspaceKey: ctx.workspaceKey });
+  const t = soulTeams(model, key);
+  const list = (v) => (Array.isArray(v) ? [...v] : []);
+  return {
+    soulTeamsApi: SOUL_TEAMS_API, soul, key, defaultTeam: t.defaultTeam, teams: t.teams,
+    local: { teams: list(model.souls.teams[key]), default: key === "*" ? null : model.souls.default[key] ?? null },
+    all: list(model.souls.teams["*"]),
+  };
+}
+
+/* ───────────────────────────── writing oats-local.yaml ─────────────────── */
+
+const clone = (v) => (v === undefined ? undefined : structuredClone(v));
+/** The four team keys of a local value, as plain data. */
+const teamState = (local) => ({
+  teams: clone(isObject(local?.teams) ? local.teams : {}),
+  defaultTeam: typeof local?.defaultTeam === "string" ? local.defaultTeam : null,
+  soulsTeams: clone(isObject(local?.souls?.teams) ? local.souls.teams : {}),
+  soulsDefault: clone(isObject(local?.souls?.default) ? local.souls.default : {}),
+});
+const modelOf = (ctx, local) => teamModel(ctx.workspace, local, { workspaceKey: ctx.workspaceKey });
+/** The refusals a state carries (unknown / ineligible references), keyed so a write can tell new ones. */
+const refusals = (ctx, local) => new Map(teamProblems(modelOf(ctx, local))
+  .filter((p) => p.code === "E_TEAM_UNKNOWN" || p.code === "E_TEAM_NOT_ELIGIBLE").map((p) => [`${p.code} ${p.at}`, p]));
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+const readLocal = (ctx) => {
+  const text = readFileSync(ctx.localPath, "utf8");
+  const doc = YAML.parseDocument(text, { keepSourceTokens: true });
+  if (doc.errors?.length) throw fail("E_WORKSPACE_SCHEMA", `${ctx.localPath}: ${doc.errors[0].message}`, { path: ctx.localPath });
+  return { text, doc, local: parseConfigData(text, { origin: { kind: "local", path: ctx.localPath } }).value };
+};
+
+/**
+ * Edit `doc` from `before` to `next` SURGICALLY: only the entries that change are touched, so comments and
+ * styles on everything else (inline comments on sibling entries, flow sequences) are kept. A map or list
+ * left empty is removed, and so is an empty `souls`.
+ */
+function applyState(doc, before, next) {
+  const map = (path, from, to, entry) => {
+    for (const k of Object.keys(from)) if (!Object.hasOwn(to, k)) doc.deleteIn([...path, k]);
+    for (const [k, v] of Object.entries(to)) if (!same(from[k], v)) entry([...path, k], from[k], v);
+    const node = doc.getIn(path);
+    if (YAML.isMap(node) && node.items.length === 0) doc.deleteIn(path);
+  };
+  // A team definition, key by key (its own comments stay on untouched keys).
+  map(["teams"], before.teams, next.teams, (path, was, now) => {
+    if (!isObject(was) || !YAML.isMap(doc.getIn(path))) { doc.setIn(path, now); return; }
+    for (const k of Object.keys(was)) if (!Object.hasOwn(now, k)) doc.deleteIn([...path, k]);
+    for (const [k, v] of Object.entries(now)) if (!same(was[k], v)) doc.setIn([...path, k], v);
+  });
+  if (next.defaultTeam !== before.defaultTeam) { if (next.defaultTeam === null) doc.deleteIn(["defaultTeam"]); else doc.setIn(["defaultTeam"], next.defaultTeam); }
+  // A soul's list, item by item (its style — flow or block — and the other items' comments stay).
+  map(["souls", "teams"], before.soulsTeams, next.soulsTeams, (path, was, now) => {
+    const seq = doc.getIn(path, true);
+    if (!Array.isArray(was) || !YAML.isSeq(seq)) { doc.setIn(path, now); return; }
+    seq.items = seq.items.filter((item) => now.includes(YAML.isScalar(item) ? item.value : item));
+    for (const label of now) if (!was.includes(label)) seq.items.push(doc.createNode(label));
+  });
+  map(["souls", "default"], before.soulsDefault, next.soulsDefault, (path, _was, now) => doc.setIn(path, now));
+  const souls = doc.get("souls");
+  if (YAML.isMap(souls) && souls.items.length === 0) doc.delete("souls");
+}
+
+/**
+ * Rewrite oats-local.yaml. `mutate(state, model)` edits the plain `state` (teamState) and may throw a
+ * refusal; both come from the file AS IT IS NOW (re-read here, never the command's startup snapshot), so
+ * two verbs running together cannot drop each other's change: the write is compare-and-swap — when the
+ * file changed after this read, the edit is redone on the new content (a few times, then E_LOCAL_CHANGED).
+ * `check(local)` may refuse the result before anything is written. → { changed, local } (the value now).
+ */
+function editLocal(ctx, mutate, { check } = {}) {
+  for (let attempt = 0; attempt < 5; attempt++) {
+    const { text, doc, local: current } = readLocal(ctx);
+    const before = teamState(current);
+    const next = teamState(current);
+    mutate(next, modelOf(ctx, current));
+    if (same(next, before)) return { changed: false, local: current };
+    applyState(doc, before, next);
+    const out = doc.toString();
+    const local = parseConfigData(out, { origin: { kind: "local", path: ctx.localPath } }).value;
+    const problems = validateLocal(local);
+    if (problems.length) throw fail("E_WORKSPACE_SCHEMA", `the rewritten oats-local.yaml would be invalid (${problems.map((p) => `${p.path || "/"}: ${p.message}`).join("; ")}); nothing was written`, { problems });
+    const had = refusals(ctx, current);
+    for (const [k, p] of refusals(ctx, local)) if (!had.has(k)) throw fail(p.code, `${p.message}; nothing was written`, Object.fromEntries(Object.entries(p).filter(([key]) => !["code", "severity", "message", "fix"].includes(key))));
+    if (check) check(local);
+    if (readFileSync(ctx.localPath, "utf8") !== text) continue; // changed under us: redo on the new content
+    writeFileAtomic(ctx.localPath, out);
+    return { changed: true, local };
+  }
+  throw fail("E_LOCAL_CHANGED", `${ctx.localPath} kept changing while this edit ran; nothing was written — run it again`, { path: ctx.localPath });
+}
+
+const assertLabel = (label) => {
+  if (typeof label !== "string" || !LABEL_RE.test(label)) throw fail("E_BAD_ARGS", `${JSON.stringify(label)} is not a team label (lowercase letters, digits, and . _ - after the first)`, { label });
+};
+
+/** `oats teams add <label> --team <id> [--description <d>]` → { changed, local }. */
+export function teamsAdd(ctx, label, { team, description } = {}) {
+  assertLabel(label);
+  if (typeof team !== "string" || !team.trim()) throw fail("E_BAD_ARGS", "oats teams add needs --team <provider team id>", { label });
+  if (!TEAM_ID_RE.test(team.trim())) throw fail("E_BAD_ARGS", `${JSON.stringify(team)} is not a team id: it must match ${TEAM_ID_RE.source} (a letter or digit first; no whitespace or control characters; at most 256 characters)`, { label, team });
+  return editLocal(ctx, (s, model) => {
+    if (model.labels.has(label)) {
+      const from = model.labels.get(label).from;
+      throw fail("E_TEAM_EXISTS", `team ${label} is already declared (${from === "shared" ? "shared, in oats-workspace.yaml" : "local, in oats-local.yaml"})${from === "local" ? ": remove it first (`oats teams remove`) to redefine it" : ""}`, { label, from });
+    }
+    s.teams[label] = { team: team.trim(), ...(typeof description === "string" && description ? { description } : {}) };
+    // The first team added becomes the deployment's default.
+    if (s.defaultTeam === null) s.defaultTeam = label;
+  });
+}
+
+/** `oats teams remove <label>`: a LOCAL team nothing references (no cascade). */
+export function teamsRemove(ctx, label) {
+  return editLocal(ctx, (s, model) => {
+    if (!model.local.has(label)) {
+      if (model.shared.has(label)) throw fail("E_TEAM_SHARED", `team ${label} is shared (declared in oats-workspace.yaml): it is edited by a PR to that file, never removed here`, { label, at: model.shared.get(label).at });
+      throw fail("E_TEAM_UNKNOWN", `team ${JSON.stringify(label)} is not declared`, { label });
+    }
+    // A label also declared in the committed file still resolves after the local copy goes (the
+    // collision's fix): its references stay valid, so only a purely local label must be unreferenced.
+    const usedBy = model.shared.has(label) ? [] : teamReferences(model, label);
+    if (usedBy.length) throw fail("E_TEAM_IN_USE", `team ${label} is still referenced (${usedBy.join(", ")}): remove the references first (\`oats teams default\`, \`oats soul teams … --remove ${label}\`)`, { label, usedBy });
+    delete s.teams[label];
+  });
+}
+
+/** `oats teams default <label>`: a label of either file. */
+export function teamsDefault(ctx, label) {
+  return editLocal(ctx, (s, model) => {
+    if (!model.labels.has(label)) throw fail("E_TEAM_UNKNOWN", `team ${JSON.stringify(label)} is not declared: \`oats teams add\` it first`, { label });
+    s.defaultTeam = label;
+  });
+}
+
+/**
+ * `oats soul teams <soul>|'*' [--add a,b] [--remove a,b] [--default <l> | --clear-default]`.
+ * `key` is the soul's key ("*" for every soul). → { changed, local }.
+ */
+export function soulTeamsEdit(ctx, key, { add = [], remove = [], setDefault = null, clearDefault = false } = {}) {
+  if (key === "*" && (setDefault !== null || clearDefault)) throw fail("E_BAD_ARGS", "a default is per soul: --default / --clear-default need a soul, not '*' (the deployment's default is `oats teams default`)", { soul: key });
+  if (setDefault !== null && clearDefault) throw fail("E_BAD_ARGS", "choose --default <label> or --clear-default, not both");
+  // --default must name one of the soul's teams after the write.
+  const check = setDefault === null ? undefined : (local) => {
+    try { soulTeams(modelOf(ctx, local), key); }
+    catch (e) { if (e.code === "E_TEAM_NOT_ELIGIBLE") throw fail("E_TEAM_NOT_ELIGIBLE", `${e.message}; nothing was written`, { soul: key, label: setDefault, at: `${LOCAL_FILE}#/souls/default/${pointerKey(key)}` }); throw e; }
+  };
+  return editLocal(ctx, (s, model) => {
+    for (const label of [...add, ...remove, ...(setDefault !== null ? [setDefault] : [])]) {
+      if (!model.labels.has(label)) throw fail("E_TEAM_UNKNOWN", `team ${JSON.stringify(label)} is not declared: \`oats teams add\` it first`, { label });
+    }
+    const list = Array.isArray(s.soulsTeams[key]) ? s.soulsTeams[key] : [];
+    const next = [...list.filter((l) => !remove.includes(l)), ...add.filter((l) => !list.includes(l) && !remove.includes(l))].filter((l, i, a) => a.indexOf(l) === i);
+    if (next.length) s.soulsTeams[key] = next; else delete s.soulsTeams[key];
+    if (clearDefault) delete s.soulsDefault[key];
+    if (setDefault !== null) s.soulsDefault[key] = setDefault;
+  }, { check });
+}

package/lib/teams.mjs

@@ -0,0 +1,190 @@
+/**
+ * Team model v2 (docs/design/2026-09-27-team-model-v2.md, option B), pure.
+ *
+ * Where teams live:
+ *   - the committed oats-workspace.yaml `teams.<label> = { description?, team? }`: SHARED teams (edited
+ *     by PR). A shared team without `team` is declared but not yet created (unmapped);
+ *   - the deployment's oats-local.yaml `teams.<label> = { team, description? }`: LOCAL teams, plus
+ *     `defaultTeam: <label>`, `souls.teams: { "*" | <soul key>: [labels] }` and
+ *     `souls.default: { <soul key>: <label> }`.
+ * A soul key is the soul's bare name, or `<package>/<soul>` for a package soul.
+ *
+ * Resolution: labels = shared ∪ local (a label in both is `team-label-collision`; the SHARED definition
+ * wins). defaultOf(soul) = souls.default[soul] ?? defaultTeam; a soul's teams = {defaultOf} ∪
+ * souls.teams["*"] ∪ souls.teams[soul]. An undeclared label the soul reaches is E_TEAM_UNKNOWN; a
+ * souls.default outside the soul's teams is E_TEAM_NOT_ELIGIBLE.
+ *
+ * Rows (docs/desktop-cli-api.md, Team model v2): TeamRow { label, team, default, from: shared|local },
+ * the default first, then by label. Reports carry unmapped rows (team null); OATS_TEAMS and
+ * instance.json carry mapped rows only. DefaultTeam { label, team, from: deployment|soul } | null.
+ */
+import { oatsError } from "./errors.mjs";
+
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const str = (v) => (typeof v === "string" && v ? v : null);
+const labelsOf = (v) => (Array.isArray(v) ? v.filter((l) => typeof l === "string") : []);
+const byCodepoint = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+export const pointerKey = (k) => String(k).replace(/~/g, "~0").replace(/\//g, "~1");
+function fail(code, message, details) {
+  const e = oatsError(code, message, details);
+  e.details = details;
+  return e;
+}
+
+export const LOCAL_FILE = "oats-local.yaml";
+/** A provider team id, as both schemas' `teams.*.team` pattern: the kernel's SAFETY rule only (never
+ *  `-`-led, so never an option; no whitespace or control characters; bounded). The messaging provider
+ *  validates its own id shape. Keep equal to docs/oats-{local,workspace}.schema.json. */
+export const TEAM_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:@/+-]{0,255}$/;
+/** What 0.30 removed, named by the schema problems that replace them. */
+export const TEAM_MEMBERSHIP_MOVED = "team membership is local since 0.30: `oats soul teams`";
+export const BY_TEAM_REMOVED = "byTeam was removed in 0.30: a team's provider id is teams.<label>.team (oats-workspace.yaml for a shared team, oats-local.yaml for a local one)";
+
+const UNMAPPED_FIX = "its owner runs `oats aweb setup`, then commits the id";
+
+/** The deployment's teams from the committed workspace and oats-local.yaml (either may be null). */
+export function teamModel(workspace, local, { workspaceKey = null } = {}) {
+  const shared = new Map(), localTeams = new Map();
+  for (const [label, def] of Object.entries(isObject(workspace?.teams) ? workspace.teams : {})) {
+    shared.set(label, { label, team: str(def?.team), description: str(def?.description), from: "shared",
+      at: `${workspaceKey ? `${workspaceKey}:` : ""}oats-workspace.yaml#/teams/${pointerKey(label)}` });
+  }
+  for (const [label, def] of Object.entries(isObject(local?.teams) ? local.teams : {})) {
+    localTeams.set(label, { label, team: str(def?.team), description: str(def?.description), from: "local", at: `${LOCAL_FILE}#/teams/${pointerKey(label)}` });
+  }
+  const souls = isObject(local?.souls) ? local.souls : {};
+  return {
+    shared, local: localTeams,
+    labels: new Map([...localTeams, ...shared]), // the committed definition wins a collision
+    defaultTeam: str(local?.defaultTeam),
+    souls: { teams: isObject(souls.teams) ? souls.teams : {}, default: isObject(souls.default) ? souls.default : {} },
+  };
+}
+
+/** The key a soul has in souls.teams / souls.default. */
+export function soulKeyOf(soulEntry) {
+  return typeof soulEntry?.package === "string" && typeof soulEntry.qualifiedName === "string" ? soulEntry.qualifiedName : soulEntry.name;
+}
+
+const unknown = (label, at) => fail("E_TEAM_UNKNOWN", `team ${JSON.stringify(label)} is not declared (${at}): declare it with \`oats teams add\`, or in oats-workspace.yaml teams: for a shared team`, { label, at });
+
+/**
+ * One soul's teams here (key "*": the deployment default + souls.teams["*"]).
+ * → { key, defaultTeam: DefaultTeam | null, teams: [TeamRow + via] } | throws E_TEAM_UNKNOWN / E_TEAM_NOT_ELIGIBLE.
+ * `via` ⊂ ["default", "*", "soul"], in that order: why the soul has the team.
+ */
+export function soulTeams(model, key) {
+  const known = (label, at) => { if (!model.labels.has(label)) throw unknown(label, at); };
+  if (model.defaultTeam !== null) known(model.defaultTeam, `${LOCAL_FILE}#/defaultTeam`);
+  const star = labelsOf(model.souls.teams["*"]);
+  star.forEach((l, i) => known(l, `${LOCAL_FILE}#/souls/teams/*/${i}`));
+  const own = key === "*" ? [] : labelsOf(model.souls.teams[key]);
+  own.forEach((l, i) => known(l, `${LOCAL_FILE}#/souls/teams/${pointerKey(key)}/${i}`));
+  const override = key === "*" ? null : str(model.souls.default[key]);
+  if (override !== null) {
+    const at = `${LOCAL_FILE}#/souls/default/${pointerKey(key)}`;
+    known(override, at);
+    if (override !== model.defaultTeam && !star.includes(override) && !own.includes(override)) {
+      throw fail("E_TEAM_NOT_ELIGIBLE", `souls.default.${key} is ${JSON.stringify(override)}, which is not one of ${key}'s teams here — add it first (\`oats soul teams ${key} --add ${override}\`)`, { soul: key, label: override, at });
+    }
+  }
+  const defaultLabel = override ?? model.defaultTeam;
+  const via = new Map();
+  const add = (label, why) => { const v = via.get(label) ?? []; if (!v.includes(why)) v.push(why); via.set(label, v); };
+  if (defaultLabel !== null) add(defaultLabel, "default");
+  for (const l of star) add(l, "*");
+  for (const l of own) add(l, "soul");
+  const teams = [...via].map(([label, v]) => {
+    const d = model.labels.get(label);
+    return { label, team: d.team, default: label === defaultLabel, from: d.from, via: v };
+  }).sort((a, b) => (b.default - a.default) || byCodepoint(a.label, b.label));
+  const defaultTeam = defaultLabel === null ? null : { label: defaultLabel, team: model.labels.get(defaultLabel).team, from: override !== null ? "soul" : "deployment" };
+  return { key, defaultTeam, teams };
+}
+
+/** TeamRows as the reports carry them (unmapped included, no `via`). */
+export const reportRows = (teams) => (teams || []).map(({ label, team, default: d, from }) => ({ label, team, default: d, from }));
+/** TeamRows as OATS_TEAMS and instance.json carry them: mapped only. */
+export const envRows = (teams) => reportRows(teams).filter((r) => r.team !== null);
+
+/** Every reference to `label` in oats-local.yaml, in written order (`oats teams remove` refuses on any). */
+export function teamReferences(model, label) {
+  const refs = [];
+  if (model.defaultTeam === label) refs.push("defaultTeam");
+  for (const [key, list] of Object.entries(model.souls.teams)) if (labelsOf(list).includes(label)) refs.push(`souls.teams:${key}`);
+  for (const [key, l] of Object.entries(model.souls.default)) if (l === label) refs.push(`souls.default:${key}`);
+  return refs;
+}
+
+const collisionProblem = (label, shared, local) => ({
+  code: "team-label-collision", label, severity: "warning",
+  shared: { team: shared.team, description: shared.description, at: shared.at },
+  local: { team: local.team, description: local.description, at: local.at },
+  message: `team ${label} is declared in both oats-workspace.yaml (shared) and oats-local.yaml (local); the shared definition wins`,
+  fix: "rename the local label in oats-local.yaml",
+});
+const unmappedProblem = (d, isDefault) => isDefault
+  ? { code: "team-unmapped", label: d.label, default: true, severity: "failure", at: d.at, message: `the default team ${d.label} has no provider id yet`, fix: `${UNMAPPED_FIX}; or choose another default with \`oats teams default\`` }
+  : { code: "team-unmapped", label: d.label, default: false, severity: "warning", at: d.at, message: `shared team ${d.label} has no provider id yet`, fix: UNMAPPED_FIX };
+const unconfiguredProblem = () => ({ code: "E_TEAM_UNCONFIGURED", severity: "failure", message: "no teams configured: run `oats aweb setup`", fix: "run `oats aweb setup` (it creates the teams and sets the default), or `oats teams add <label> --team <id>`" });
+const refusalProblem = (e) => ({ code: e.code, ...e.details, severity: "failure", message: e.message,
+  fix: e.code === "E_TEAM_UNKNOWN" ? "declare the team (`oats teams add`), or remove the reference" : "add the label to the soul's teams (`oats soul teams … --add`), or clear its default (`--clear-default`)" });
+
+/**
+ * Readiness problems. Without `key`: the deployment's (`oats teams`): collisions, unmapped shared
+ * teams (a failure when it is `defaultTeam`), every unknown reference, every ineligible
+ * souls.default. With `key`: only what concerns that soul (`default` marks ITS default).
+ * `messaging`: a messaging layer is active, so no default is E_TEAM_UNCONFIGURED.
+ */
+export function teamProblems(model, { key = null, messaging = false } = {}) {
+  const problems = [];
+  if (key !== null) {
+    let t;
+    try { t = soulTeams(model, key); }
+    catch (e) { if (e.code === "E_TEAM_UNKNOWN" || e.code === "E_TEAM_NOT_ELIGIBLE") return [refusalProblem(e)]; throw e; }
+    for (const r of t.teams) if (model.shared.has(r.label) && model.local.has(r.label)) problems.push(collisionProblem(r.label, model.shared.get(r.label), model.local.get(r.label)));
+    for (const r of t.teams) if (r.team === null) problems.push(unmappedProblem(model.labels.get(r.label), r.default));
+    if (messaging && t.defaultTeam === null) problems.push(unconfiguredProblem());
+    return problems;
+  }
+  const labels = [...model.labels.keys()].sort(byCodepoint);
+  for (const label of labels) if (model.shared.has(label) && model.local.has(label)) problems.push(collisionProblem(label, model.shared.get(label), model.local.get(label)));
+  for (const label of labels) { const d = model.labels.get(label); if (d.team === null) problems.push(unmappedProblem(d, label === model.defaultTeam)); }
+  const known = (label, at) => { if (!model.labels.has(label)) problems.push(refusalProblem(unknown(label, at))); };
+  if (model.defaultTeam !== null) known(model.defaultTeam, `${LOCAL_FILE}#/defaultTeam`);
+  for (const [k, list] of Object.entries(model.souls.teams)) labelsOf(list).forEach((l, i) => known(l, `${LOCAL_FILE}#/souls/teams/${pointerKey(k)}/${i}`));
+  for (const [k, l] of Object.entries(model.souls.default)) if (typeof l === "string") known(l, `${LOCAL_FILE}#/souls/default/${pointerKey(k)}`);
+  for (const [k, l] of Object.entries(model.souls.default)) {
+    if (typeof l !== "string" || !model.labels.has(l)) continue;
+    try { soulTeams(model, k); } catch (e) { if (e.code === "E_TEAM_NOT_ELIGIBLE" && e.details.soul === k) problems.push(refusalProblem(e)); else if (e.code !== "E_TEAM_UNKNOWN") throw e; }
+  }
+  if (messaging && model.defaultTeam === null) problems.push(unconfiguredProblem());
+  return problems;
+}
+
+/**
+ * The provider environment (docs/desktop-cli-api.md, The provider environment) from a soul's teams
+ * `{ defaultTeam, teams, source: "live"|"recorded" }`, or null when they are not known. A name that
+ * does not apply is `undefined`, so a child process never inherits an ambient value. The pre-0.30
+ * names are always unset.
+ */
+export function teamsEnv(t) {
+  const known = isObject(t) && Array.isArray(t.teams);
+  const d = known && isObject(t.defaultTeam) ? t.defaultTeam : null;
+  return {
+    OATS_DEFAULT_TEAM: d?.label ?? undefined,
+    OATS_DEFAULT_TEAM_ID: d?.team ?? undefined,
+    OATS_DEFAULT_TEAM_FROM: d?.from ?? undefined,
+    OATS_TEAMS: known ? JSON.stringify(envRows(t.teams)) : undefined,
+    OATS_TEAMS_SOURCE: known && (t.source === "live" || t.source === "recorded") ? t.source : undefined,
+    OATS_TEAM_LABEL: undefined, OATS_TEAM_LABELS: undefined, OATS_TEAM_ID: undefined,
+  };
+}
+
+/** A home's spawn-time teams (instance.json `teams` / `defaultTeam`) → { teams, defaultTeam }; teams null
+ *  when the home recorded none in this shape (spawned before 0.30: its teams are unknown, never guessed). */
+export function recordedTeams(meta) {
+  const rows = Array.isArray(meta?.teams) && meta.teams.every((r) => isObject(r) && typeof r.label === "string" && typeof r.default === "boolean") ? meta.teams : null;
+  const d = isObject(meta?.defaultTeam) && typeof meta.defaultTeam.label === "string" ? meta.defaultTeam : null;
+  return { teams: rows, defaultTeam: rows ? d : null };
+}

package/lib/triggers.mjs

@@ -483,8 +483,8 @@ export function tickTriggers(ws, { now = new Date(), io, dryRun = false, ctx = n
   for (const e of entries) {
     const id = e.id;
     // A workspace trigger another host runs is not this tick's business; one NAMED for this host
-    // that it cannot run (another gh account) is reported every tick until someone fixes it.
-    if (e.placement.reason) { if (e.placement.reason === "owner-mismatch" && e.placement.enabledHere) rec(id, "not-here", { reason: e.placement.reason, detail: e.placement.detail }); continue; }
+    // that it cannot run (another gh account, or not trusted here) is reported every tick until someone fixes it.
+    if (e.placement.reason) { if (["owner-mismatch", "untrusted"].includes(e.placement.reason) && e.placement.enabledHere) rec(id, "not-here", { reason: e.placement.reason, detail: e.placement.detail }); continue; }
     if (e.invalid) { if (e.placement.enabledHere) rec(id, "invalid", { error: e.invalid.message }); continue; }
     if (!e.placement.runsHere) continue;
     const def = runDef(e);