@awebai/oats 0.36.1 → 0.38.0

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
@@ -341,7 +345,9 @@ Hooks receive:
 A spawn hook also gets `OATS_TASK`, `OATS_REPO`, `OATS_BRANCH`, `OATS_WORK`,
 `OATS_HARNESS`, `OATS_KIND` and, for a spawn a trigger started,
 `OATS_TRIGGER_EVENT_FILE`. A launch hook also gets `OATS_HARNESS` and
-`OATS_PREVIOUS_HARNESS`.
+`OATS_PREVIOUS_HARNESS`, and `OATS_LAUNCH_PREVIEW=1` when it runs for a
+preview (only a preview-aware hook does, below); on a real run
+`OATS_LAUNCH_PREVIEW` is not set.
 
 `OATS_SETTINGS_ORIGINS` says where each leaf of
 `OATS_SETTINGS` came from: a JSON object from a JSON pointer to `{ kind, at }`,
@@ -350,7 +356,8 @@ A spawn hook also gets `OATS_TASK`, `OATS_REPO`, `OATS_BRANCH`, `OATS_WORK`,
 `{"/harvest":{"kind":"soul","at":"soul.yaml#/knowledge"}}`. A provider tells a
 soul-set value from a host-set one there, and never reads `soul.yaml` for it;
 a home with none recorded gives `{}`. A final JSON line may return `meta`,
-`brief`, `warning`, or harness-specific `launch` arguments. A **spawn or
+`brief`, `warning`, or harness-specific `launch` arguments; a preview-aware
+launch hook's preview answer may add `volatileEnv` (below). A **spawn or
 launch hook** may also return an `env` object for the launched process;
 returning `env` from a retire hook is an explicit contract error.
 
@@ -364,6 +371,54 @@ start (a renewed session grant, for example) leaves the CURRENT one on record. A
 launch hook that answers without `meta` keeps its previous entry; a start whose
 preparation fails changes nothing.
 
+A launch hook may do idempotent provider registration on a real start (an
+aweb home registering with the host wake broker, for example). How the
+kernel runs it depends on whether its capability declares **preview
+awareness**: `"launchPreview": true` at the top level of its manifest. The
+kernel reads the declaration from the home's own module copy, so a home keeps
+the behaviour of the module it was spawned with.
+
+**A preview-aware hook** must change nothing under `OATS_LAUNCH_PREVIEW=1`,
+and must return the same contribution (`launch` arguments and `env`) as for
+a real start. It runs twice per start:
+
+1. **As a preview, under `OATS_LAUNCH_PREVIEW=1`.** The start's preflight uses
+   this contribution: trust, environment ownership, the harness-package
+   probe and the rendered command. `oats launch-config preview` (which
+   Desktop's start dialog uses) runs only this pass.
+2. **For real, without the flag.** This pass runs only once preflight has
+   passed, including the check that the home is not already running
+   (`E_SESSION_RUNNING`), and before a restart stops the running harness.
+
+The real run's `meta` and warnings are what the start records. If its
+contribution differs from its preview contribution, the start is refused
+with `E_LAUNCH_PREPARATION` and nothing is stopped or started.
+
+Some values only a real run can know, such as a credential minted at start.
+A preview answer may list those names in `volatileEnv` (for example
+`"volatileEnv": ["AWEB_IDENTITY_HOME"]`, beside `env`). For those names:
+
+- The start takes the values from the real run, records them, and renders
+  the launch command again with them.
+- The comparison leaves those values out. Everything else must still be
+  identical.
+
+Each name must be one the same hook returned in `env`. Preflight sees only
+the preview's value, so a volatile name must not affect how the harness
+resolves its packages. The kernel refuses (`E_LAUNCH_PREPARATION`) a volatile
+`CLAUDE_CONFIG_DIR`, `CODEX_HOME` or `PI_CODING_AGENT_DIR`. It reads
+`volatileEnv` only from a preview answer and never records it.
+
+**A hook that does not declare preview awareness** runs once per start, for
+real, during preflight, before the checks that use its contribution. A
+refused start may therefore already have run it. `oats launch-config preview`
+never runs it. The preview shows that capability's recorded contribution, and
+its `capabilities` check says the hook was not run.
+
+`launchPreview` is a top-level key so that a kernel older than 0.37 ignores
+it and runs the hook once, as it always did. A key inside the hook's
+declaration would make such a kernel refuse the whole package.
+
 Hook environment values are strings, at most 8192 UTF-8 bytes, with no NUL or
 newlines. Names use the portable environment grammar and must belong to an
 unambiguous vendor namespace. Only a dotted capability ID participates: its

package/docs/capability-manifest.schema.json

@@ -61,6 +61,10 @@
       "type": "boolean",
       "description": "Workspace discovery: true makes this member capability repo-owned — listed (private: true) but usable only by souls of its own repository (E_CAPABILITY_PRIVATE elsewhere)."
     },
+    "launchPreview": {
+      "type": "boolean",
+      "description": "true declares the launch hook preview-aware: it changes nothing under OATS_LAUNCH_PREVIEW=1 and returns the same contribution (apart from its preview answer's volatileEnv values), so a start runs it as a preview during preflight and for real after it, and a launch preview runs it. Without it the hook runs once per start, for real, during preflight, and never for a launch preview. Top-level so that older kernels ignore it."
+    },
     "layer": {
       "enum": [
         "knowledge",

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.37.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 still applies all
-four keys and warns 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
 
@@ -242,7 +232,12 @@ recipe is resolved again against the home's recorded context and every check
 runs first. With `--reselect-launch`, the launch preferences decide again
 (the home's recorded soul and this deployment's `souls.launch`). A capability that contributed harness-specific arguments must
 declare a `launch` hook to follow a harness change; otherwise the start is
-refused (`E_LAUNCH_PREPARATION`). A launch hook's warnings do not stop
+refused (`E_LAUNCH_PREPARATION`). The checks use the preview run
+(`OATS_LAUNCH_PREVIEW=1`) of the launch hooks whose capabilities declare
+`launchPreview`. Those hooks run for real only after every check has passed,
+so a start refused by preflight has run none of them for real. Other launch
+hooks run once, for real, during the checks (see
+[capabilities.md](capabilities.md)). A launch hook's warnings do not stop
 the start: `session start|restart` print them (and answer them as
 `warnings` under `--json`), as spawn does, and each is kept as a
 `launch-warning` instance event (`oats instance events`).
@@ -327,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