@awebai/oats 0.37.0 → 0.38.1

package/bin/oats.mjs

@@ -36,7 +36,7 @@ import {
   writeFileAtomic, LOCK_FILE, readLock, readLockIfPresent, writeLock, resolvePackages, memoizedRemote,
   classifyPackageValue, parsePackageRequest } from "../lib/packages.mjs";
 import { loadLocal, validateWorkspace, validateLocal, discoverPackageSouls, workspaceWarnings, memberRowByKey } from "../lib/workspace.mjs";
-import { migrationProblems, recordedTeams, reportRows, soulKeyOf, soulTeams, teamModel } from "../lib/teams.mjs";
+import { discoveredTeamKeys, isTeamRefusal, localTeamsClosedProblem, recordedTeams, reportRows, soulKeyOf, soulTeams, teamKeyOf, teamModel } from "../lib/teams.mjs";
 import { launchLayers } from "../lib/launch-preference.mjs";
 import { parseConfigData } from "../lib/config-data.mjs";
 import * as remoteModule from "../lib/remote.mjs";
@@ -221,17 +221,18 @@ async function doctorComposition(ctx, soulName, ws, bail) {
   } finally { for (const c of cleanups) { try { c(); } catch { /* best effort: temporary copies only */ } } }
 }
 
-/** team-model-3-migration in doctor (0.36.x), OFFLINE like the rest of doctor: oats-local.yaml, and for its
- *  local teams the workspace file this machine's parsed cache holds (cachedWorkspace: no git process, no
- *  network). Without that file, whether local teams need `localTeams: true` is said to be unchecked
- *  (information), never guessed. The standalone view has no workspace rules. → { problems, information } */
-function doctorTeamMigration(local) {
+/** Local teams the workspace does not allow (team model 3: E_WORKSPACE_SCHEMA local-teams-closed), in
+ *  doctor, OFFLINE like the rest of doctor: oats-local.yaml, and the workspace file this machine's parsed
+ *  cache holds (cachedWorkspace: no git process, no network). Without that file, whether the local teams are
+ *  allowed is said to be unchecked (information), never guessed. The standalone view has no workspace
+ *  rules. → { problems, information } */
+function doctorLocalTeams(local) {
   const standalone = typeof local.standalone === "string" && local.standalone !== "";
   const file = standalone ? null : cachedWorkspace(local.workspace)?.file ?? null;
   const model = teamModel(file, local);
-  const unchecked = !standalone && file === null && model.migration.teamKeys.length > 0;
-  return { problems: migrationProblems(model),
-    information: unchecked ? ["team-model-3-migration: whether oats-local.yaml teams/defaultTeam need localTeams: true couldn't be checked: this deployment hasn't observed its workspace yet; run oats sync"] : [] };
+  const declared = ["teams", "defaultTeam"].some((k) => Object.hasOwn(local, k));
+  return { problems: model.closedKeys.length ? [localTeamsClosedProblem(model.closedKeys)] : [],
+    information: !standalone && file === null && declared ? ["local-teams-closed: whether oats-workspace.yaml allows oats-local.yaml teams/defaultTeam (localTeams: true) couldn't be checked: this deployment hasn't observed its workspace yet; run oats sync"] : [] };
 }
 
 /** Workspace-model v2 doctor data, OFFLINE: the deployment declaration found
@@ -411,7 +412,9 @@ async function workspaceTarget(bail, { command, liveTeams = true }) {
     if (!existsSync(join(deployment, "oats-local.yaml"))) return bail("E_HOME_MISMATCH", `${homeFlag} is not at <deployment>/agents/<soul>/instances/<name>: ${deployment} has no oats-local.yaml`, { home: homeFlag, expected: join(deployment, "oats-local.yaml") });
     if (flag("dir") !== undefined) { let given = null; try { given = dirname(loadLocal(dirFlag()).path); } catch { given = dirFlag(); } if (realOrResolved(given) !== realOrResolved(deployment)) return bail("E_HOME_MISMATCH", `--dir ${dirFlag()} is not the deployment of ${homeFlag} (${deployment}); omit --dir for a home`); }
     if (rootFlag && realOrResolved(rootFlag) !== realOrResolved(join(deployment, "agents"))) return bail("E_HOME_MISMATCH", `--agents-root ${rootFlag} is not the agents root of ${homeFlag}`);
-    return homeTarget(homeFlag, meta, { remoteOptions, discover: command === "readiness", live: liveTeams });
+    // A typed refusal (the deployment's removed team keys, team model 3) answers as one, as for --soul.
+    try { return await homeTarget(homeFlag, meta, { remoteOptions, discover: command === "readiness", live: liveTeams }); }
+    catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_")) return bail(e.code, e.message, e.details); throw e; }
   }
   try { if (!isWorkspaceContext(dirFlag())) return bail("E_LOCAL_MISSING", `${command} reads a workspace deployment, and none is in reach of ${dirFlag()} (no oats-local.yaml walking up; \`oats onboard\` creates one) — or pass --home <abs> of a workspace instance`); }
   catch (e) { return bail(e?.code || "E_WORKSPACE_SCHEMA", e?.message || String(e), e?.details); }
@@ -597,13 +600,13 @@ function legacyLayoutProblems(root) {
 async function doctorWorkspaceJson(ctx, soulName, ws) {
   const composition = await doctorComposition(ctx, soulName, ws, (code, msg, details) => jsonFail(code, msg, details));
   const agentsRoot = join(dirname(ws.local.path), "agents");
-  const migration = doctorTeamMigration(ws.local.value);
-  const problems = [...legacyLayoutProblems(agentsRoot), readableInstanceHomes(agentsRoot), ...migration.problems].filter(Boolean);
+  const localTeams = doctorLocalTeams(ws.local.value);
+  const problems = [...legacyLayoutProblems(agentsRoot), readableInstanceHomes(agentsRoot), ...localTeams.problems].filter(Boolean);
   return {
     schemaVersion: 1, workspaceApi: 2, context: ctx,
     workspace: { file: ws.local.path, ref: ws.local.workspace },
     workspaceError: ws.localError, lockFile: ws.lockFile, packages: ws.packages, lockError: ws.lockError,
-    information: [...(operationalKnowledgeNote(composition, soulName) ? [operationalKnowledgeNote(composition, soulName)] : []), ...migration.information],
+    information: [...(operationalKnowledgeNote(composition, soulName) ? [operationalKnowledgeNote(composition, soulName)] : []), ...localTeams.information],
     composedInstructions: composition?.text, instructionBlocks: composition?.blocks,
     ...(problems.length ? { problems } : {}),
   };
@@ -638,10 +641,10 @@ async function doctor(dir) {
   const composition = await doctorComposition(ctx, soulName, ws, (code, msg) => die(`${msg} [${code}]`));
   printDoctorWorkspace(ws);
   const agentsRoot = join(dirname(ws.local.path), "agents");
-  const migration = doctorTeamMigration(ws.local.value);
+  const localTeams = doctorLocalTeams(ws.local.value);
   for (const p of [...legacyLayoutProblems(agentsRoot), readableInstanceHomes(agentsRoot)].filter(Boolean)) console.log(`\n! ${p.code}: ${p.message}`);
-  for (const p of migration.problems) console.log(`\n! ${p.code}: ${p.message} — ${p.fix}`);
-  for (const line of migration.information) console.log(`\nINFO: ${line}`);
+  for (const p of localTeams.problems) console.log(`\n! ${p.code} (${p.condition}): ${p.message}`);
+  for (const line of localTeams.information) console.log(`\nINFO: ${line}`);
   if (soulName) {
     const information = operationalKnowledgeNote(composition, soulName);
     if (information) console.log(`\nINFO: ${information}`);
@@ -1083,11 +1086,8 @@ function maxAgeRefusal(command, head) {
     case "spawn": return head.includes("--preview") ? null : refuse("spawn");
     case "workspace": return word(1) === "status" ? null : refuse(["workspace", word(1)].filter(Boolean).join(" "));
     case "teams": return word(1) === undefined ? null : refuse(`teams ${word(1)}`);
-    case "soul": {
-      if (word(1) !== "teams") return refuse(["soul", word(1)].filter(Boolean).join(" "));
-      const edit = ["--add", "--remove", "--default", "--clear-default"].find((f) => head.includes(f));
-      return edit ? refuse(`soul teams ${edit}`) : null;
-    }
+    // `soul teams` only reads (its edit flags were removed in 0.38.0, and refuse as such).
+    case "soul": return word(1) === "teams" ? null : refuse(["soul", word(1)].filter(Boolean).join(" "));
     default: {
       const sub = ["package", "schedule", "session", "trigger", "automations", "launch-config", "server", "instance", "operation", "pane"].includes(command) ? word(1) : undefined;
       return refuse([command, sub].filter(Boolean).join(" "));
@@ -1175,8 +1175,8 @@ function soulLaunchFacts(entry, local, { launchConfigs, contextDir }) {
 /** Rows of every soul and capability of confirmed members (+ external souls) + locked package
  *  capabilities. Souls have no private mode (0.26.0); a private member capability is listed with
  *  `private: true` — repo-owned: usable only by its own repo's souls (E_CAPABILITY_PRIVATE).
- *  Each soul row carries its teams HERE (team model v2: `teams`, `defaultTeam`), from the committed
- *  shared teams and `local` (oats-local.yaml); both null when its teams do not resolve (E_TEAM_*). */
+ *  Each soul row carries its teams HERE (team model 3: `teams`, `defaultTeam`), from the committed
+ *  workspace and the local teams it allows; both null when its teams do not resolve (isTeamRefusal). */
 function workspaceItems(discovery, lock, local, deploymentDir) {
   const souls = [];
   let launchConfigs = {};
@@ -1185,8 +1185,8 @@ function workspaceItems(discovery, lock, local, deploymentDir) {
   const capabilities = [];
   const model = teamModel(discovery.standalone === true ? null : discovery.workspace, local, { workspaceKey: discovery.key ?? null });
   const teamsHere = (entry) => {
-    try { const t = soulTeams(model, soulKeyOf(entry)); return { teams: reportRows(t.teams), defaultTeam: t.defaultTeam }; }
-    catch (e) { if (String(e?.code).startsWith("E_TEAM_")) return { teams: null, defaultTeam: null }; throw e; }
+    try { const t = soulTeams(model, teamKeyOf(entry)); return { teams: reportRows(t.teams), defaultTeam: t.defaultTeam }; }
+    catch (e) { if (isTeamRefusal(e)) return { teams: null, defaultTeam: null }; throw e; }
   };
   for (const m of discovery.members) {
     if (!m.confirmed && !(discovery.standalone === true && m.key === discovery.key)) continue;
@@ -1589,22 +1589,23 @@ async function workspaceStatusFacts(result, discovery, lock, ctx) {
   }
 }
 
-/** The deployment's team facts for the team verbs: oats-local.yaml and the committed shared teams
- *  (the workspace host read now; none in a standalone view). */
+/** The deployment's team facts for the team verbs: oats-local.yaml, the committed workspace file and the
+ *  souls it offers (the workspace discovered now; none in a standalone view). */
 async function teamsContext(bail) {
   const ctx = workspaceContext(bail);
-  let workspace = null, workspaceKey = null;
-  if (!(typeof ctx.local.standalone === "string" && ctx.local.standalone)) {
-    try { const { observeWorkspace } = await import("../lib/workspace.mjs"); const obs = await observeWorkspace(ctx.local.workspace, { remoteOptions: ctx.remoteOptions }); workspace = obs.workspace; workspaceKey = obs.key; }
-    catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_")) return bail(e.code, e.message, e.details ?? e.provenance); throw e; }
-  }
-  return { deployment: ctx.deploymentDir, localPath: ctx.localPath, local: ctx.local, workspace, workspaceKey, remoteOptions: ctx.remoteOptions };
+  let discovery;
+  try {
+    const { discoverOrStandalone } = await import("../lib/instance-resolution.mjs");
+    discovery = await discoverOrStandalone(ctx.local, { lock: readLockIfPresent(ctx.deploymentDir), deployment: ctx.deploymentDir, remoteOptions: ctx.remoteOptions });
+  } catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_")) return bail(e.code, e.message, e.details ?? e.provenance); throw e; }
+  const standalone = discovery.standalone === true;
+  return { deployment: ctx.deploymentDir, localPath: ctx.localPath, local: ctx.local, workspace: standalone ? null : discovery.workspace, workspaceKey: standalone ? null : discovery.key ?? null,
+    soulKeys: discoveredTeamKeys(discovery), remoteOptions: ctx.remoteOptions };
 }
-const labelsFlag = (name) => { const v = valueFlag(name); return v === undefined ? [] : String(v).split(",").map((l) => l.trim()).filter(Boolean); };
 const positional = (i) => (args[i] !== undefined && !args[i].startsWith("--") ? args[i] : undefined);
 
 /** `oats teams [--json] | add <label> --team <id> [--description <d>] | remove <label> | default <label>` —
- *  this deployment's teams (team model v2). Config only: never a provider call. */
+ *  this deployment's teams (team model 3). Config only: never a provider call. */
 async function teamsCmd() {
   const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
   const usage = "usage: oats teams [--json] | oats teams add <label> --team <id> [--description <d>] | oats teams remove <label> | oats teams default <label>  [--dir <deployment>] [--json]";
@@ -1623,25 +1624,29 @@ async function teamsCmd() {
   const doc = V.teamsDocument(result ? { ...ctx, local: result.local } : ctx);
   if (JSON_MODE) { jsonOk(result ? { ...doc, changed: result.changed } : withObservation(doc)); return; }
   if (result) console.log(result.changed ? `${sub === "add" ? `Declared team ${label}` : sub === "remove" ? `Removed team ${label}` : `The default team is now ${label}`} in ${shortPath(ctx.localPath)}` : "Nothing to change");
-  console.log(`default   ${doc.defaultTeam ?? "(none)"}`);
+  console.log(`default   ${doc.defaultTeam ? `${doc.defaultTeam.label} (${doc.defaultTeam.from})` : "(none)"}`);
+  console.log(`local     ${doc.localTeams === null ? "allowed (standalone)" : doc.localTeams ? "allowed (localTeams: true)" : "not allowed"}`);
   if (!doc.teams.length) console.log("teams     (none: `oats aweb setup` creates them, or `oats teams add <label> --team <id>`)");
   else printTable(["team", "id", "from", ""], doc.teams.map((t) => [t.label, t.team ?? "(no id yet)", t.from, t.default ? "default" : ""]));
-  const souls = Object.entries(doc.souls.teams).map(([k, l]) => `${k}: ${l.join(",")}`);
+  const souls = Object.entries(doc.souls).map(([k, e]) => `${k}: ${[e.default ? `default ${e.default}` : null, e.teams === "any" ? "any" : Array.isArray(e.teams) ? `[${e.teams.join(",")}]` : null].filter(Boolean).join(" ") || "default only"}`);
   if (souls.length) console.log(`souls     ${souls.join(" · ")}`);
-  const defaults = Object.entries(doc.souls.default).map(([k, l]) => `${k}: ${l}`);
-  if (defaults.length) console.log(`defaults  ${defaults.join(" · ")}`);
   for (const p of doc.problems) console.log(`${p.severity === "failure" ? "problem" : "warning"}   ${p.code}  ${p.message} — ${p.fix}`);
 }
 
-/** `oats soul teams <soul>|'*' [--add a,b] [--remove a,b] [--default <label> | --clear-default] [--json]` —
- *  which teams a soul belongs to here, and why (team model v2). Config only. */
+/** The `oats soul teams` edit flags team model 3 removed (0.38.0): a soul's teams are the workspace's `souls:`. */
+const SOUL_TEAMS_REMOVED_FLAGS = ["--add", "--remove", "--default", "--clear-default"];
+const SOUL_TEAMS_REPLACEMENT = "souls: in oats-workspace.yaml (a PR to the workspace file)";
+
+/** `oats soul teams <soul>|'*' [--json]` — which teams a soul may join here, its default, and why (team
+ *  model 3: the workspace's `souls:`, and the local teams it allows). Config only, read only. */
 async function soulCmd() {
   const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
-  const usage = "usage: oats soul teams <soul>|'*' [--add <label>[,…]] [--remove <label>[,…]] [--default <label> | --clear-default]  [--dir <deployment>] [--json]";
+  const usage = "usage: oats soul teams <soul>|'*'  [--dir <deployment>] [--max-age <s>] [--json]";
+  const removed = SOUL_TEAMS_REMOVED_FLAGS.find((f) => args.some((a) => a === f || a.startsWith(`${f}=`)));
+  if (removed) bail("E_BAD_ARGS", `oats soul teams ${removed} was removed in 0.38.0 (team model 3): which teams a soul may join, and its default, are ${SOUL_TEAMS_REPLACEMENT}`, { flag: removed, replacement: SOUL_TEAMS_REPLACEMENT });
   if (positional(1) !== "teams") bail("E_USAGE", usage);
   const name = positional(2);
-  if (name === undefined) bail("E_BAD_ARGS", `oats soul teams needs a soul (or '*' for every soul) — ${usage}`);
-  const edit = { add: labelsFlag("add"), remove: labelsFlag("remove"), setDefault: valueFlag("default") ?? null, clearDefault: args.includes("--clear-default") };
+  if (name === undefined) bail("E_BAD_ARGS", `oats soul teams needs a soul (or '*') — ${usage}`);
   const ctx = workspaceContext(bail);
   let teamsCtx, soul = "*", key = "*";
   if (name === "*") teamsCtx = await teamsContext(bail);
@@ -1655,19 +1660,16 @@ async function soulCmd() {
       discovery = await discoverOrStandalone(ctx.local, { lock, deployment: ctx.deploymentDir, remoteOptions: ctx.remoteOptions });
       entry = findSoulEntry(discovery, name);
     } catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_")) return bail(e.code, e.message, e.details ?? e.provenance); throw e; }
-    soul = entry.name; key = soulKeyOf(entry);
+    soul = entry.name; key = teamKeyOf(entry);
     teamsCtx = { deployment: ctx.deploymentDir, localPath: ctx.localPath, local: ctx.local, workspace: discovery.standalone === true ? null : discovery.workspace, workspaceKey: discovery.key ?? null };
   }
   const V = await import("../lib/teams-verbs.mjs");
-  const mutating = edit.add.length || edit.remove.length || edit.setDefault !== null || edit.clearDefault;
-  let result = null, doc;
-  try {
-    if (mutating) result = V.soulTeamsEdit(teamsCtx, key, edit);
-    doc = V.soulTeamsDocument(result ? { ...teamsCtx, local: result.local } : teamsCtx, { soul, key });
-  } catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_")) return bail(e.code, e.message, e.details); throw e; }
-  if (JSON_MODE) { jsonOk(result ? { ...doc, changed: result.changed } : withObservation(doc)); return; }
-  if (result) console.log(result.changed ? `Updated the teams of ${key === "*" ? "every soul" : key} in ${shortPath(teamsCtx.localPath)}` : "Nothing to change");
-  console.log(`${key === "*" ? "every soul" : key} on this computer: default ${doc.defaultTeam ? `${doc.defaultTeam.label} (${doc.defaultTeam.from})` : "(none)"}`);
+  let doc;
+  try { doc = V.soulTeamsDocument(teamsCtx, { soul, key }); }
+  catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_")) return bail(e.code, e.message, e.details); throw e; }
+  if (JSON_MODE) { jsonOk(withObservation(doc)); return; }
+  console.log(`${key === "*" ? "unlisted souls (\"*\")" : key} here: default ${doc.defaultTeam ? `${doc.defaultTeam.label} (${doc.defaultTeam.from})` : "(none)"}`);
+  console.log(`souls: ${doc.match === null ? "no entry matches" : `teams from ${JSON.stringify(doc.match)}`}${doc.defaultMatch !== null ? `, default from ${JSON.stringify(doc.defaultMatch)}` : ""}`);
   if (doc.teams.length) printTable(["team", "id", "from", "why"], doc.teams.map((t) => [t.default ? `${t.label} (default)` : t.label, t.team ?? "(no id yet)", t.from, t.via.join(",")]));
 }
 
@@ -1904,8 +1906,8 @@ async function statusDrift(data) {
  *  machine's parsed cache knows: `ref` itself when the cache holds its workspace file, or the host its
  *  cached oats-membership.yaml names when `ref` is a member ("workspace"). A member whose host is not
  *  known keys as itself ("member"); a ref nothing is known of is taken as the host, as the schema
- *  defines `workspace:` ("workspace"). The team model resolves as teamModel resolves it (the default
- *  label is local; a committed team wins a collision) over the shared teams of, in order, the workspace
+ *  defines `workspace:` ("workspace"). The team model resolves as teamModel resolves it (the default is
+ *  the local one the workspace allows, else the workspace's; a committed team wins a collision) over the shared teams of, in order, the workspace
  *  file this run observed (`teamsFrom: "observed"`), the cached file ("cache": no git process), or none
  *  ("local"). `standalone` is the CONFIGURED standalone view only (oats-local.yaml `standalone:`): it
  *  reads no workspace file, so its local teams are the whole team model. A run that fell back to the
@@ -1928,10 +1930,12 @@ function workspaceIdentity(local, discovery) {
     else if (cached?.file) [shared, teamsFrom] = [cached.file, "cache"];
   }
   const model = teamModel(shared, local);
+  // A soul with no souls: default of its own lives here (team model 3: the local default the workspace allows, else the workspace's).
+  const deploymentDefault = model.localDefault ?? model.workspaceDefault;
   const labels = [...model.labels.keys()].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
   return {
     key, ref, keyFrom, standalone,
-    defaultTeam: model.defaultTeam === null ? null : { label: model.defaultTeam, team: model.labels.get(model.defaultTeam)?.team ?? null },
+    defaultTeam: deploymentDefault === null ? null : { label: deploymentDefault, team: model.labels.get(deploymentDefault)?.team ?? null },
     teams: Object.fromEntries(labels.map((l) => [l, model.labels.get(l).team])),
     teamsFrom,
   };
@@ -2010,8 +2014,8 @@ async function status() {
   const verbose = args.includes("--verbose");
   const problems = legacyLayoutProblems(root);
   if (args.includes("--json")) {
-    // The soul key (feature launch-preference): what souls.teams / souls.default / souls.launch and
-    // `oats soul teams <key>` use — from the instances' records, so it needs no remote.
+    // The soul key (feature launch-preference): what souls.launch and `oats soul teams <key>` use —
+    // from the instances' records, so it needs no remote.
     for (const a of data) a.key = agentSoulKey(a);
     if (ws) for (const a of data) {
       const stamp = ws.souls.get(a.name);
@@ -3002,7 +3006,9 @@ async function capabilityCommand() {
     if (!trust.trusted) bail("E_CAPABILITY_BLOCKED", `${m.capability} executable command is blocked: ${trust.reason}`);
     if (homeMeta && m.capability === homeMeta.messaging) {
       const { liveTeams } = await import("../lib/instance-resolution.mjs");
-      const live = await liveTeams(instanceHome, homeMeta.meta, { remoteOptions: remoteOptionsFromEnv() });
+      let live;
+      try { live = await liveTeams(instanceHome, homeMeta.meta, { remoteOptions: remoteOptionsFromEnv() }); }
+      catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_")) return bail(e.code, e.message, e.details); throw e; }
       teamCtx = homeTeamCtx(live);
     }
     return runManifestCommand(m, { settings: capSettings[m.capability] || {}, origins: capOrigins[m.capability] }, teamCtx, () => m._dir, () => ({ dir: soulDir, cleanup: () => {} }));
@@ -3136,7 +3142,7 @@ function versionCmd() {
     // Phase B: `instance-modules` and `spawn-provider-payload` are advertised only once spawn
     // runs on resolve/materialize (contract §6); a feature the binary does not implement is
     // never listed.
-    console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends: ["tmux"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations", "readiness", "instance-events", "instance-git", "lifecycle-plans"], features: ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-2", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity"], automationsApi: A.AUTOMATIONS_API, workspaceApi: 2, instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 2, lifecycleApi: 1, readinessApi: 2, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 3, scheduleApi: SCHEDULE_API, operationsApi: 2, capabilityShowApi: 1 }));
+    console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends: ["tmux"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations", "readiness", "instance-events", "instance-git", "lifecycle-plans"], features: ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity"], automationsApi: A.AUTOMATIONS_API, workspaceApi: 2, instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 2, lifecycleApi: 1, readinessApi: 2, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 3, scheduleApi: SCHEDULE_API, operationsApi: 2, capabilityShowApi: 1 }));
     return;
   }
   console.log(`@awebai/oats ${OATS_VERSION} (desktop API v1)`);
@@ -3810,10 +3816,10 @@ Usage:
                                             teams on this deployment
   oats teams [--json] | add <label> --team <id> [--description <d>] | remove <label>
       | default <label>  [--dir <d>]        this deployment's teams (shared + local), the
-      [--max-age <s>] (the read form only)  default; add/remove/default edit oats-local.yaml
-  oats soul teams <soul>|'*' [--add a,b] [--remove a,b] [--default <l> | --clear-default]
-      [--dir <d>] [--json]                  which teams a soul (or every soul) belongs to here
-      [--max-age <s>] (without an edit)
+      [--max-age <s>] (the read form only)  default, the workspace's souls:; add/remove/default
+                                            edit oats-local.yaml (only with localTeams: true)
+  oats soul teams <soul>|'*' [--dir <d>]    which teams a soul may join here, its default, and
+      [--max-age <s>] [--json]              why (the workspace's souls: and local teams)
   oats instance git <instance> [--home <abs>] [--dir <d>] [--json]
                                              read-only Git observation of the instance's work
                                              tree: branch, status (renames kept), ahead/behind

package/docs/capabilities.md

@@ -193,23 +193,27 @@ per-deployment activation or exclusion maps.
 
 ### Teams in the provider environment
 
-A soul's teams here (the committed shared teams, and the deployment's `oats-local.yaml` `teams`, `defaultTeam`, `souls.teams`,
-`souls.default` — see [workspaces.md](workspaces.md#teams)) travel **beside** a
+A soul's teams here (the workspace's shared teams, `defaultTeam` and `souls:`, and
+the deployment's `oats-local.yaml` `teams` and `defaultTeam` where the workspace
+allows them — see [workspaces.md](workspaces.md#teams)) travel **beside** a
 provider's settings, never inside them, in the environment of every hook, home
 command and provider check:
 
 - `OATS_DEFAULT_TEAM` — the soul's default label; `OATS_DEFAULT_TEAM_ID` — its
-  provider id; `OATS_DEFAULT_TEAM_FROM` — `deployment` (`defaultTeam`) or `soul`
-  (`souls.default`).
+  provider id; `OATS_DEFAULT_TEAM_FROM` — `soul` (the soul's `souls:` default in
+  the workspace file), `deployment` (the local `defaultTeam`) or `workspace` (the
+  workspace's `defaultTeam`).
 - No default configured: none of the three is set. An **unmapped** default (a
   shared team declared without an id): `OATS_DEFAULT_TEAM` and
   `OATS_DEFAULT_TEAM_FROM` are set and `OATS_DEFAULT_TEAM_ID` is not. What a
   provider does then is its own contract; a messaging provider typically
   refuses the spawn, naming the unmapped label, or saying no team is
   configured.
-- `OATS_TEAMS` — JSON `[{label, team, default, from: "shared"|"local"}]`: every
-  mapped team the soul may be in here, the default included (`default: true`),
-  default first, then by label. Eligible to join = the rows with `default: false`.
+- `OATS_TEAMS` — JSON `[{label, team, default, from: "shared"|"local", via}]`:
+  every mapped team the soul may be in here, the default included
+  (`default: true`), default first, then by label; `via` says why
+  (`default`, `workspace`, `local`). Eligible to join = the rows with
+  `default: false`, and no other team: a provider refuses a join outside them.
   Unset when a home's teams are unknown (none recorded, and unreadable now).
 - `OATS_TEAMS_SOURCE` — `live` (the workspace and `oats-local.yaml` read now, or
   a fresh resolution) or `recorded` (the spawn-time record). **A provider leaves

package/docs/configuration.md

@@ -21,15 +21,10 @@ settings:                                    # host-owned values per capability
   oats.okf:
     bindings-file: /Users/ana/.oats/okf-bindings.json
 
-teams:                                       # LOCAL teams: only this deployment uses them
+teams:                                       # LOCAL teams (only where the workspace says localTeams: true)
   ana-research: { team: "ana-research:acme.aweb.ai", description: Ana's research }
-defaultTeam: ana-research                    # the team every instance lives in
+defaultTeam: ana-research                    # this deployment's default team (same condition)
 souls:
-  teams:
-    "*": [ana-research]                      # every soul is in these teams here
-    data-analyst: [platform]                 # and this one also joins a shared team
-  default:
-    data-analyst: platform                   # per-soul override of defaultTeam
   disabled: [legacy-bot]                     # souls not run on this machine
 
 host:
@@ -66,10 +61,8 @@ refused (`E_WORKSPACE_SCHEMA`).
 | `standalone` | A repo ref to realize on its own: its souls and `from: here` capabilities plus `oats.core`, with no workspace lookup. For a repository whose workspace this machine cannot read ([workspaces.md](workspaces.md#the-standalone-case)). |
 | `clones` | `<repo key>: <absolute path>` for a member clone that is not at `<deployment>/<member name>/`. Only a soul whose work target needs a clone (`work: worktree \| checkout`) uses it. Lookup order: `spawn --repo`, then this map, then `<deployment>/<member name>` (a member named `agents` → `<deployment>/agents-repo`). None → `E_CLONE_MISSING`; a directory whose `origin` is another repository → `E_CLONE_MISMATCH`. |
 | `settings.<cap>.<key>` | Host-owned values a capability's manifest asks for: absolute paths, state roots, delivery modes. The workspace file refuses absolute paths; they go here. Merged into the capability's provider payload after the soul's own and before any `--provider` flag ([three homes](workspaces.md#provider-payloads-have-three-homes)). |
-| `teams.<label>` | A **local** team: `{ team: <provider team id>, description? }`. Shared teams are committed in `oats-workspace.yaml`; a label in both is refused. Written by `oats teams add <label> --team <id>` and `oats teams remove <label>`. |
-| `defaultTeam` | The team every instance of this deployment lives in: a label of a local or shared team. The first `oats teams add` sets it; `oats teams default <label>` changes it. |
-| `souls.teams` | Which teams each soul joins here: `"*"` applies to every soul; a soul's own entry (its name, or `<package>/<soul>`) adds to it. Every soul is also in its default team. Written by `oats soul teams <soul>\|'*' --add … --remove …`. |
-| `souls.default` | A per-soul override of `defaultTeam`; it must be one of that soul's teams here (`E_TEAM_NOT_ELIGIBLE`). Written by `oats soul teams <soul> --default <label>`. |
+| `teams.<label>` | A **local** team: `{ team: <provider team id>, description? }`, a team only this deployment uses; every soul may join it. Allowed only where `oats-workspace.yaml` says `localTeams: true` (or in the standalone view); otherwise refused (`E_WORKSPACE_SCHEMA`, reason `local-teams-closed`). Shared teams are committed in `oats-workspace.yaml`; a label in both is `team-label-collision` (the shared one wins). Written by `oats teams add <label> --team <id>` and `oats teams remove <label>`. |
+| `defaultTeam` | This deployment's default team: a label of a local or shared team, under the same condition as `teams`. A soul's own default in the workspace's `souls:` wins over it; it wins over the workspace's `defaultTeam`. The first `oats teams add` sets it; `oats teams default <label>` changes it. |
 | `souls.disabled` | Souls not run on this machine; a spawn is refused with `E_SOUL_DISABLED`. A bare name disables every soul of that name; `<package>/<soul>` or `<member>/<soul>` disables one. |
 | `session.tmuxSession` | The tmux session new tmux instances open their windows in (0.31). Absent: `OATS_TMUX_SESSION`, else `PI_AGENTS_TMUX_SESSION` (the pre-0.31 variable), else `oats-agents`. `session: { tmuxSession: pi-agents }` keeps the pre-0.31 layout. `oats inspect --json` reports it as `session`. |
 | `host.name` | This machine's name. A workspace trigger or schedule runs only on the host named by its `runsOn` ([schedules.md](schedules.md)). |
@@ -78,14 +71,11 @@ refused (`E_WORKSPACE_SCHEMA`).
 | `launch-configs.<name>` | A named way to start a harness on this host, chosen at spawn or session start, never by the soul. `default: true` makes it this host's baseline for its harness (0.32). See [Launch configurations](#launch-configurations). |
 | `souls.launch` | This machine's launch preference per soul (0.30): `"*"` for every soul, a soul's own entry (its name, or `<package>/<soul>`) over it. A value is a `launch-configs` name or an inline `{ harness, model? }`. It overrides the soul's own `launch:`; explicit spawn flags win over both. See [Launch preferences](#launch-preferences). |
 
-How teams are resolved, and what a messaging provider does with them, is in
-[workspaces.md](workspaces.md#teams).
-
-OATS 0.38.0 (team model 3) removes `souls.teams` and `souls.default` (they move
-to `souls:` in `oats-workspace.yaml`) and allows `teams` and `defaultTeam` here
-only when the workspace file says `localTeams: true`. 0.36.x and 0.37.x still apply all
-four keys and warn about them (`team-model-3-migration`): see
-[Preparing for team model 3](workspaces.md#preparing-for-team-model-3-036x).
+Which teams a soul may join, and its default, are committed in the workspace's
+`souls:`, never here: `souls.teams` and `souls.default` were removed in 0.38.0
+(`E_WORKSPACE_SCHEMA`, reason `removed-key`; the refusal prints the `souls:` to
+commit instead). How teams are resolved, and what a messaging provider does
+with them, is in [workspaces.md](workspaces.md#teams).
 
 ## Launch configurations
 
@@ -332,7 +322,7 @@ is safe to delete.
 oats workspace status          # members, locked packages, external souls
 oats sync                      # confirm, resolve, lock, report the diff
 oats teams                     # shared and local teams, and the default
-oats soul teams <soul>         # the teams one soul joins here
+oats soul teams <soul>         # the teams one soul may join here, and why
 oats spawn <soul> --preview    # the exact modules, teams and provider payloads
 oats doctor                    # this deployment's files and the lock
 ```

package/docs/design/2026-09-27-team-model-v2.md

@@ -1,6 +1,6 @@
 # Team model v2: shared and local teams, the default team, and membership per deployment
 
-**Status:** decided and implemented (kernel 0.30.0, feature `team-model-2`). This record decides where teams, the default team and team membership live, how the kernel resolves them, and what the kernel hands a messaging provider. The reference pages ([workspaces.md](../workspaces.md#teams), [capabilities.md](../capabilities.md#teams-in-the-provider-environment), [desktop-cli-api.md](../desktop-cli-api.md#team-model-v2-feature-team-model-2-oats-0300-replaces-feature-teams)) win on operator-visible behaviour.
+**Status:** superseded in part by [team model 3](2026-10-02-team-model-3.md) (kernel 0.38.0): which teams a soul may join and its default team are committed in the workspace's `souls:` and `defaultTeam`, and local teams need `localTeams: true`; `souls.teams`, `souls.default` and the `oats soul teams` edits below are removed. The rest stands. Decided and implemented (kernel 0.30.0, feature `team-model-2`). This record decides where teams, the default team and team membership live, how the kernel resolves them, and what the kernel hands a messaging provider. The reference pages ([workspaces.md](../workspaces.md#teams), [capabilities.md](../capabilities.md#teams-in-the-provider-environment), [desktop-cli-api.md](../desktop-cli-api.md#team-model-v2-feature-team-model-2-oats-0300-replaces-feature-teams)) win on operator-visible behaviour.
 
 ## Why
 

package/docs/design/2026-10-02-team-model-3.md

@@ -0,0 +1,146 @@
+# Team model 3: the teams a soul may join, and its default, are committed in the workspace
+
+**Status:** decided and implemented (kernel 0.38.0, feature `team-model-3`; prepared in 0.36.1).
+Specs: awebai/oats#484 and #485, agreed by both maintainers on 2026-10-02. This record supersedes the
+membership and default-team parts of [team model v2](2026-09-27-team-model-v2.md); v2's shared teams,
+unmapped ids, live teams and provider environment stand. The reference pages
+([workspaces.md](../workspaces.md#teams), [capabilities.md](../capabilities.md#teams-in-the-provider-environment),
+[desktop-cli-api.md](../desktop-cli-api.md#team-model-3-feature-team-model-3-oats-0370-replaces-feature-team-model-2))
+win on operator-visible behaviour.
+
+## Why
+
+**The local bridge.** An instance that sits in two teams is a bridge between them: one process reads
+both inboxes, holds both contexts in one session, and can relay anything from one to the other. Under
+team model v2, one person's `oats-local.yaml` could put an organisation's instance into a team the
+organisation never sees: a local extra team in `souls.teams`, or a local default team while its souls
+joined the organisation's shared teams. Either way it never showed in the organisation's git, and it
+differed per person and per machine. The organisation owns its teams' trust boundary, so the teams its
+instances can be in are its decision, committed in its workspace, and closed by default.
+
+**Scale.** With many souls and teams, per-deployment lists were repeated by every person on every
+machine.
+
+**Principle**, consistent with v2's "shared facts committed, personal choices local": everything
+workspace-specific lives in the workspace file; souls stay team-free in their repositories, open source
+included; an organisation says how souls behave in its teams in its own `oats-workspace.yaml`, and
+someone running the souls standalone sees none of it.
+
+## What it protects against, and what it does not
+
+The workspace's eligibility rules (`souls:`, `localTeams` closed by default) **prevent accidental joins**
+in a cooperative installation, and make the organisation's intended team set visible and reviewable in
+its git. That is all they claim.
+
+They are not anti-bridging enforcement, and neither is the messaging layer. Distinct keys do not prove
+distinct processes: an operator controlling two identities can read under one and relay under the
+other, or copy content outside the messaging layer. aweb admission controls who holds credentials for
+a team (the team controller key signs memberships; hosted invites are mediated by the service), not
+what a process does with what it reads. A deployment's authority comes from the credentials it holds,
+not from its path or its name. Today's team certificates carry no soul, workspace or home-team claim,
+and any such metadata would be self-asserted, so it would not be prevention. Enforcement on the
+messaging side (admission per root, claims in certificates, a namespace policy, bridge visibility for a
+team's owner) is a separate question for the aweb protocol owners.
+
+## The model
+
+### `oats-workspace.yaml`
+
+```yaml
+teams:                                   # shared teams, as in v2
+  engineering: { team: "engineering:acme.aweb.ai" }
+  security:    { team: "security:acme.aweb.ai" }
+  docs:        { team: "docs:acme.aweb.ai" }
+defaultTeam: engineering                 # the workspace's fallback default team (a shared label)
+localTeams: false                        # may deployments declare their own teams? (absent: false)
+souls:                                   # per pattern: the default team and the other teams a soul may join
+  "*": { teams: [] }
+  security-souls/*: { default: security, teams: [engineering] }
+  security-souls/incident-responder: { default: security, teams: [engineering, docs] }
+  oats.engineering/*: { teams: any }
+```
+
+- **Keys are patterns:** `<member>/<soul>` or `<package>/<soul>`, `<member>/*` or `<package>/*`, and
+  `"*"`, with the names `souls.disabled` already uses. A soul's key is its qualified name. Bare names are
+  refused: a bare name is ambiguous across members, and the qualified form is what the workspace sees.
+- **The most specific key wins outright for teams,** with no merging across levels; the default comes
+  from the most specific key that sets one. `a/*: {default: security}` and `a/x: {teams: [docs]}` give
+  `a/x` the default `security` and the teams `[docs]` only. Merging was rejected: an entry that adds to
+  a broader one hides what a soul can join behind two places, and the point of the model is that a
+  reviewer reads one entry.
+- **`any`** is every shared team of the file.
+- **A soul no key matches** (and no `"*"`) has its default only, member and package souls alike; a
+  workspace opens a package explicitly.
+- **Every label is a shared team of the same file.** An unknown label, or a default that isn't one, is
+  `E_WORKSPACE_SCHEMA` when the file is read, never at a spawn on someone else's machine. A key that is
+  neither a pattern nor a discovered soul's qualified name is the warning `team-soul-unknown` (a typo
+  guard; not an error, because the file is validated without discovery and packages come and go).
+
+### The default team, in order
+
+1. the soul's `default` from `souls:` (`from: "soul"`);
+2. else the deployment's `oats-local.yaml` `defaultTeam`, only when `localTeams: true`
+   (`from: "deployment"`);
+3. else the workspace's `defaultTeam` (`from: "workspace"`);
+4. else none (`E_TEAM_UNCONFIGURED` when a messaging layer is active).
+
+The soul's own default comes first because it is the organisation's most specific statement; a
+personal default, where allowed, comes before the workspace's fallback so a person can keep their own
+default team (awebai/oats sets `localTeams: true` for this).
+
+### The teams a soul may join
+
+Its default, plus the `teams` of its most specific matching key, plus, with `localTeams: true`, every
+local team the deployment declares (there is no per-soul local list: a deployment that is trusted with
+local teams is trusted with them for every soul). Each row says why: `via` ⊂ `default`, `workspace`,
+`local`. Unchanged from v2: an instance joins only its default at spawn; the others are offered and
+joined on request, and the messaging provider decides admission from the eligible rows it receives in
+`OATS_TEAMS`.
+
+### `oats-local.yaml`
+
+- `souls.teams` and `souls.default` are removed keys. The refusal names each key found and prints the
+  `souls:` that gives the same result (a v2 soul's teams were its default ∪ `"*"` ∪ its own list, so each
+  named soul's entry lists `"*"`'s teams too; a bare soul name is written `<member>/<soul>` for the
+  operator to qualify), so a deployment's migration is a copy, a qualification and a PR.
+- `teams` and `defaultTeam` are allowed only when the workspace says `localTeams: true`. Otherwise every
+  spawn, preview and inspect refuses with `E_WORKSPACE_SCHEMA` (reason `local-teams-closed`), and `oats
+  teams`, readiness and doctor report it as a failure. The message names both fixes: allow local teams,
+  or commit them in the workspace and remove them locally. The rule can only be checked where the
+  workspace file has been read, so it is not part of `oats-local.yaml`'s own validation.
+- The standalone view (explicit, or a fallback when the workspace can't be read) has no workspace rules:
+  it is an individual running souls outside any organisation, so local teams apply.
+- Verbs: `oats teams add` and `oats teams default` refuse where local teams are closed; `oats teams
+  remove` runs there, since removing local teams is the last step of committing them in the workspace.
+  `oats soul teams` is read only; its edit flags were removed (a soul's teams are a PR to the workspace).
+
+### `soul.yaml` and `oats-membership.yaml`
+
+Unchanged: they say nothing about teams, so a soul in a public repository carries no organisation's
+labels. Per-soul lists in `oats-membership.yaml` and teams in `soul.yaml` were rejected for the same
+reason v2 rejected them: labels belong to a workspace, and there should be one central place.
+
+## Reporting (contract)
+
+- `defaultTeam.from` (spawn preview, `inspect`, `oats souls`, readiness, `OATS_DEFAULT_TEAM_FROM`):
+  `soul`, `deployment` or `workspace`. `soul` changed meaning: it was the local `souls.default`.
+- Every `TeamRow` gains `via`.
+- `oats teams --json` is `teamsApi: 2`: `localTeams`, a `DefaultTeam` for the deployment, and the
+  workspace's `souls:` in place of the local `souls` block. `oats soul teams --json` is
+  `soulTeamsApi: 2`: `match` and `defaultMatch` (the `souls:` keys that applied) in place of `local` and
+  `all`. Feature `team-model-3` replaces `team-model-2`.
+- Readiness: local-teams-closed (failure) and `team-soul-unknown` (warning) join the team items;
+  `E_TEAM_NOT_ELIGIBLE` is no longer a kernel item (a soul's default is always one of its teams); it
+  remains the provider's join refusal.
+
+## 0.36.x → 0.38.0
+
+0.36.1 accepted and validated `defaultTeam`, `localTeams` and `souls:` without applying them, and warned
+(`team-model-3-migration`) about what 0.38.0 refuses, so every workspace could commit its side first, as
+0.29.4 did for 0.30. 0.38.0 applies the keys, refuses the old shape, and retires the warning. The steps
+for each kind of deployment are in the [0.38.0 release notes](../release-notes/v0.38.0.md).
+
+## Out of scope
+
+Enforcement on the aweb side (above); nested teams; the Desktop's team-editing UI (its own spec:
+anything that writes `souls.teams` or `souls.default` goes).

package/docs/design/README.md

@@ -17,7 +17,11 @@ successor, with a link to its full text.
 - [OKF knowledge operations](2026-09-26-okf-knowledge-operations.md): package
   souls, triggers and automations for harvest and maintenance.
 - [Team model v2](2026-09-27-team-model-v2.md): shared teams in the workspace,
-  local teams, the default team and membership in each deployment.
+  local teams, live teams and the provider environment (its membership and
+  default-team parts are superseded by team model 3).
+- [Team model 3](2026-10-02-team-model-3.md): the teams a soul may join, and
+  its default, are committed in the workspace; local teams only where the
+  workspace allows them.
 
 The Desktop's design brief for designers is in
 [packages/desktop/docs](../../packages/desktop/docs/design-brief.md).