@awebai/oats 0.29.4 → 0.30.0

package/README.md

@@ -13,8 +13,6 @@ OATS—**Open Agent Team Specification**—is a framework for building, running
 
 The [official catalog](docs/official-catalog.md) is the reviewed list of official packages; a workspace trusts a package by declaring it, and listing does not declare it for you.
 
-**oats.aweb 1.13.1** attaches resident session-grant homes to the resident custody service during minting, verifies the written `grant.yaml` custody locator, and fails closed if an installed `aw` cannot write or prove that attachment. If a grant-sent message ever arrives as unverified, report the missing custody attachment instead of retrying.
-
 For example, a kernel expert, a UX expert and a customer-support expert can share capabilities for learning and coordination, while each has specific capabilities for its own area of expertise.
 
 Through your capabilities, you remain in control of:
@@ -179,7 +177,7 @@ For example, you might want:
 - **Long-running instances to retain working understanding.** A customer-support instance carries its investigations, observations and unresolved questions across many tasks.
 - **Selected learning to become shared knowledge.** Useful findings are reviewed and made available to other instances, while task-specific context stays with the instance that needs it.
 
-Your knowledge capability determines what context an instance receives, how it builds on experience, and which learning is retained or shared. It can organise knowledge per soul, per topic or per project, centrally or alongside soul definitions, provided that it actually supports the chosen arrangement. Mutable knowledge must not be written into immutable captured source artifacts.
+Your knowledge capability determines what context an instance receives, how it builds on experience, and which learning is retained or shared. It can organise knowledge per soul, per topic or per project, centrally or alongside soul definitions, provided that it actually supports the chosen arrangement.
 
 The same principle applies to messaging and tasks: **OATS provides the contracts; you choose how your team works through them.**
 
@@ -210,7 +208,15 @@ Begin with a small team and a real piece of work:
 4. Create instances for their assignments.
 5. Verify that work, communication, learning and handoff behave as intended.
 
-Start with the [first-team guide](docs/first-team.md) and the [release notes](docs/release-notes/) for the supported scope of your chosen versions.
+On a machine with Node.js 22+, Git and tmux, and a workspace repository to point at:
+
+```bash
+npm install -g @awebai/oats
+oats onboard ~/acme --workspace git:github.com/acme/agents   # this machine's deployment
+oats spawn <soul> --task "First concrete task"
+```
+
+The [first-team guide](docs/first-team.md) walks through writing the workspace, its members and a first soul; the [release notes](docs/release-notes/) state the supported scope of each version.
 
 Further documentation:
 
@@ -220,10 +226,10 @@ Further documentation:
 - [Knowledge operations](docs/knowledge.md)
 - [Knowledge, instances and evolving expertise](docs/knowledge-theory.md)
 - [Packages](docs/packages.md)
-- [Execution targets](docs/execution-targets.md)
+- [Sessions](docs/execution-targets.md)
 - [OATS Desktop](docs/desktop.md)
 
-This README explains the framework and its direction. Advanced mechanisms such as automatic speciation and context cloning require their own implementation and verification; the architectural model is not a claim that every feature or capability combination already works. Alternative knowledge layouts require a compatible capability, not a change to an undocumented kernel switch.
+This README explains the framework and its direction. Advanced mechanisms such as automatic speciation and context cloning require their own implementation and verification; the model is not a claim that every feature or capability combination already works.
 
 ## Contributing and releases
 

package/bin/oats.mjs

@@ -27,12 +27,14 @@ import {
   LAYERS, OATS_VERSION, manifestOperations, upgradeHomeMeta,
   capabilityManifests, capabilityTrust, capabilityExecutablePath,
   officialPackageCatalog, officialCatalogFile, officialCapabilityAliases, resolvedFromHome, resolvedFromPrepared, teamEnv, isWorkspaceHome, preWorkspaceHome, isCapturedHome, capturedHomeRefusal, composeInstanceAgentsMd, parseYamlNested, withConfigFile,
-  findInstanceHome, findInstanceHomes, workspaceOf, stopInstanceSession, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, instanceSoulDir, launchConfigsAt, explicitInstanceName, retireInstance, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, defaultRepo, RELATIONS, validateLaunchConfig, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
+  findInstanceHome, findInstanceHomes, workspaceOf, stopInstanceSession, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, instanceSoulDir, launchConfigsAt, launchReportFor, explicitInstanceName, retireInstance, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, defaultRepo, RELATIONS, validateLaunchConfig, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
 } from "../lib/core.mjs";
 import {
   writeFileAtomic, LOCK_FILE, readLock, writeLock, resolvePackages, memoizedRemote,
   classifyPackageValue, parsePackageRequest } from "../lib/packages.mjs";
 import { loadLocal, validateWorkspace, validateLocal, discoverPackageSouls, workspaceWarnings } from "../lib/workspace.mjs";
