@awebai/oats 0.29.3 → 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

@@ -21,7 +21,7 @@
  *  succeeded. A launch whose side effects cannot be confirmed stays
  *  `unknown` with its slot held until `reconcile` proves what happened. */
 import { spawnSync } from "node:child_process";
-import { closeSync, constants as fsConstants, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { closeSync, constants as fsConstants, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
@@ -31,7 +31,7 @@ import { loadLocal } from "./workspace.mjs";
 import { noteRuntimeName } from "./deprecation.mjs";
 import { tickTriggers } from "./triggers.mjs";
 import { resolveMemberClone } from "./instance-resolution.mjs";
-import { AUTOMATION_ID_RE, automationContext, automationError, baseRow, localEntry, localId, soulOriginOf, splitId } from "./automations.mjs";
+import { AUTOMATION_ID_RE, MODEL_RE, automationContext, automationError, baseRow, localEntry, localId, soulOriginOf, splitId } from "./automations.mjs";
 import { RESERVED_LAUNCH_ENV, MAX_INSTANCE_NAME, findAgent, findInstanceHomes, inspectInstanceSession, inputInstanceSession, startInstanceSession, retirePendingMarkerPath } from "./core.mjs";
 
 export const SCHEDULE_FILE = "oats-schedules.json";
@@ -208,6 +208,12 @@ export function readRegistry() {
   if (!Array.isArray(reg.workspaces)) reg.workspaces = [];
   if (!Number.isInteger(reg.maxConcurrent) || reg.maxConcurrent < 1) reg.maxConcurrent = 1;
   if (!Number.isInteger(reg.tickIntervalSec) || reg.tickIntervalSec < 60) reg.tickIntervalSec = 60;
+  // The host cap on trigger-spawned live instances (re-review B #5): absent = unbounded (each
+  // trigger's own concurrency.max still applies). Separate from maxConcurrent: a running scheduled
+  // job never holds a trigger, and trigger homes never hold a schedule. Hand-edited, so refused loudly.
+  if (reg.triggersMaxConcurrent !== undefined && !(Number.isSafeInteger(reg.triggersMaxConcurrent) && reg.triggersMaxConcurrent >= 1)) {
+    throw scheduleError("E_SCHEDULE_INVALID", `${join(hostScheduleDir(), "registry.json")}: triggersMaxConcurrent must be a positive integer, or absent for no host cap (got ${JSON.stringify(reg.triggersMaxConcurrent)})`, { field: "triggersMaxConcurrent" });
+  }
   return reg;
 }
 export function writeRegistry(reg) { writeJson(join(hostScheduleDir(), "registry.json"), reg); }
@@ -300,14 +306,14 @@ export function validateDefinition(ws, def, { checkAgent = true } = {}) {
   validateCron(def.cron, def.tz);
   const out = { id, enabled, cron: def.cron.trim(), tz: def.tz.trim(), kind: def.kind };
   if (def.kind === "spawn") {
-    if (typeof def.agent !== "string" || !def.agent.trim()) throw scheduleError("E_SCHEDULE_INVALID", "agent: soul name required", { field: "agent" });
+    if (typeof def.agent !== "string" || !def.agent.trim() || def.agent.trim().startsWith("-")) throw scheduleError("E_SCHEDULE_INVALID", "agent: soul name required (not an option)", { field: "agent" });
     out.agent = def.agent.trim();
     if (def.agentsRoot !== undefined) {
       const known = scopeRoots(ws);
       if (typeof def.agentsRoot !== "string" || !isAbsolute(def.agentsRoot) || !inside(ws, def.agentsRoot) || !known.includes(resolve(def.agentsRoot))) throw scheduleError("E_SCHEDULE_INVALID", `agentsRoot: must be one of this scope's agents roots (${known.join(", ") || "none"})`, { field: "agentsRoot" });
       out.agentsRoot = resolve(def.agentsRoot);
     }
-    if (def.repo !== undefined) { if (typeof def.repo !== "string" || !def.repo.trim()) throw scheduleError("E_SCHEDULE_INVALID", "repo: the work repository path, as oats spawn --repo", { field: "repo" }); out.repo = def.repo; }
+    if (def.repo !== undefined) { if (typeof def.repo !== "string" || !def.repo.trim() || def.repo.startsWith("-")) throw scheduleError("E_SCHEDULE_INVALID", "repo: the work repository path, as oats spawn --repo", { field: "repo" }); out.repo = def.repo; }
     if (def.backend !== undefined) { if (!BACKENDS.has(def.backend)) throw scheduleError("E_SCHEDULE_INVALID", "backend: tmux or herdr", { field: "backend" }); out.backend = def.backend; }
     if (def.purpose !== undefined) { if (typeof def.purpose !== "string" || !/^[a-z0-9-]{1,40}$/.test(def.purpose)) throw scheduleError("E_SCHEDULE_INVALID", "purpose: lowercase letters, digits and dashes", { field: "purpose" }); out.purpose = def.purpose; }
     // A run spawns <agent>-<purpose|id>-<YYYYMMDDHHMM>; instance names are at most
@@ -323,7 +329,7 @@ export function validateDefinition(ws, def, { checkAgent = true } = {}) {
     }
     if (def.launchConfig !== undefined) { if (typeof def.launchConfig !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(def.launchConfig)) throw scheduleError("E_SCHEDULE_INVALID", "launchConfig: the name of a launch configuration on the running host (oats-local.yaml launch-configs)", { field: "launchConfig" }); out.launchConfig = def.launchConfig; }
     if (def.harness !== undefined) { if (!HARNESSES.has(def.harness)) throw scheduleError("E_SCHEDULE_INVALID", "harness: pi, claude or codex", { field: "harness" }); out.harness = def.harness; }
-    if (def.model !== undefined) { if (typeof def.model !== "string") throw scheduleError("E_SCHEDULE_INVALID", "model: string", { field: "model" }); out.model = def.model; }
+    if (def.model !== undefined) { if (typeof def.model !== "string" || !MODEL_RE.test(def.model)) throw scheduleError("E_SCHEDULE_INVALID", "model: a model id: a letter or digit, then letters, digits and . _ : / @ + - [ ] (at most 128 characters)", { field: "model" }); out.model = def.model; }
     if (def.yolo !== undefined) { if (typeof def.yolo !== "boolean") throw scheduleError("E_SCHEDULE_INVALID", "yolo: boolean", { field: "yolo" }); out.yolo = def.yolo; }
     if (def.wake !== undefined) {
       const w = def.wake;
@@ -402,6 +408,10 @@ export function validateWorkspaceSchedule(dep, a) {
   if (spec.kind === "command") {
     if (d.cwd !== undefined && (typeof d.cwd !== "string" || isAbsolute(d.cwd))) throw scheduleError("E_SCHEDULE_INVALID", "cwd: a directory relative to the deployment (a workspace schedule never names a machine path)", { field: "cwd" });
     spec.cwd = resolve(dep, d.cwd ?? ".");
+    // Inside the deployment, `..` and symlinks included (re-review B #4): Git content never picks a
+    // directory elsewhere on the host.
+    const real = (p) => { try { return realpathSync(p); } catch { return resolve(p); } };
+    if (!inside(real(dep), real(spec.cwd))) throw scheduleError("E_SCHEDULE_INVALID", `cwd: ${JSON.stringify(d.cwd)} leaves the deployment; a workspace command's cwd is a directory inside it`, { field: "cwd" });
   }
   const out = validateDefinition(dep, spec, { checkAgent: false });
   delete out.enabled;
@@ -497,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;
 }
@@ -521,19 +531,22 @@ export function workspaceSpawnContext(ws) {
  *  `io.oatsBin`, `io.commandTimeoutMs` and `io.noLaunch` are the test seams. */
 function spawnViaCli(ws, root, agent, opts, context, io) {
   if (context.error) throw scheduleError(context.error.code, `this deployment realizes a workspace (${context.dir}) but its oats-local.yaml cannot be read: ${context.error.message}`);
-  const argv = ["spawn", agent.name, "--dir", context.dir, ...(opts.discover ? [] : ["--agents-root", root]), "--purpose", opts.purpose, "--json"];
-  if (opts.launchConfig) argv.push("--launch-config", opts.launchConfig);
-  if (opts.harness) argv.push("--harness", opts.harness);
-  if (opts.model) argv.push("--model", opts.model);
-  if (opts.backend) argv.push("--backend", opts.backend);
-  if (opts.repo) argv.push("--repo", opts.repo);
+  // Every value travels as ONE `--flag=value` token, so no value can be read as a flag of its own;
+  // the soul is the one positional, and an option-shaped one is refused.
+  if (String(agent.name).startsWith("-")) throw scheduleError("E_SCHEDULE_INVALID", `agent: ${JSON.stringify(agent.name)} is not a soul name`, { field: "agent" });
+  const argv = ["spawn", agent.name, `--dir=${context.dir}`, ...(opts.discover ? [] : [`--agents-root=${root}`]), `--purpose=${opts.purpose}`, "--json"];
+  if (opts.launchConfig) argv.push(`--launch-config=${opts.launchConfig}`);
+  if (opts.harness) argv.push(`--harness=${opts.harness}`);
+  if (opts.model) argv.push(`--model=${opts.model}`);
+  if (opts.backend) argv.push(`--backend=${opts.backend}`);
+  if (opts.repo) argv.push(`--repo=${opts.repo}`);
   if (opts.yolo === true) argv.push("--yolo"); else if (opts.yolo === false) argv.push("--no-yolo");
   if (opts.launch === false) argv.push("--no-launch");
   // The task is multi-line text of arbitrary size: it travels as a private file, never in argv.
   mkdirSync(join(stateDir(ws), "tasks"), { recursive: true });
   const taskFile = join(stateDir(ws), "tasks", `${opts.purpose}-${process.pid}.md`);
   writeFileSync(taskFile, opts.task, { mode: 0o600 });
-  argv.push("--task-file", taskFile);
+  argv.push(`--task-file=${taskFile}`);
   let r;
   try { r = spawnSync(process.execPath, [io?.oatsBin || OATS_BIN, ...argv], { cwd: context.dir, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: io?.commandTimeoutMs || COMMAND_TIMEOUT_MS, killSignal: "SIGTERM", maxBuffer: 16 * 1024 * 1024, env: childEnv() }); }
   finally { try { rmSync(taskFile, { force: true }); } catch { /* best effort */ } }
@@ -866,7 +879,7 @@ export function tickHost({ now = new Date(), io, dryRun = false } = {}) {
     }
     // Triggers: each scope's event-driven spawns, polled at their own interval (lib/triggers.mjs).
     for (const ws of wsList) {
-      try { considered.push(...tickTriggers(ws, { now, io, dryRun, ctx: contexts.get(ws) })); }
+      try { considered.push(...tickTriggers(ws, { now, io, dryRun, ctx: contexts.get(ws), reg, wsList })); }
       catch (e) { considered.push({ workspace: ws, action: "error", error: `triggers: ${e.message}` }); }
     }
     if (!dryRun) writeHostState({ ...readHostState(), lastTick: now.toISOString(), minute: minuteKey(minuteStart(now)) });
@@ -978,10 +991,11 @@ export function testSchedule(ws, qid, io, { now = new Date(), ctx = null } = {})
       const { root, discover } = resolveScheduledAgent(ws, def);
       const context = workspaceSpawnContext(ws);
       if (context.error) throw scheduleError(context.error.code, context.error.message);
-      const argv = ["spawn", def.agent, "--dir", context.dir, ...(discover ? [] : ["--agents-root", root]), "--preview", "--json"];
-      if (def.launchConfig) argv.push("--launch-config", def.launchConfig);
-      if (def.harness) argv.push("--harness", def.harness);
-      if (def.model) argv.push("--model", def.model);
+      if (String(def.agent).startsWith("-")) throw scheduleError("E_SCHEDULE_INVALID", `agent: ${JSON.stringify(def.agent)} is not a soul name`, { field: "agent" });
+      const argv = ["spawn", def.agent, `--dir=${context.dir}`, ...(discover ? [] : [`--agents-root=${root}`]), "--preview", "--json"];
+      if (def.launchConfig) argv.push(`--launch-config=${def.launchConfig}`);
+      if (def.harness) argv.push(`--harness=${def.harness}`);
+      if (def.model) argv.push(`--model=${def.model}`);
       const r = spawnSync(process.execPath, [io?.oatsBin || OATS_BIN, ...argv], { cwd: context.dir, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: io?.commandTimeoutMs || COMMAND_TIMEOUT_MS, killSignal: "SIGTERM", maxBuffer: 16 * 1024 * 1024, env: childEnv() });
       const envelope = parseEnvelopeText(r.stdout);
       if (!envelope || typeof envelope.ok !== "boolean") throw scheduleError("E_SPAWN_FAILED", `the spawn preview answered no valid envelope (exit ${r.status ?? r.signal})`);

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 });
+}