+import { recordedTeams, reportRows, soulKeyOf, soulTeams, 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";
 import YAML from "yaml";
@@ -72,7 +74,7 @@ function expandInlineValues(argv) {
 const { argv: args, problem: argvProblem } = expandInlineValues(rawArgs);
 let cmd = args[0];
 const HELP_WORDS = new Set(["help", "--help", "-h"]);
-const KERNEL_COMMANDS = new Set(["automations", "trigger", "capture", "capabilities", "doctor", "inspect", "instance", "operation", "package", "readiness", "souls", "launch-config", "experimental", "onboard", "pane", "recall", "retire", "root", "schedule", "server", "session", "setup", "spawn", "status", "sync", "update", "version", "workspace"]);
+const KERNEL_COMMANDS = new Set(["automations", "trigger", "capture", "capabilities", "doctor", "inspect", "instance", "operation", "package", "readiness", "souls", "soul", "teams", "launch-config", "experimental", "onboard", "pane", "recall", "retire", "root", "schedule", "server", "session", "setup", "spawn", "status", "sync", "update", "version", "workspace"]);
 /** Commands whose argv another parser reads (packages/record and packages/experimental parse process.argv). */
 const OWN_ARGV_COMMANDS = new Set(["capture", "recall", "setup", "experimental"]);
 /** Commands `--server <id>` runs on a registered server. */
@@ -411,18 +413,17 @@ function printWorkspaceInspect(doc) {
   for (const p of doc.problems) console.log(`  ! ${p.code}: ${p.message}`);
 }
 
-/** `{ teams, teamsSource }` for a session start of a workspace home: its eligible teams read
- *  live (two repository reads), which the launch hook re-checks joined memberships against
- *  (teams contract decision 6) — or the spawn record, marked `recorded`, when the read cannot
- *  answer. Anything that is not a readable workspace home gets nothing here — the start
+/** `{ teams, defaultTeam, teamsSource }` for a session start of a workspace home: its teams read
+ *  live (the workspace host + oats-local.yaml), which the launch hook re-checks joined memberships
+ *  against — or the spawn record, marked `recorded`, when the read cannot answer. Anything that is not a readable workspace home gets nothing here — the start
  *  itself refuses it. */
 async function homeLiveTeams(home) {
   let meta;
   try { meta = JSON.parse(readFileSync(join(home, "instance.json"), "utf8")); } catch { return {}; }
   if (!isWorkspaceHome(meta)) return {};
   const { liveTeams } = await import("../lib/instance-resolution.mjs");
-  const { teams, source } = await liveTeams(home, meta, { remoteOptions: remoteOptionsFromEnv() });
-  return Array.isArray(teams) ? { teams, teamsSource: source } : {};
+  const { teams, defaultTeam, source } = await liveTeams(home, meta, { remoteOptions: remoteOptionsFromEnv() });
+  return Array.isArray(teams) ? { teams, defaultTeam, teamsSource: source } : {};
 }
 
 // ---------- operation run: generic invoke through the capability engine ----------
@@ -1072,33 +1073,46 @@ const short = (oid) => (typeof oid === "string" ? oid.slice(0, 8) : "?");
 /** Display name of a discovery: the workspace's name, or the standalone label (decision 10). */
 const workspaceName = (discovery) => discovery.workspace?.name ?? `standalone:${memberLabel(discovery.key)}`;
 const memberLabel = (key) => String(key).split("/").filter(Boolean).pop()?.replace(/\.git$/, "") || String(key);
-const teamLabel = (team) => team ?? "unassigned";
 const originOf = (item) => (item.package ? `package ${item.package} v${item.version}` : `member ${item.repoKey} @ ${short(item.commit)}`);
 
-/** A soul's spawn default harness and model (feature desktop-facts): its definition's, else the kernel's (pi, the
- *  harness's native model) — what `oats spawn <soul>` takes with no --harness/--model/--launch-config. */
-const soulDefaults = (def) => ({ harness: def?.harness ?? "pi", model: def?.model ?? null, harnessFrom: def?.harness ? "soul" : "kernel-default" });
+/** A soul's launch here (feature launch-preference): the `Launch` report a spawn with no flags would decide
+ *  (souls.launch, the soul's own launch, the host default), and the desktop-facts `harness`, `model`,
+ *  `harnessFrom` equal to its effective launch (`harnessFrom` "kernel-default" for the host default). */
+function soulLaunchFacts(entry, local, { launchConfigs, contextDir }) {
+  const launch = launchReportFor({ layers: launchLayers({ definition: entry.definition, entry, key: soulKeyOf(entry), local }), launchConfigs, contextDir });
+  return { harness: launch.effective.harness, model: launch.effective.model, harnessFrom: launch.from === "host" ? "kernel-default" : launch.from, launch };
+}
 
 /** 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). */
-function workspaceItems(discovery, lock) {
+ *  `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_*). */
+function workspaceItems(discovery, lock, local, deploymentDir) {
   const souls = [];
+  let launchConfigs = {};
+  try { launchConfigs = deploymentDir ? launchConfigsAt(deploymentDir) : {}; } catch { launchConfigs = {}; }
+  const soulDefaults = (entry) => soulLaunchFacts(entry, local, { launchConfigs, contextDir: 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; }
+  };
   for (const m of discovery.members) {
     if (!m.confirmed && !(discovery.standalone === true && m.key === discovery.key)) continue;
-    for (const s of m.souls) souls.push({ name: s.name, origin: originOf(s), kind: "member", repoKey: s.repoKey, commit: s.commit, team: teamLabel(s.team), labels: [...(s.labels ?? (s.team ? [s.team] : []))], private: s.private, path: s.path, work: s.definition.work ?? null, description: s.definition.description ?? null, ...soulDefaults(s.definition) });
-    for (const c of m.capabilities) capabilities.push({ name: c.name, origin: originOf(c), kind: "member", repoKey: c.repoKey, commit: c.commit, team: teamLabel(c.team), private: c.private, path: c.path, layer: c.manifest.layer ?? null, version: c.manifest.version ?? null });
+    for (const s of m.souls) souls.push({ name: s.name, key: soulKeyOf(s), origin: originOf(s), kind: "member", repoKey: s.repoKey, commit: s.commit, ...teamsHere(s), private: s.private, path: s.path, work: s.definition.work ?? null, description: s.definition.description ?? null, ...soulDefaults(s) });
+    for (const c of m.capabilities) capabilities.push({ name: c.name, origin: originOf(c), kind: "member", repoKey: c.repoKey, commit: c.commit, private: c.private, path: c.path, layer: c.manifest.layer ?? null, version: c.manifest.version ?? null });
   }
   for (const ext of discovery.external || []) {
     const s = ext.soul;
-    souls.push({ name: s.name, origin: `external ${s.repoKey} @ ${short(s.commit)}`, kind: "external", repoKey: s.repoKey, commit: s.commit, team: teamLabel(s.team), labels: [...(s.labels ?? (s.team ? [s.team] : []))], private: s.private, path: s.path, work: s.definition.work ?? null, description: s.definition.description ?? null, ...soulDefaults(s.definition) });
+    souls.push({ name: s.name, key: soulKeyOf(s), origin: `external ${s.repoKey} @ ${short(s.commit)}`, kind: "external", repoKey: s.repoKey, commit: s.commit, ...teamsHere(s), private: s.private, path: s.path, work: s.definition.work ?? null, description: s.definition.description ?? null, ...soulDefaults(s) });
   }
   for (const s of discovery.packageSouls || []) {
-    souls.push({ name: s.name, qualifiedName: s.qualifiedName, origin: originOf(s), kind: "package", package: s.package, version: s.version, repoKey: s.repoKey, commit: s.commit, team: teamLabel(s.team), labels: [...(s.labels ?? [])], private: false, path: s.path, work: s.definition.work ?? null, description: s.definition.description ?? null, ...soulDefaults(s.definition) });
+    souls.push({ name: s.name, key: soulKeyOf(s), qualifiedName: s.qualifiedName, origin: originOf(s), kind: "package", package: s.package, version: s.version, repoKey: s.repoKey, commit: s.commit, ...teamsHere(s), private: false, path: s.path, work: s.definition.work ?? null, description: s.definition.description ?? null, ...soulDefaults(s) });
   }
   for (const [id, entry] of Object.entries(lock?.packages || {})) {
-    for (const name of entry.capabilities) capabilities.push({ name, origin: originOf({ package: id, version: entry.version }), kind: "package", package: id, version: entry.version, commit: entry.commit, team: teamLabel(null), private: false });
+    for (const name of entry.capabilities) capabilities.push({ name, origin: originOf({ package: id, version: entry.version }), kind: "package", package: id, version: entry.version, commit: entry.commit, private: false });
   }
   const byName = (a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : a.origin < b.origin ? -1 : a.origin > b.origin ? 1 : 0);
   souls.sort(byName);
@@ -1109,7 +1123,7 @@ function workspaceItems(discovery, lock) {
 /** Membership rows for `sync` / `workspace status`. */
 function memberRows(discovery) {
   return discovery.members.map((m) => ({
-    key: m.key, name: memberLabel(m.key), commit: m.commit ?? null, confirmed: m.confirmed, status: m.confirmed ? "confirmed" : m.reason, detail: m.detail ?? null, team: m.team ?? null,
+    key: m.key, name: memberLabel(m.key), commit: m.commit ?? null, confirmed: m.confirmed, status: m.confirmed ? "confirmed" : m.reason, detail: m.detail ?? null,
     souls: m.souls.map((s) => s.name), capabilities: m.capabilities.map((c) => c.name), publishes: m.publishes ?? null,
   }));
 }
@@ -1180,7 +1194,7 @@ async function performSync(ctx, bail, { onDiscovered } = {}) {
   const members = memberRows(discovery);
   const packages = packageRows(lock);
   const changes = resolved.changes;
-  const items = workspaceItems(discovery, lock);
+  const items = workspaceItems(discovery, lock, ctx.local, ctx.deploymentDir);
   const report = { syncApi: 1, automations: automationCounts(automations), standalone: discovery.standalone === true || undefined, workspace: { name: workspaceName(discovery), key: discovery.key, url: discovery.url, commit: discovery.commit, observedAt: discovery.observedAt, local: ctx.localPath, lock: lockFile }, members, packages, changes, problems, warnings: discovery.warnings ?? [] };
   return { report, lock, discovery, items, lockFile, problems };
 }
@@ -1216,10 +1230,8 @@ function printSyncReport(ctx, synced) {
   const packageSouls = items.souls.filter((s) => s.kind === "package");
   const disabledHere = items.souls.filter(isDisabled);
   console.log(`souls      ${items.souls.length} discovered (${memberSouls.length} members, ${externalSouls.length} external, ${packageSouls.length ? `${packageSouls.length} package, ` : ""}${disabledHere.length} disabled here) · ${repoOwned.length} private capabilit${repoOwned.length === 1 ? "y" : "ies"}${repoOwned.length ? ` (${repoOwned.map((c) => `${c.name}, ${memberLabel(c.repoKey)} only`).join("; ")})` : ""}`);
-  const teams = new Map();
-  for (const s of items.souls) { const t = teams.get(s.team) || { souls: 0, capabilities: 0 }; t.souls++; teams.set(s.team, t); }
-  for (const c of items.capabilities.filter((c) => c.kind === "member")) { const t = teams.get(c.team) || { souls: 0, capabilities: 0 }; t.capabilities++; teams.set(c.team, t); }
-  console.log(`teams      ${[...teams.entries()].sort(([a], [b]) => (a < b ? -1 : 1)).map(([team, n]) => `${team} ${n.souls} soul${n.souls === 1 ? "" : "s"}${n.capabilities ? `, ${n.capabilities} capabilit${n.capabilities === 1 ? "y" : "ies"}` : ""}`).join(" · ") || "(none)"}`);
+  const sharedTeams = Object.keys(discovery.workspace?.teams || {}).sort();
+  console.log(`teams      ${sharedTeams.length ? `${sharedTeams.join(", ")} (shared)` : "(no shared teams)"} · this deployment's: oats teams`);
   const ac = report.automations;
   if (ac.triggers || ac.schedules) console.log(`automations ${ac.triggers} trigger${ac.triggers === 1 ? "" : "s"}, ${ac.schedules} schedule${ac.schedules === 1 ? "" : "s"} in the members (oats trigger list · oats schedule list)`);
   for (const p of synced.problems ?? discovery.problems) console.log(`problem    ${p.code}  ${p.repoKey ? `${memberLabel(p.repoKey)}:` : ""}${p.path}  ${p.message}`);
@@ -1417,32 +1429,46 @@ async function workspaceCmd() {
   const locked = new Set(packages.map((p) => p.id));
   const unsynced = declared.filter((id) => !locked.has(id));
   const stale = packages.filter((p) => !declared.includes(p.id)).map((p) => p.id);
-  const result = { workspaceStatusApi: 1, standalone: standalone || undefined, workspace: { name: workspaceName(discovery), key: discovery.key, url: discovery.url, commit: discovery.commit, observedAt: discovery.observedAt, local: ctx.localPath, teams: Object.keys(discovery.workspace?.teams || {}) }, members, packages, declaredPackages: declared, unsynced, stale, external: (discovery.external || []).map((e) => ({ source: e.source, soul: e.soul.name, team: teamLabel(e.soul.team) })), problems: discovery.problems, warnings: discovery.warnings ?? [] };
+  const result = { workspaceStatusApi: 1, standalone: standalone || undefined, workspace: { name: workspaceName(discovery), key: discovery.key, url: discovery.url, commit: discovery.commit, observedAt: discovery.observedAt, local: ctx.localPath, teams: sharedTeamRows(discovery) }, members, packages, declaredPackages: declared, unsynced, stale, external: (discovery.external || []).map((e) => ({ source: e.source, soul: e.soul.name })), problems: discovery.problems, warnings: [...(discovery.warnings ?? [])] };
   // Workspace automations (0.29.0), from the snapshot `oats sync` took, placed on this host.
   const actx = scopeAutomations(ctx.deploymentDir, {});
   result.automations = { host: actx.host.name, snapshot: actx.snapshot ? { takenAt: actx.snapshot.takenAt, problems: actx.snapshot.problems.length } : null, rows: [...actx.triggers, ...actx.schedules].map((a) => ({ kind: a.kind, id: a.id, runsOn: a.runsOn, owner: a.owner, runsHere: a.placement.runsHere, reason: a.placement.reason, enabledHere: a.placement.enabledHere, origin: a.origin, ...(a.invalid ? { invalid: a.invalid } : {}) })) };
+  // Automation trust (0.30): a workspace automation placed here but not trusted, and a trust entry
+  // that names none, are warnings the operator acts on in oats-local.yaml.
+  for (const a of [...actx.triggers, ...actx.schedules].filter((x) => x.placement.reason === "untrusted")) {
+    result.warnings.push({ code: "automation-untrusted", kind: a.kind, id: a.id, message: `${a.kind} ${a.id} is declared for this host (${a.runsOn}, as ${a.owner}) but not trusted here, so it does not run`, remedy: A.trustRemedy(a.id) });
+  }
+  for (const entry of A.staleTrust(actx.host, [...actx.triggers, ...actx.schedules])) {
+    result.warnings.push({ code: "automation-trust-stale", entry, message: `oats-local.yaml automations.trust names ${entry}, which is no workspace trigger or schedule${actx.snapshot ? "" : " (no automations snapshot yet: run oats sync)"}; its member may not have synced yet` });
+  }
   await workspaceStatusFacts(result, discovery, lock, ctx);
   if (JSON_MODE) { jsonOk(result); return; }
   console.log(`workspace ${workspaceName(discovery)}  (${discovery.key} @ ${short(discovery.commit)})  local ${shortPath(ctx.localPath)}\n`);
   if (standalone) console.log(`  (${standaloneNote(discovery)})\n`);
   console.log("Members:");
-  printTable(["member", "status", "commit", "team", "souls", "capabilities", "publishes"], members.map((m) => [m.name, m.status, short(m.commit), m.team ?? "—", m.souls.join(",") || "—", m.capabilities.join(",") || "—", m.publishes ? `${m.publishes.package} v${m.publishes.version ?? "?"}` : "—"]));
+  printTable(["member", "status", "commit", "souls", "capabilities", "publishes"], members.map((m) => [m.name, m.status, short(m.commit), m.souls.join(",") || "—", m.capabilities.join(",") || "—", m.publishes ? `${m.publishes.package} v${m.publishes.version ?? "?"}` : "—"]));
   for (const m of members.filter((m) => !m.confirmed)) console.log(`    ${m.name}: ${m.detail}`);
   console.log("\nPackages:");
   if (!packages.length) console.log(unsynced.length ? `  (none locked yet — \`oats sync\` resolves ${unsynced.join(", ")})` : "  (none)");
   else printTable(["package", "version", "source", "commit", "capabilities", "souls"], packages.map((p) => [p.id, p.version, p.source, short(p.commit), p.capabilities.join(","), p.souls.join(",") || "—"]));
   if (packages.length && unsynced.length) console.log(`  declared but not locked (run \`oats sync\`): ${unsynced.join(", ")}`);
   if (stale.length) console.log(`  locked but no longer declared (run \`oats sync\`): ${stale.join(", ")}`);
-  if (result.external.length) console.log(`\nExternal: ${result.external.map((e) => `${e.soul} (${e.source.replace(/@([0-9a-f]{40})$/, (_, o) => `@${short(o)}`)}, ${e.team})`).join("   ")}`);
+  if (result.external.length) console.log(`\nExternal: ${result.external.map((e) => `${e.soul} (${e.source.replace(/@([0-9a-f]{40})$/, (_, o) => `@${short(o)}`)})`).join("   ")}`);
   if (result.automations.rows.length) {
     console.log(`\nAutomations (this host: ${result.automations.host ?? "unnamed — set host.name in oats-local.yaml"}):`);
     printTable(["kind", "id", "runs on", "owner", "here"], result.automations.rows.map((r) => [r.kind, r.id, r.runsOn, r.owner, r.runsHere ? "runs here" : r.invalid ? "invalid" : r.reason ?? "disabled here"]));
   }
   if (discovery.problems.length) { console.log("\nProblems:"); for (const p of discovery.problems) console.log(`  ${p.code}  ${p.repoKey ? `${memberLabel(p.repoKey)}:` : ""}${p.path}  ${p.message}`); }
-  if (discovery.warnings?.length) { console.log("\nWarnings:"); for (const w of discovery.warnings) console.log(`  ${w.code}  ${w.message}`); }
+  if (result.warnings.length) { console.log("\nWarnings:"); for (const w of result.warnings) console.log(`  ${w.code}  ${w.message}${w.remedy ? `\n    ${w.remedy}` : ""}`); }
+}
+
+/** The committed (shared) teams as `workspace status` reports them: rows in label order (team model v2). */
+function sharedTeamRows(discovery) {
+  const teams = discovery.standalone === true ? {} : discovery.workspace?.teams || {};
+  return Object.keys(teams).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)).map((label) => ({ label, team: typeof teams[label]?.team === "string" ? teams[label].team : null, description: typeof teams[label]?.description === "string" ? teams[label].description : null }));
 }
 
-/** `oats workspace status` facts (feature desktop-facts): the workspace and team defaults as rows; this
+/** `oats workspace status` facts (feature desktop-facts): the workspace defaults as rows; this
  *  computer (member clones and the rule that found each, disabled souls, the lock); file locations with
  *  browsable urls; each catalog package's newer version, when the official catalog has one. */
 async function workspaceStatusFacts(result, discovery, lock, ctx) {
@@ -1454,7 +1480,6 @@ async function workspaceStatusFacts(result, discovery, lock, ctx) {
   result.defaults = {
     slots: Object.fromEntries(LAYERS.map((l) => [l, slot(defaults[l])])),
     capabilities: rows(defaults.capabilities),
-    byTeam: Object.fromEntries(Object.entries(defaults.byTeam && typeof defaults.byTeam === "object" ? defaults.byTeam : {}).map(([label, t]) => [label, { capabilities: rows(t?.capabilities) }])),
   };
   result.workspace.file = discovery.standalone === true ? null : { path: "oats-workspace.yaml", url: browseUrl(discovery.key, discovery.commit, "oats-workspace.yaml") };
   for (const m of result.members) Object.assign(m, { url: browseUrl(m.key, m.commit), membershipFile: { path: "oats-membership.yaml", url: browseUrl(m.key, m.commit, "oats-membership.yaml") } });
@@ -1475,6 +1500,88 @@ 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). */
+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 };
+}
+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. */
+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]";
+  const sub = positional(1);
+  if (sub !== undefined && !["add", "remove", "default"].includes(sub)) bail("E_USAGE", usage);
+  const label = sub ? positional(2) : undefined;
+  if (sub && label === undefined) bail("E_BAD_ARGS", `oats teams ${sub} needs a team label — ${usage}`);
+  const ctx = await teamsContext(bail);
+  const V = await import("../lib/teams-verbs.mjs");
+  let result = null;
+  try {
+    if (sub === "add") result = V.teamsAdd(ctx, label, { team: valueFlag("team"), description: valueFlag("description") });
+    else if (sub === "remove") result = V.teamsRemove(ctx, label);
+    else if (sub === "default") result = V.teamsDefault(ctx, label);
+  } catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_")) return bail(e.code, e.message, e.details); throw e; }
+  const doc = V.teamsDocument(result ? { ...ctx, local: result.local } : ctx);
+  if (JSON_MODE) { jsonOk(result ? { ...doc, changed: result.changed } : 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)"}`);
+  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(",")}`);
+  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. */
+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]";
+  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") };
+  const ctx = workspaceContext(bail);
+  let teamsCtx, soul = "*", key = "*";
+  if (name === "*") teamsCtx = await teamsContext(bail);
+  else {
+    // The soul is named as for spawn: E_SOUL_UNKNOWN / E_SOUL_AMBIGUOUS; package souls come from the lock.
+    let lock = null;
+    try { lock = existsSync(join(ctx.deploymentDir, LOCK_FILE)) ? readLock(ctx.deploymentDir) : null; } catch (e) { return bail(e.code || "E_LOCK_SCHEMA", e.message, e.details); }
+    let discovery, entry;
+    try {
+      const { discoverOrStandalone, findSoulEntry } = await import("../lib/instance-resolution.mjs");
+      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);
+    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 } : 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)"}`);
+  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(",")]));
+}
+
 /** `oats capabilities` / `oats souls` [--dir] [--json] — contract §6. */
 async function itemsCmd(kind) {
   const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
@@ -1482,7 +1589,7 @@ async function itemsCmd(kind) {
   const discovery = await discoverForCli(ctx, bail);
   let lock;
   try { lock = readLock(ctx.deploymentDir); } catch (e) { return bail(e.code || "E_LOCK_SCHEMA", e.message, e.details); }
-  const items = workspaceItems(discovery, lock)[kind];
+  const items = workspaceItems(discovery, lock, ctx.local, ctx.deploymentDir)[kind];
   // One command's reads at a commit are shared: many souls resolve over the same manifests and listings.
   const remote = memoizedRemote(remoteModule);
   if (kind === "capabilities") await capabilityFacts(items, discovery, lock, ctx, remote);
@@ -1491,8 +1598,8 @@ async function itemsCmd(kind) {
   if (JSON_MODE) { jsonOk({ [`${kind}Api`]: 1, standalone: standalone || undefined, workspace: { name: workspaceName(discovery), key: discovery.key, commit: discovery.commit }, [kind]: items, problems: discovery.problems }); return; }
   console.log(`${kind} of workspace ${workspaceName(discovery)} (${discovery.key} @ ${short(discovery.commit)})${standalone ? `  — ${standaloneNote(discovery)}` : ""}\n`);
   if (!items.length) console.log("  (none)");
-  else if (kind === "souls") printTable(["name", "origin", "team", "work"], items.map((s) => [s.name, s.origin, s.labels?.length > 1 ? s.labels.join(",") : s.team, s.work ?? "—"]));
-  else printTable(["name", "origin", "team", "layer"], items.map((c) => [c.private ? `${c.name} (repo-owned)` : c.name, c.origin, c.team, c.layer ?? "—"]));
+  else if (kind === "souls") printTable(["name", "origin", "teams here", "work"], items.map((s) => [s.name, s.origin, s.teams === null ? "(invalid: oats teams)" : s.teams.map((t) => (t.default ? `${t.label}*` : t.label)).join(",") || "—", s.work ?? "—"]));
+  else printTable(["name", "origin", "layer"], items.map((c) => [c.private ? `${c.name} (repo-owned)` : c.name, c.origin, c.layer ?? "—"]));
   const unsynced = Object.keys(discovery.workspace?.packages || {}).filter((id) => !lock.packages[id]);
   if (kind === "capabilities" && unsynced.length) console.log(`\n  package capabilities of ${unsynced.join(", ")} appear after \`oats sync\``);
 }
@@ -1636,6 +1743,16 @@ function soulRepoLabel(a, ws) {
   const moved = stamp.current && stamp.commit && stamp.current !== stamp.commit ? ` (member now @ ${short7(stamp.current)})` : "";
   return `${memberLabel(stamp.repoKey)} @ ${short7(stamp.commit)}${moved}`;
 }
+/** A roster agent's soul key: the qualified name of a package soul, else the recorded agent (soul) name;
+ *  null when no instance records a workspace soul. Exactly soulKeyOf for the soul it was spawned from. */
+function agentSoulKey(a) {
+  for (const i of a.instances || []) {
+    const soul = i?.workspace?.soul;
+    if (!soul || typeof soul !== "object") continue;
+    return soul.package && typeof soul.qualifiedName === "string" ? soul.qualifiedName : (typeof i.agent === "string" ? i.agent : a.name);
+  }
+  return null;
+}
 const short7 = (oid) => (typeof oid === "string" ? oid.slice(0, 7) : "?");
 
 async function status() {
@@ -1648,6 +1765,9 @@ 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.
+    for (const a of data) a.key = agentSoulKey(a);
     if (ws) for (const a of data) {
       const stamp = ws.souls.get(a.name);
       if (stamp) a.soulSource = { repoKey: stamp.repoKey, commit: stamp.commit, path: stamp.path, ...(stamp.current ? { current: stamp.current, status: stamp.current === stamp.commit ? "current" : "moved" } : {}) };
@@ -1764,7 +1884,7 @@ async function spawnCmd() {
         if (!agent || soulFetched || agent._dir !== dirname(soulDir)) agent = findAgent(root, soulName);
       }
       if (!agent) bail("E_SOUL_UNKNOWN", `soul "${name}" was fetched to ${shortPath(soulDir)} but is not readable as a soul there`);
-      note(`(workspace soul: "${name}" from ${wsPrepared.soulEntry.repoKey} @ ${String(wsPrepared.soulEntry.commit).slice(0, 12)}${wsPrepared.soulEntry.team ? `, team ${wsPrepared.soulEntry.team}` : ""}${soulFetched ? "; soul source fetched" : ""})`);
+      note(`(workspace soul: "${name}" from ${wsPrepared.soulEntry.repoKey} @ ${String(wsPrepared.soulEntry.commit).slice(0, 12)}${wsPrepared.resolution.defaultTeam ? `, team ${wsPrepared.resolution.defaultTeam.label}` : ""}${soulFetched ? "; soul source fetched" : ""})`);
     } catch (e) {
       // Standalone (decisions 10/25): the ONLY package request is the kernel's own
       // default; when the catalog cannot name it, say so instead of "add it to packages:"
@@ -1922,7 +2042,7 @@ async function spawnCmd() {
     // A launch refusal (configuration, executable, environment reference,
     // model, harness) is a fact about the selection, not a spawn-mechanism
     // failure: it keeps its own code so a GUI can act on it.
-    if (typeof e?.code === "string" && /^E_LAUNCH_|^E_MODEL_UNKNOWN$|^E_UNSUPPORTED_HARNESS$/.test(e.code)) { bail(e.code, e.message); throw e; }
+    if (typeof e?.code === "string" && /^E_LAUNCH_|^E_MODEL_UNKNOWN$|^E_UNSUPPORTED_HARNESS$|^E_HARNESS_UNAVAILABLE$/.test(e.code)) { bail(e.code, e.message, e.details); throw e; }
     // An unmet declared requirement is a fact about the soul's configuration
     // (with a remedy), not a spawn-mechanism failure: keep its code and details.
     if (e?.code === "E_REQUIREMENT_INACTIVE") { bail(e.code, e.message, { soul: e.soul, capabilities: e.capabilities, context: e.context, remedy: e.remedy }); throw e; }
@@ -2201,7 +2321,9 @@ async function triggerCmd() {
         try {
           const { observeWorkspace } = await import("../lib/workspace.mjs");
           const { local } = loadLocal(ws());
-          if (typeof local.workspace === "string") workspaceTeams = Object.keys((await observeWorkspace(local.workspace, { remoteOptions: remoteOptionsFromEnv() })).workspace.teams || {});
+          // The labels declared here: the committed shared teams and this deployment's local ones.
+          const shared = typeof local.workspace === "string" && !local.standalone ? (await observeWorkspace(local.workspace, { remoteOptions: remoteOptionsFromEnv() })).workspace : null;
+          workspaceTeams = [...teamModel(shared, local).labels.keys()];
         } catch { /* reported as unknown (null) */ }
         return out(T.testTrigger(ws(), needId(), { workspaceTeams, ctx: ctx() }), (r) => [
           `trigger ${r.id}: ${r.ok ? "ready" : "NOT ready"} (nothing was spawned)`,
@@ -2279,7 +2401,11 @@ async function sessionCmd() {
       if (launchConfig === true) bad("--launch-config needs a configuration name, or none");
       const harness = harnessFlag();
       if (harness === true || (harness !== undefined && !LAUNCH_HARNESSES.includes(harness))) bad(`--harness must be one of ${LAUNCH_HARNESSES.join(", ")}`);
-      const opts = { model: model || undefined, launchConfig, harness, yolo: yoloFlag(), env: process.env, ...(await homeLiveTeams(home)) };
+      // --reselect-launch (feature launch-preference): the home's launch layers decide again; without it a
+      // recorded launch stays frozen (a changed preference never reaches an existing home on its own).
+      const reselectLaunch = args.includes("--reselect-launch");
+      if (reselectLaunch && launchConfig !== undefined) bad("--reselect-launch applies the launch preferences; --launch-config names one explicitly — choose one");
+      const opts = { model: model || undefined, launchConfig, harness, yolo: yoloFlag(), ...(reselectLaunch ? { reselectLaunch: true } : {}), env: process.env, ...(await homeLiveTeams(home)) };
       if (args[1] === "restart") {
         const grace = flag("stop-grace");
         if (grace !== undefined) { if (grace === true || !/^\d+$/.test(String(grace)) || Number(grace) < 1 || Number(grace) > 300) bad("--stop-grace needs a number of seconds (1..300) to wait for the harness after SIGTERM"); opts.stopGraceMs = Number(grace) * 1000; }
@@ -2302,8 +2428,13 @@ async function sessionCmd() {
       const file = flag("file");
       if (!file || file === true) throw Object.assign(new Error("session upload needs --file <local path>"), { code: "E_BAD_ARGS" });
       result = uploadAttachment({ file, home: home === true ? undefined : home });
-    } else throw Object.assign(new Error("usage: oats session inspect|input|attach|start|restart|receive|upload --home /absolute/home [--text-file path] [--model id] [--launch-config name|none] [--harness pi|claude|codex] [--yolo|--no-yolo] [--stop-grace seconds] [--name file] [--file path] [--json]"), { code: "E_BAD_ARGS" });
-    if (JSON_MODE) jsonOk(result); else console.log(JSON.stringify(result, null, 2));
+    } else throw Object.assign(new Error("usage: oats session inspect|input|attach|start|restart|receive|upload --home /absolute/home [--text-file path] [--model id] [--launch-config name|none | --reselect-launch] [--harness pi|claude|codex] [--yolo|--no-yolo] [--stop-grace seconds] [--name file] [--file path] [--json]"), { code: "E_BAD_ARGS" });
+    if (JSON_MODE) jsonOk(result);
+    else {
+      console.log(JSON.stringify(result, null, 2));
+      // A start's launch-hook warnings, as spawn prints its own (stderr keeps stdout one JSON document).
+      for (const w of result?.warnings || []) console.error(`  WARNING: ${w}`);
+    }
   } catch (e) { cmdFail(e.code || "E_SESSION_FAILED", e.message, e.details); }
 }
 
@@ -2313,8 +2444,8 @@ async function paneCmd() {
 
 /** `oats onboard [<dir>] --workspace <repo ref> [--json]` — workspace model v2 (decision 9).
  *
- * Realizes a workspace on this machine in the directory the operator chooses (decision 9)
- * (docs/design/2026-09-23-simplified-workspace-model.md §4): writes
+ * Realizes a workspace on this machine in the directory the operator chooses
+ * (docs/workspaces.md): writes
  * `<dir>/oats-local.yaml` naming the workspace, creates `<dir>/agents/` (the
  * instance homes), then runs exactly the `oats sync` path — discover over the
  * remotes, confirm membership, resolve `packages:`, write `oats-lock.json`. Nothing is installed, no soul
@@ -2543,8 +2674,8 @@ async function capabilityCommand() {
         const ws = meta.workspace && typeof meta.workspace === "object" ? meta.workspace : {};
         const messaging = (meta.capabilities || []).find((c) => c.layer === "messaging")?.id;
         homeMeta = { meta, messaging };
-        homeTeamCtx = (teams, teamsSource) => teamEnv({ workspace: { key: ws.key, name: ws.name, deployment: ws.deployment, team: ws.soul?.team, slots: { messaging } }, payloads: meta.providers, teams, teamsSource });
-        teamCtx = homeTeamCtx(meta.teams, "recorded");
+        homeTeamCtx = (t) => teamEnv({ workspace: { key: ws.key, name: ws.name, deployment: ws.deployment }, teams: t.teams, defaultTeam: t.defaultTeam, teamsSource: t.source });
+        teamCtx = homeTeamCtx({ ...recordedTeams(meta), source: "recorded" });
       } else {
         // Not inside a home: a v2 deployment (oats-local.yaml in reach) resolves
         // through the workspace, exactly as a spawn of --soul would (below).
@@ -2567,7 +2698,7 @@ async function capabilityCommand() {
     if (homeMeta && m.capability === homeMeta.messaging) {
       const { liveTeams } = await import("../lib/instance-resolution.mjs");
       const live = await liveTeams(instanceHome, homeMeta.meta, { remoteOptions: remoteOptionsFromEnv() });
-      teamCtx = homeTeamCtx(live.teams, live.source);
+      teamCtx = homeTeamCtx(live);
     }
     return runManifestCommand(m, { settings: capSettings[m.capability] || {}, origins: capOrigins[m.capability] }, teamCtx, () => m._dir, soulDir);
   }
@@ -2692,7 +2823,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", "herdr"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations"], 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", "teams", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts"], 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 }));
+    console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends: ["tmux", "herdr"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations"], 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"], 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 }));
     return;
   }
   console.log(`@awebai/oats ${OATS_VERSION} (desktop API v1)`);
@@ -3044,7 +3175,7 @@ async function serverRouteCmd() {
 // blame` pointing at the commit that last changed each command.
 const TYPED_CLI_FAILURES = new Set(["unsafe-config-key", "unsafe-config-value"]);
 /** Removed 0.24 verbs → their v2 replacement (workspace model v2, decision 5). Checked before capability dispatch. */
-const REMOVED_VERBS = { prepare: "`oats onboard` / `oats sync` to set up a workspace, and `oats spawn <soul> --preview` to see what a spawn would resolve (the captured/portable path was removed in 0.26)", create: "author souls/<name>/soul.yaml + AGENTS.md in a member repository, then `oats sync`", type: "the soul's own soul.yaml in its member repository (agent types were a classic config block)", soul: "the soul's soul.yaml / AGENTS.md in its member repository, then `oats sync` (per-spawn choices: spawn flags or a launch configuration)", install: "oats sync", restore: "oats sync", init: "oats-local.yaml + oats sync", use: "soul.yaml capabilities: { <cap>: { from } } + workspace defaults", trust: "declaring the package in packages: (package approval was removed; oats sync locks commit + integrity)", list: "oats workspace status | oats capabilities", catalog: "oats package add <id> <version> (bare versions resolve through package-catalog.json)", remove: "oats package remove <id>", migrate: "a rebuild (no migration: docs/design/2026-09-23-workspace-module-contracts.md)", config: "oats-local.yaml (host settings) and oats-workspace.yaml (shared)", inject: "injection overrides are not part of the workspace model yet; edit the capability inject in its member repo" };
+const REMOVED_VERBS = { prepare: "`oats onboard` / `oats sync` to set up a workspace, and `oats spawn <soul> --preview` to see what a spawn would resolve (the captured/portable path was removed in 0.26)", create: "author souls/<name>/soul.yaml + AGENTS.md in a member repository, then `oats sync`", type: "the soul's own soul.yaml in its member repository (agent types were a classic config block)", install: "oats sync", restore: "oats sync", init: "oats-local.yaml + oats sync", use: "soul.yaml capabilities: { <cap>: { from } } + workspace defaults", trust: "declaring the package in packages: (package approval was removed; oats sync locks commit + integrity)", list: "oats workspace status | oats capabilities", catalog: "oats package add <id> <version> (bare versions resolve through package-catalog.json)", remove: "oats package remove <id>", migrate: "a rebuild (no migration: docs/design/2026-09-23-workspace-module-contracts.md)", config: "oats-local.yaml (host settings) and oats-workspace.yaml (shared)", inject: "injection overrides are not part of the workspace model yet; edit the capability inject in its member repo" };
 try {
 // The captured/portable path was removed in 0.26 (lead decisions on (e), D2/D3):
 // its selectors and an inherited captured context are refused, never quietly
@@ -3100,6 +3231,8 @@ else if (cmd === "sync") await syncCmd();
 else if (cmd === "package") await packageCmd();
 else if (cmd === "workspace") await workspaceCmd();
 else if (cmd === "capabilities" || cmd === "souls") await itemsCmd(cmd);
+else if (cmd === "teams") await teamsCmd();
+else if (cmd === "soul") await soulCmd();
 else if (cmd === "status") await status();
 else if (cmd === "pane") await paneCmd();
 else if (cmd === "version" || cmd === "--version" || cmd === "-v") versionCmd();
@@ -3223,6 +3356,9 @@ Usage:
   oats session start --home <absolute-home>  start a STOPPED instance again in its existing home
       [--model m] [--launch-config n|none]  (recorded recipe as is; a selection re-resolves it
       [--harness r] [--yolo|--no-yolo]      against the scope; a named configuration is a unit)
+      [--reselect-launch]                   applies the launch preferences now (oats-local.yaml
+                                            souls.launch, the soul's launch); a changed preference
+                                            never reaches an existing home without it or a respawn
   oats session restart --home <abs-home>     stop the running harness (SIGTERM, bounded wait,
       [same flags] [--stop-grace <s>]        never escalated) and start it again in place under
                                             the same lock; a stop that is not observed is
@@ -3230,7 +3366,7 @@ Usage:
       [--model <m>] [--json]                 (same identity, worktree, notes and launch env; no
                                             spawn hooks); --model replaces the recorded model
                                             for this and later starts; a live harness is refused
-  oats spawn <agent> [--task <text>]         spawn an instance (tmux/Herdr; --no-launch
+  oats spawn <agent> [--task <text> | --task-file <f>]  spawn an instance (tmux/Herdr; --no-launch
       [--purpose <slug>] [--repo <r>]       = scaffold only); the agent is a workspace
       [--parent <instance>]                 soul or a capability-defined agent
       [--relation child|sibling|parent|unrelated]    --relation + --relative-to anchor the
@@ -3238,7 +3374,9 @@ Usage:
       [--relative-root <agents-root>]       disambiguates same-named team anchors
       [--work worktree|checkout|attached|workspace|directory]  = sugar for --relative-to X --relation
       [--work-dir <owner-work>] [--harness pi|claude|codex] [--backend tmux|herdr] [--herdr-socket <path>] [--yolo|--no-yolo] [--model <m>] [--branch <b>]  child (default: unrelated, top-level)
-      [--no-launch] [--json]
+      [--no-launch] [--json]                 without --launch-config/--harness the launch is the
+                                            soul's preference: oats-local.yaml souls.launch.<soul>,
+                                            then souls.launch."*", then the soul's launch:, then pi
                                             with team: declared, unknown souls
                                             resolve across the team scope's repos
                                             directory: owned home/work, config context may
@@ -3302,7 +3440,13 @@ Usage:
                                             its own repo's souls) + the locked packages
   oats souls [--dir <d>] [--json]            every soul of every confirmed member + external souls
                                             (souls have no private mode), with origin
-                                            (member <key> @ <commit> | package <id> v<ver>) and team
+                                            (member <key> @ <commit> | package <id> v<ver>) and its
+                                            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
+                                            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
   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