@awebai/oats 0.29.4 → 0.30.0

package/lib/instance-inspect.mjs

@@ -14,10 +14,12 @@ import { spawnSync } from "node:child_process";
 import { accessSync, constants as fsConstants, existsSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { capabilityManifests, instanceSoulDir, manifestOperations, parseYamlNested, servedIdentityOf, teamEnv, upgradeHomeMeta, withConfigFile } from "./core.mjs";
-import { agentDirOf, discoverOrStandalone, findSoulEntry, liveTeams, prepareInstance } from "./instance-resolution.mjs";
+import { capabilityManifests, homeLaunchLayers, instanceSoulDir, launchConfigsAt, launchReportFor, manifestOperations, parseYamlNested, servedIdentityOf, teamEnv, upgradeHomeMeta, withConfigFile } from "./core.mjs";
+import { agentDirOf, discoverOrStandalone, ensureWorkspaceSoul, findSoulEntry, liveTeams, prepareInstance } from "./instance-resolution.mjs";
 import { declaredSettings } from "./capability-contract.mjs";
-import { kernelCompatibility, teamLabelsOf, teamsOf } from "./resolve.mjs";
+import { kernelCompatibility } from "./resolve.mjs";
+import { recordedTeams, reportRows, soulKeyOf, soulTeams, teamModel, teamProblems } from "./teams.mjs";
+import { launchLayers, launchReport } from "./launch-preference.mjs";
 import { loadLocal } from "./workspace.mjs";
 import { ensureModuleTree } from "./operator-dispatch.mjs";
 /** Bounds of a provider check's answer (bytes, nesting, entries), as the released binding wire set them. */
@@ -34,7 +36,9 @@ const real = (p) => { try { return realpathSync(p); } catch { return resolve(p);
 
 /** A resolution refusal that is a readiness FACT (the soul cannot resolve as the
  *  lock stands), not a failure to answer: reported as a failing `installed` item. */
-export const RESOLUTION_FACTS = new Set(["E_PACKAGE_MISSING", "E_PACKAGE_INTEGRITY", "E_CAPABILITY_MISSING", "E_LOCK_SCHEMA", "E_REQUIREMENT_INACTIVE"]);
+export const RESOLUTION_FACTS = new Set(["E_PACKAGE_MISSING", "E_PACKAGE_INTEGRITY", "E_CAPABILITY_MISSING", "E_LOCK_SCHEMA", "E_REQUIREMENT_INACTIVE", "E_TEAM_UNKNOWN", "E_TEAM_NOT_ELIGIBLE"]);
+/** A resolution refusal that readiness reports as a team item (checks.configured), not an install failure. */
+const TEAM_FACTS = new Set(["E_TEAM_UNKNOWN", "E_TEAM_NOT_ELIGIBLE"]);
 
 /** Is `name` an executable on PATH? (manifest `requires`, no shell). */
 function onPath(name) {
@@ -54,7 +58,7 @@ const missingRequires = (manifest) => manifestRequires(manifest).filter((r) => !
 function declarationsOf(definition) {
   const d = obj(definition) ? definition : {};
   const section = (key) => (d[key] === undefined ? null : d[key]);
-  return { requires: section("requires"), defaults: section("defaults"), knowledge: section("knowledge"), teams: section("teams"), resources: section("resources"), children: section("children"), capabilities: section("capabilities") };
+  return { requires: section("requires"), defaults: section("defaults"), knowledge: section("knowledge"), resources: section("resources"), children: section("children"), capabilities: section("capabilities") };
 }
 function readSoulYaml(soulDir) {
   const file = soulDir && join(soulDir, "soul.yaml");
@@ -68,9 +72,9 @@ function readTextCapped(file, cap = 200_000) {
 }
 
 /** The instance target: `home` is absolute and holds instance.json with modules.
- *  `teams` is the home's LIVE eligible teams (teams contract decision 6), read from this
- *  target's discovery when it discovers, else by liveTeams; `teamsSource` says which
- *  ("live" | "recorded": the spawn-time record, when the workspace cannot answer now).
+ *  `teams` / `defaultTeam` are the home's LIVE teams (team model v2), read from this target's
+ *  discovery when it discovers, else by liveTeams; `teamsSource` says which ("live" |
+ *  "recorded": the spawn-time record, when the workspace cannot answer now).
  *  `live: false` skips the live read — a caller that never hands the teams to the
  *  messaging provider (a non-messaging operation) gets the record at no remote cost. */
 export async function homeTarget(home, meta, { remoteOptions, discover = true, live: readLive = true } = {}) {
@@ -88,12 +92,13 @@ export async function homeTarget(home, meta, { remoteOptions, discover = true, l
   const ws = obj(meta.workspace) ? meta.workspace : {};
   const soulDir = instanceSoulDir(realHome, meta) ?? null;
   const { definition, problems } = readSoulYaml(soulDir);
-  let discovery = null, discoveryError = null;
+  let discovery = null, discoveryError = null, local = null;
   if (discover) {
     try {
       // The derived deployment exactly — never an oats-local.yaml found further up.
       const found = loadLocal(deployment);
       if (real(dirname(found.path)) !== real(deployment)) throw Object.assign(new Error(`${deployment} has no oats-local.yaml`), { code: "E_HOME_MISMATCH" });
+      local = found.local;
       discovery = await discoverOrStandalone(found.local, { deployment, remoteOptions });
     }
     catch (e) { discoveryError = { code: e.code || "E_REMOTE_UNREADABLE", message: e.message }; }
@@ -106,18 +111,26 @@ export async function homeTarget(home, meta, { remoteOptions, discover = true, l
     if (external === null && (discovery.members || []).some((m) => m.key === ws.soul?.repoKey)) external = false;
   }
   const slots = Object.fromEntries(LAYERS.map((l) => [l, Object.keys(modules).find((n) => manifests[n]?.layer === l) ?? null]));
-  let live;
+  // The home's soul key (souls.teams / souls.default): its name, or <package>/<soul> for a package soul.
+  const teamKey = ws.soul?.package && typeof ws.soul.qualifiedName === "string" ? ws.soul.qualifiedName : meta.agent;
+  let live, model = null;
   if (discovery) {
-    let entry = null; try { entry = findSoulEntry(discovery, meta.agent); } catch { /* no longer listed */ }
-    live = entry && entry.repoKey === ws.soul?.repoKey
-      ? { teams: teamsOf(discovery.standalone === true ? null : discovery.workspace, teamLabelsOf(entry)), source: "live" }
-      : { teams: Array.isArray(meta.teams) ? meta.teams : null, source: "recorded" };
+    model = teamModel(discovery.standalone === true ? null : discovery.workspace, local, { workspaceKey: discovery.key ?? null });
+    try { const t = soulTeams(model, teamKey); live = { teams: reportRows(t.teams), defaultTeam: t.defaultTeam, source: "live" }; }
+    catch (e) { if (!String(e?.code).startsWith("E_TEAM_")) throw e; live = { ...recordedTeams(meta), source: "recorded" }; }
   } else if (readLive) live = await liveTeams(realHome, meta, { remoteOptions });
-  else live = { teams: Array.isArray(meta.teams) ? meta.teams : null, source: "recorded" };
+  else live = { ...recordedTeams(meta), source: "recorded" };
+  // Feature launch-preference: the recorded launch (frozen), and what --reselect-launch would choose now —
+  // from the home's recorded soul and this deployment's oats-local.yaml (null when it cannot be read).
+  const launch = recordedLaunch(meta);
+  let launchCurrent = null;
+  try { launchCurrent = launchReportFor({ layers: homeLaunchLayers(realHome, meta), launchConfigs: launchConfigsAt(deployment), contextDir: deployment }); }
+  catch { launchCurrent = null; }
   return {
-    kind: "instance", home: realHome, meta, deployment, agentsRoot, teams: live.teams, teamsSource: live.source,
+    kind: "instance", home: realHome, meta, deployment, agentsRoot, teams: live.teams, defaultTeam: live.defaultTeam ?? null, teamsSource: live.source, launch, launchCurrent,
+    recordedDefaultTeam: recordedTeams(meta).defaultTeam, teamModel: model, teamKey,
     subject: { kind: "instance", instance: meta.instance, home, soul: meta.agent },
-    soul: { name: meta.agent, repoKey: ws.soul?.repoKey ?? null, commit: ws.soul?.commit ?? null, team: ws.soul?.team ?? null, external, path: null, soulDir, definition, problems: [...problems, ...loadProblems] },
+    soul: { name: meta.agent, repoKey: ws.soul?.repoKey ?? null, commit: ws.soul?.commit ?? null, external, path: null, soulDir, definition, problems: [...problems, ...loadProblems] },
     workspace: { key: ws.key ?? null, name: typeof ws.name === "string" ? ws.name : discovery?.workspace?.name ?? null, deployment, commit: ws.commit ?? null, standalone: ws.standalone === true },
     modules: Object.keys(modules).sort().map((name) => ({ name, from: modules[name]?.from ?? null, manifest: manifests[name] ?? null, dir: join(realHome, ".oats", "modules", name) })),
     payloads: obj(meta.providers) ? meta.providers : {},
@@ -146,14 +159,34 @@ export async function soulTarget(contextDir, soul, { remoteOptions } = {}) {
     soulEntry = findSoulEntry(discovery, soul);
   }
   const res = prepared?.resolution;
-  // A refused resolution still names its eligible teams: the labels and the workspace are known.
-  const teams = res?.teams ?? teamsOf(discovery?.standalone === true ? null : discovery?.workspace ?? null, teamLabelsOf(soulEntry));
-  const cached = soulEntry?.commit ? join(deployment, "agents", agentDirOf(soulEntry), "souls", String(soulEntry.commit).slice(0, 12)) : null;
+  // A refused resolution still names the soul's teams when they resolve (a package refusal, …); a
+  // refusal of the teams themselves (E_TEAM_UNKNOWN / E_TEAM_NOT_ELIGIBLE) names none.
+  const model = teamModel(discovery?.standalone === true ? null : discovery?.workspace ?? null, prepared?.local ?? found.local, { workspaceKey: discovery?.key ?? null });
+  const teamKey = soulKeyOf(soulEntry);
+  let teams = res?.teams ?? null, defaultTeam = res ? res.defaultTeam ?? null : null;
+  if (!res) { try { const t = soulTeams(model, teamKey); teams = reportRows(t.teams); defaultTeam = t.defaultTeam; } catch (e) { if (!String(e?.code).startsWith("E_TEAM_")) throw e; } }
+  // The soul being asked about is materialised as a spawn would (ensureWorkspaceSoul: idempotent per
+  // commit, never touching a directory an instance links), so its checks always get OATS_SOUL; only a
+  // spawn wrote the per-commit copy before, and a provider asked about a soul not yet spawned at this
+  // commit answered a false negative. A failure is a readiness fact (soulCopyError), never a silent null.
+  // A refused resolution has nothing to materialise: the cached copy, when there is one.
+  let soulDir = null, soulCopyError = null;
+  if (prepared) {
+    try { soulDir = await ensureWorkspaceSoul(prepared, join(deployment, "agents")); }
+    catch (e) { soulCopyError = { code: e?.code || "E_SOUL_COPY_FAILED", message: e?.message || String(e) }; }
+  } else {
+    const cached = soulEntry?.commit ? join(deployment, "agents", agentDirOf(soulEntry), "souls", String(soulEntry.commit).slice(0, 12)) : null;
+    soulDir = cached && existsSync(join(cached, "soul.yaml")) ? cached : null;
+  }
+  // Feature launch-preference: what a spawn with no flags would launch here.
+  let launchConfigs = {};
+  try { launchConfigs = launchConfigsAt(deployment); } catch { launchConfigs = {}; }
+  const launch = launchReportFor({ layers: prepared?.launch ?? launchLayers({ definition: soulEntry.definition, entry: soulEntry, key: teamKey, local: found.local }), launchConfigs, contextDir: deployment });
   return {
-    kind: "soul", home: null, meta: null, deployment, agentsRoot: join(deployment, "agents"), teams, teamsSource: "live",
-    subject: { kind: "soul", soul: soulEntry.name, repoKey: soulEntry.repoKey ?? null, commit: soulEntry.commit ?? null, team: soulEntry.team ?? null },
-    soul: { name: soulEntry.name, repoKey: soulEntry.repoKey ?? null, commit: soulEntry.commit ?? null, team: soulEntry.team ?? null, external: soulEntry.external === true, path: soulEntry.path ?? null,
-      soulDir: cached && existsSync(join(cached, "soul.yaml")) ? cached : null, definition: soulEntry.definition ?? null, problems: [] },
+    kind: "soul", home: null, meta: null, deployment, agentsRoot: join(deployment, "agents"), teams, defaultTeam, teamsSource: "live", teamModel: model, teamKey, launch,
+    subject: { kind: "soul", soul: soulEntry.name, repoKey: soulEntry.repoKey ?? null, commit: soulEntry.commit ?? null },
+    soul: { name: soulEntry.name, repoKey: soulEntry.repoKey ?? null, commit: soulEntry.commit ?? null, external: soulEntry.external === true, path: soulEntry.path ?? null,
+      soulDir, definition: soulEntry.definition ?? null, problems: [], ...(soulCopyError ? { copyError: soulCopyError } : {}) },
     workspace: { key: discovery?.key ?? null, name: discovery?.workspace?.name ?? null, deployment, commit: discovery?.commit ?? null, standalone: discovery?.standalone === true },
     modules: (res?.modules || []).map((m) => ({ name: m.name, from: m.from ?? null, manifest: m.manifest ?? null, dir: null, module: m })).sort((a, b) => a.name.localeCompare(b.name)),
     payloads: obj(res?.payloads) ? res.payloads : {}, payloadOrigins: obj(res?.payloadOrigins) ? res.payloadOrigins : {}, slots: obj(res?.slots) ? res.slots : Object.fromEntries(LAYERS.map((l) => [l, null])), slotsFrom: obj(res?.slotsFrom) ? res.slotsFrom : {},
@@ -195,7 +228,7 @@ function capabilityRows(t) {
 }
 function soulRow(t) {
   const s = t.soul, def = obj(s.definition) ? s.definition : {};
-  return { soulsApi: SOULS_API, name: s.name, repoKey: s.repoKey, commit: s.commit, team: s.team, kind: s.external === true ? "external" : s.external === false ? "member" : null, path: s.path,
+  return { soulsApi: SOULS_API, name: s.name, repoKey: s.repoKey, commit: s.commit, kind: s.external === true ? "external" : s.external === false ? "member" : null, path: s.path,
     description: def.description ?? null, work: def.work ?? null, harness: def.harness ?? null, model: def.model ?? null,
     declarations: declarationsOf(s.definition), declarationProblems: s.problems,
     instructions: s.soulDir ? readTextCapped(join(s.soulDir, "AGENTS.md")) : null };
@@ -215,20 +248,57 @@ export function inspectDocument(t, { kernel }) {
     // The capabilities the soul turned off (feature desktop-facts): its `off` over a workspace/team entry
     // (reason "off"), or a `<slot>: none` that dropped a workspace default (reason "slot-none", slot).
     capabilitiesOff: (t.turnedOff || []).map(({ name, reason, slot, overrides }) => ({ id: name, off: true, from: "soul", reason, ...(slot ? { slot } : {}), overrides })),
-    // Teams contract item 7 (feature `teams`): the ELIGIBLE teams, one per soul label in order —
-    // live for a home (`teamsSource: "recorded"` when its workspace could not be read now).
-    teams: t.teams ?? null, teamsSource: t.teamsSource ?? null,
+    // Team model v2 (feature team-model-2): the soul's teams here and its default — live for a home
+    // (`teamsSource: "recorded"` when its workspace could not be read now), which also answers the
+    // default it was spawned with.
+    teams: t.teams ?? null, defaultTeam: t.defaultTeam ?? null, teamsSource: t.teamsSource ?? null,
+    ...(t.home ? { recordedDefaultTeam: t.recordedDefaultTeam ?? null } : {}),
+    // Feature launch-preference: a soul's launch here; a home's recorded launch and launchCurrent.
+    launch: t.launch ?? null,
+    ...(t.home ? { launchCurrent: t.launchCurrent ?? null } : {}),
     knowledge: kcap ? { provider: kcap.id, version: kcap.version, operations: kcap.operations.map((o) => ({ name: o.name, kind: o.kind, available: o.available, reason: o.reason })) } : { provider: null, version: null, operations: [] },
     instance: m ? { home: t.home, instance: m.instance, agent: m.agent, harness: m.harness || null, model: m.model ?? null, yolo: m.yolo ?? null, launched: !!m.launched, createdAt: m.createdAt || null,
       resolution: m.workspace?.resolution ?? null, soulDir: t.soul.soulDir, instructions: { ...readTextCapped(join(t.home, "AGENTS.md")), sources: m.instructions || [] } } : null,
     ...(m ? { identity: servedIdentityOf(m) } : {}),
-    problems: [...t.soul.problems, ...(t.discoveryError ? [t.discoveryError] : []),
+    problems: [...t.soul.problems, ...(t.soul.copyError ? [t.soul.copyError] : []), ...(t.discoveryError ? [t.discoveryError] : []),
       ...t.modules.filter((x) => !x.manifest).map((x) => ({ code: "module-missing", message: `${x.name} is recorded but its module copy has no readable oats.json`, capability: x.name })),
       ...capabilities.filter((c) => !c.compatibility.ok).map((c) => ({ code: "capability-incompatible", message: `${c.id} requires oats ${c.compatibility.range}; this kernel is ${c.compatibility.kernel} (re-spawn from the deployment with a release whose range admits it)`, capability: c.id, range: c.compatibility.range, kernel: c.compatibility.kernel }))],
   };
 }
 
 // ---------- readiness ----------
+/** The soul's team problems as readiness items in `checks.configured` (team model v2; no fifth check:
+ *  released Desktops recompute the summary from the four). A failure blocks `ready`; a warning is
+ *  `required: false`. A home also compares its spawn-time default with the live one. */
+function teamItems(t) {
+  if (!t.teamModel) return [];
+  const problems = teamProblems(t.teamModel, { key: t.teamKey, messaging: !!t.slots?.messaging });
+  const same = (a, b) => (a?.label ?? null) === (b?.label ?? null) && (a?.team ?? null) === (b?.team ?? null);
+  if (t.home && t.teamsSource === "live" && t.meta?.defaultTeam !== undefined && !same(t.recordedDefaultTeam, t.defaultTeam)) {
+    problems.push({ code: "default-team-changed", severity: "warning", recorded: t.recordedDefaultTeam, current: t.defaultTeam,
+      message: `this instance was spawned in ${t.recordedDefaultTeam?.label ?? "no default team"}; the default is now ${t.defaultTeam?.label ?? "none"}`, fix: "respawn" });
+  }
+  return problems.map(({ code, severity, message, fix, ...rest }) => item(rest.label ? `team ${rest.label}` : "teams", "fail",
+    { required: severity === "failure", producer: "team model", code, reason: message, remedy: fix, ...rest }));
+}
+/** The home's recorded launch as a `Launch` (from instance.json; `from: "recorded"` for a home from before 0.30). */
+function recordedLaunch(meta) {
+  const recipe = obj(meta?.launch) ? meta.launch : {};
+  return launchReport({ declared: obj(meta?.launchDeclared) ? meta.launchDeclared : null, harness: meta?.harness || recipe.harness || null, model: meta?.model || null,
+    launchConfig: recipe.launchConfig ?? null, from: typeof meta?.launchFrom === "string" ? meta.launchFrom : "recorded", at: meta?.launchAt ?? null });
+}
+/** `launch-changed` (feature launch-preference; `--home` only): a home whose launch a LAYER chose (not explicit
+ *  flags, not a pre-0.30 record) now reads a different launch from the layers. A warning: the home keeps its
+ *  recorded launch until `--reselect-launch` or a respawn. */
+function launchItems(t) {
+  if (!t.home || !t.launch || !t.launchCurrent || !["local", "local-default", "soul", "host"].includes(t.launch.from)) return [];
+  const a = t.launch.effective, b = t.launchCurrent.effective;
+  if (a.harness === b.harness && a.model === b.model && a.launchConfig === b.launchConfig) return [];
+  const show = (e) => `${e.harness ?? "?"}${e.model ? ` ${e.model}` : ""}${e.launchConfig ? ` (launch configuration ${e.launchConfig})` : ""}`;
+  return [item("launch", "fail", { required: false, producer: "launch preference", code: "launch-changed",
+    reason: `this instance runs ${show(a)}; its launch preference now says ${show(b)} (${t.launchCurrent.at ?? t.launchCurrent.from})`,
+    remedy: "`oats session restart --reselect-launch`, or respawn", recorded: a, current: b, from: t.launchCurrent.from, at: t.launchCurrent.at })];
+}
 function roll(items) {
   const req = items.filter((i) => i.required !== false);
   if (!items.length) return "not-applicable";
@@ -241,7 +311,7 @@ const item = (subject, status, { required = true, reason = null, producer = "ker
 /** The team/workspace facts a provider receives, as hooks get them (teamEnv). */
 function providerEnv(t, capability, settings) {
   const env = Object.fromEntries(Object.entries(process.env).filter(([k]) => !/^(OATS_|OAS_|PI_)/.test(k)));
-  Object.assign(env, teamEnv({ workspace: { key: t.workspace.key, name: t.workspace.name, deployment: t.deployment, team: t.soul.team, slots: t.slots }, payloads: t.payloads, teams: t.teams, teamsSource: t.teamsSource }));
+  Object.assign(env, teamEnv({ workspace: { key: t.workspace.key, name: t.workspace.name, deployment: t.deployment }, teams: t.teams, defaultTeam: t.defaultTeam, teamsSource: t.teamsSource }));
   return Object.assign(env, { OATS_CAPABILITY: capability, OATS_SETTINGS: JSON.stringify(settings), OATS_SETTINGS_ORIGINS: JSON.stringify(t.payloadOrigins?.[capability] ?? {}), OATS_CLI_BIN: CLI_BIN, OATS_WORKSPACE: t.deployment,
     ...(t.home ? { OATS_INSTANCE: t.meta.instance, OATS_INSTANCE_HOME: t.home } : {}), OATS_AGENT: t.soul.name, ...(t.soul.soulDir ? { OATS_SOUL: t.soul.soulDir } : {}) });
 }
@@ -276,10 +346,10 @@ export function runProviderCheck(t, mod, dir, { timeoutMs = 30000 } = {}) {
   if (!file) return unavailable("resource-not-found", `${mod.name}: the check executable ${script} is unavailable`);
   const settings = obj(t.payloads[mod.name]) ? t.payloads[mod.name] : {};
   // The released binding wire, key for key: providers decode it strictly (oats.aweb 1.13.1
-  // refuses any other key). The eligible teams reach the check through its environment
-  // (OATS_TEAMS / OATS_TEAMS_SOURCE / OATS_TEAM_LABELS, providerEnv), never on stdin.
+  // refuses any other key). The teams reach the check through its environment
+  // (OATS_DEFAULT_TEAM* / OATS_TEAMS / OATS_TEAMS_SOURCE, providerEnv), never on stdin.
   const request = { schemaVersion: 1, phase: "check", slot: m.layer ?? null, capability: mod.name, settings,
-    input: { context: { kind: "workspace", workspace: t.workspace.key, deployment: t.deployment, soul: t.soul.name, team: t.soul.team, instance: t.meta?.instance ?? null, home: t.home }, action: { kind: "readiness" } } };
+    input: { context: { kind: "workspace", workspace: t.workspace.key, deployment: t.deployment, soul: t.soul.name, instance: t.meta?.instance ?? null, home: t.home }, action: { kind: "readiness" } } };
   // The environment is providerEnv's: ambient OATS_/OAS_/PI_ identity removed, the rest
   // inherited.
   const r = spawnSync(process.execPath, [file, ...args], { cwd: dir, env: providerEnv(t, mod.name, settings), input: JSON.stringify(request), encoding: "utf8", timeout: Math.max(1, timeoutMs), killSignal: "SIGKILL", maxBuffer: BINDING_LIMITS.maxBytes, stdio: ["pipe", "pipe", "pipe"] });
@@ -315,9 +385,13 @@ export const PROVIDER_CHECK_BUDGET_MS = 60_000;
 export async function readinessDocument(t, { selector = null, remoteOptions, catalog = null, budgetMs = PROVIDER_CHECK_BUDGET_MS } = {}) {
   const installed = [], configured = [], member = [], providers = [];
   const cap = (id) => ({ capability: { id } });
-  if (t.resolutionError) {
+  if (t.resolutionError && !TEAM_FACTS.has(t.resolutionError.code)) {
     installed.push(item(t.soul.name, "fail", { producer: "workspace resolution", code: t.resolutionError.code, reason: t.resolutionError.message, evidence: t.resolutionError.details, remedy: "oats sync (the lock must provide every package capability the soul resolves)" }));
   }
+  if (t.soul.copyError) {
+    installed.push(item(`soul ${t.soul.name}`, "fail", { producer: "soul copy", code: t.soul.copyError.code, reason: `the soul could not be copied into ${join(t.agentsRoot, "…", "souls")}: ${t.soul.copyError.message}`,
+      evidence: { repoKey: t.soul.repoKey, commit: t.soul.commit }, remedy: "check access to the soul's repository at the locked commit (oats sync), then retry" }));
+  }
   for (const mod of t.modules) {
     const present = t.home ? existsSync(join(mod.dir, "oats.json")) && !!mod.manifest : !!mod.manifest;
     installed.push(item(mod.name, present ? "pass" : "fail", { producer: t.home ? "instance modules" : "workspace resolution", evidence: { from: mod.from },
@@ -328,6 +402,7 @@ export async function readinessDocument(t, { selector = null, remoteOptions, cat
         evidence: { command: req.command }, remedy: found ? null : req.install, ...cap(mod.name) }));
     }
   }
+  configured.push(...teamItems(t), ...launchItems(t));
   // member — the soul's member repository is a confirmed member of the workspace
   // (oats-membership.yaml backlink observed over the remotes).
   const d = t.discovery;

package/lib/instance-lifecycle.mjs

@@ -10,7 +10,7 @@
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { basename, join } from "node:path";
-import { findInstanceHomes, inspectInstanceSession, listAgents, listInstances, retirePendingMarkerPath, stopInstanceSession } from "./core.mjs";
+import { findInstanceHomes, inspectInstanceSession, listAgents, listInstances, observeSessionWithoutReceipt, retirePendingMarkerPath, stopInstanceSession } from "./core.mjs";
 import { observeInstanceGit } from "./instance-git.mjs";
 import { appendEvent } from "./instance-events.mjs";
 import { oatsError } from "./errors.mjs";
@@ -74,6 +74,17 @@ function sessionFacts(home) {
   try { const s = inspectInstanceSession(home); return { state: s.state, present: s.present, backend: s.backend ?? null, established: true }; }
   catch (e) { return { state: "unestablished", present: null, backend: null, established: false, reason: e.code || "E_SESSION_UNAVAILABLE" }; }
 }
+/** Retire's view of a home without its session receipt (before 0.25.9): the
+ *  retirement needs only absence, which it can observe — `{state: "absent",
+ *  present: false, established: true, note}`; live or ambiguous stays
+ *  unestablished, with the note saying why (retire refuses it). */
+function retireSessionFacts(home, session) {
+  if (session.established || session.reason !== "E_RUNTIME_ENDPOINT_UNKNOWN") return session;
+  const meta = readJson(join(home, "instance.json"));
+  if (!meta) return session;
+  const seen = observeSessionWithoutReceipt(home, meta);
+  return seen.absent ? { state: "absent", present: false, backend: seen.backend, established: true, note: seen.note } : { ...session, note: seen.note };
+}
 const running = (s) => s.established && s.present === true && !["shell", "stopped", "not-launched"].includes(s.state);
 function workFacts(home) {
   if (!existsSync(join(home, "work"))) return { observed: false, reason: "no-worktree" };
@@ -161,6 +172,7 @@ export function planRetire(ctx, root, name, { home } = {}) {
   const me = resolveInstance(ctx, root, name, { home });
   const kids = descendantsOf(me.root, name);
   const target = targetFacts({ ...me, instance: name, depth: 0 });
+  target.session = retireSessionFacts(me.home, target.session);
   const meta = readJson(join(me.home, "instance.json")) || {};
   const facts = { session: target.session, work: target.work, workMode: meta.work ?? null, repo: meta.repo ?? null, recordedBranch: meta.branch ?? null,
     children: kids.map((c) => ({ instance: c.instance, agent: c.agent, home: c.home, session: sessionFacts(c.home) })),
@@ -175,6 +187,7 @@ export function planRetire(ctx, root, name, { home } = {}) {
       ...(facts.work.observed && facts.work.changed + facts.work.untracked > 0 ? [`${facts.work.changed} changed and ${facts.work.untracked} untracked file(s) would be retained with the worktree`] : []),
       ...(kids.length ? [`${kids.length} recorded child instance(s) are stopped first (bounded SIGTERM, never escalated) and retained (their homes are not removed); a child still running after the grace refuses the retirement`] : []),
       ...((kids.ambiguous || []).length ? [`${kids.ambiguous.length} instance(s) record this name as parent but the name is not unique under this root; they are listed under ambiguous and NOT acted on`] : []),
+      ...(target.session.note ? [target.session.established ? `session absent: ${target.session.note}; nothing needs quiescing` : `session not observably absent: ${target.session.note}; retire refuses until it is stopped`] : []),
       "pull request state is unknown to the kernel; the ADE reports it when a forge connection exists",
     ] };
 }

package/lib/instance-resolution.mjs

@@ -19,8 +19,10 @@
 import { existsSync, readFileSync, readdirSync, lstatSync, realpathSync } from "node:fs";
 import { join, resolve as resolvePath, dirname, relative, isAbsolute, sep } from "node:path";
 import { oatsError } from "./errors.mjs";
-import { loadLocal, discoverWorkspace, discoverRepo, standaloneRepo, observeWorkspace, observeSoulLabels } from "./workspace.mjs";
-import { resolveSoul, teamsOf, kernelCompatibility } from "./resolve.mjs";
+import { loadLocal, discoverWorkspace, discoverRepo, standaloneRepo, observeWorkspace } from "./workspace.mjs";
+import { resolveSoul, kernelCompatibility } from "./resolve.mjs";
+import { BY_TEAM_REMOVED, recordedTeams, reportRows, soulKeyOf, soulTeams, teamModel } from "./teams.mjs";
+import { launchLayers } from "./launch-preference.mjs";
 import { declaredSettings } from "./capability-contract.mjs";
 import { materialize, MODULES_DIR, SKILLS_DIR } from "./materialize.mjs";
 import { fetchRemoteTree } from "./remote.mjs";
@@ -39,14 +41,13 @@ function err(code, message, details) { const e = oatsError(code, message, detail
  *  Same set as lib/resolve.mjs POISON_KEYS; refused with E_WORKSPACE_SCHEMA reason
  *  "poison-key" so a `--provider constructor x=1` never reaches Object.prototype. */
 const POISON_KEYS = new Set(["__proto__", "constructor", "prototype"]);
-/** `byTeam` is reserved: legal ONLY at the top level of workspace.messaging (decision 23);
- *  a spawn payload may never smuggle it in. */
+/** `byTeam` was removed in 0.30 (team model v2): a spawn payload may not carry it. */
 const RESERVED_KEY = "byTeam";
 
 /** Parse repeated `--provider <cap> k=v` occurrences into { <cap>: { k: v } }.
  *  Values are strings; `k=v=w` keeps everything after the first `=`. Poison keys
  *  (capability OR any path segment) are E_WORKSPACE_SCHEMA reason "poison-key";
- *  `byTeam` (any path segment) is E_WORKSPACE_SCHEMA reason "reserved-key". Both are
+ *  `byTeam` (any path segment) is E_WORKSPACE_SCHEMA reason "removed-key". Both are
  *  refused again in resolve (defense in depth). The accumulators are built with
  *  Object.create(null) and only OWN keys are ever reused, so a name that happens to
  *  exist on Object.prototype (`toString`, `hasOwnProperty`) never writes through to it. */
@@ -63,7 +64,7 @@ export function parseProviderFlags(pairs) {
     const parts = key.split(".");
     for (const p of parts) {
       if (POISON_KEYS.has(p)) throw err("E_WORKSPACE_SCHEMA", `--provider ${cap}: key ${JSON.stringify(key)} is refused (segment ${JSON.stringify(p)} would poison the payload's prototype)`, { path: `/${cap}/${parts.join("/")}`, key: p, reason: "poison-key" });
-      if (p === RESERVED_KEY) throw err("E_WORKSPACE_SCHEMA", `--provider ${cap}: key ${JSON.stringify(key)} is refused (${JSON.stringify(RESERVED_KEY)} is reserved for the top level of workspace.messaging)`, { path: `/${cap}/${parts.join("/")}`, key: p, reason: "reserved-key" });
+      if (p === RESERVED_KEY) throw err("E_WORKSPACE_SCHEMA", `--provider ${cap}: key ${JSON.stringify(key)} is refused (${BY_TEAM_REMOVED})`, { path: `/${cap}/${parts.join("/")}`, key: p, reason: "removed-key" });
     }
     if (!Object.hasOwn(out, cap)) out[cap] = Object.create(null);
     let cur = out[cap];
@@ -130,33 +131,29 @@ export function disabledEntry(local, soulEntry) {
 }
 
 /**
- * A home's LIVE eligible teams (teams contract 2026-09-25, decision 6). Teams are messaging
- * state, not frozen composition: the soul's labels are read from its repository NOW and each
- * label's payload from the workspace's current `messaging`. The home's modules and skills are
- * untouched. No workspace discovery: exactly two repository reads — the workspace host at its
- * current commit (observeWorkspace) and the soul's own repo (observeSoulLabels).
- * → { teams, source: "live" } — or, when that cannot answer (the host or the soul's repo is
- *   unreachable, the soul is no longer listed, a standalone deployment), the spawn-time record:
- *   { teams: <record, or null when none>, source: "recorded", reason }.
+ * A home's LIVE teams (team model v2): the committed shared teams (the workspace host read now) and the
+ * deployment's oats-local.yaml as it is now, resolved for the home's soul key (its name, or
+ * `<package>/<soul>`). The home's modules and skills are untouched. One repository read, the workspace
+ * host; a standalone deployment has local teams only and reads none.
+ * → { teams, defaultTeam, source: "live" } — or, when that cannot answer (the host is unreachable, the
+ *   deployment or its teams are unreadable), the spawn-time record: { teams, defaultTeam, source: "recorded", reason }.
  * `source` travels as OATS_TEAMS_SOURCE: a provider leaves a joined team only on a `live` answer.
  */
 export async function liveTeams(home, meta, { remoteOptions, remote } = {}) {
-  const recorded = (reason, error) => ({ teams: Array.isArray(meta?.teams) ? meta.teams : null, source: "recorded", reason, ...(error ? { error } : {}) });
+  const recorded = (reason, error) => ({ ...recordedTeams(meta), source: "recorded", reason, ...(error ? { error } : {}) });
   const soul = meta?.workspace?.soul;
-  // A home without a workspace soul record (a pre-0.29 capability agent's) has nothing to re-read.
-  if (!soul || typeof soul.repoKey !== "string" || typeof meta.agent !== "string") return recorded("no-workspace-soul");
-  // A package soul's labels are pinned with the package: the spawn-time record is its answer.
-  if (soul.package && typeof soul.package === "object") return recorded("package-soul");
+  // A home without a workspace soul record has nothing to resolve.
+  if (!soul || typeof meta.agent !== "string") return recorded("no-workspace-soul");
+  const key = soul.package && typeof soul.qualifiedName === "string" ? soul.qualifiedName : meta.agent;
   const deployment = dirname(dirname(dirname(dirname(resolvePath(home)))));
   try {
     const found = loadLocal(deployment);
     if (!found.path || resolvePath(dirname(found.path)) !== resolvePath(deployment)) return recorded("no-deployment");
-    if (typeof found.local.standalone === "string" && found.local.standalone) return recorded("standalone");
-    const wsObs = await observeWorkspace(found.local.workspace, { remoteOptions, remote });
-    const labels = await observeSoulLabels(wsObs, { name: meta.agent, repoKey: soul.repoKey }, { remoteOptions, remote });
-    if (labels === null) return recorded("soul-not-listed");
-    return { teams: teamsOf(wsObs.workspace, labels), source: "live" };
-  } catch (e) { return recorded("unreadable", { code: e?.code || "E_REMOTE_UNREADABLE", message: e?.message ?? String(e) }); }
+    const standalone = typeof found.local.standalone === "string" && found.local.standalone;
+    const wsObs = standalone ? null : await observeWorkspace(found.local.workspace, { remoteOptions, remote });
+    const t = soulTeams(teamModel(wsObs?.workspace ?? null, found.local, { workspaceKey: wsObs?.key ?? null }), key);
+    return { teams: reportRows(t.teams), defaultTeam: t.defaultTeam, source: "live" };
+  } catch (e) { return recorded(String(e?.code).startsWith("E_TEAM_") ? "invalid-teams" : "unreadable", { code: e?.code || "E_REMOTE_UNREADABLE", message: e?.message ?? String(e) }); }
 }
 
 /** The per-commit soul cache under an agent directory: `<agentDir>/souls/<commit12>/`.
@@ -425,7 +422,7 @@ export function requireMemberClone(prepared, { explicit } = {}) {
 }
 
 /** Would a spawn of this discovered soul be refused before it touches this machine (feature desktop-facts)?
- *  The same checks prepareInstance makes — souls.disabled, then the soul's resolution (team conflicts, slot
+ *  The same checks prepareInstance makes — souls.disabled, then the soul's resolution (its teams here, slot
  *  conflicts, missing or private capabilities, compatibility …) — without spawning anything.
  *  → { spawnable: true, problem: null } | { spawnable: false, problem: { code, message } } */
 export async function soulSpawnability(local, discovery, lock, soulEntry, { remoteOptions, remote } = {}) {
@@ -447,7 +444,9 @@ export async function prepareInstance(contextDir, soulName, { spawn = {}, remote
   const disabled = disabledEntry(local, soulEntry);
   if (disabled !== null) throw err("E_SOUL_DISABLED", `soul ${qualifiedSoulName(soulEntry)} is disabled on this machine (oats-local.yaml souls.disabled: ${disabled}) — remove it from that list to spawn it here`, { name: soulEntry.name, qualifiedName: qualifiedSoulName(soulEntry), entry: disabled });
   const resolution = await resolveSoul(discovery, soulEntry, { local, lock, spawn, remoteOptions, remote });
-  return { local, deployment, lock, discovery, soulEntry, resolution, remoteOptions, spawn };
+  // The launch layers a new selection reads (feature launch-preference): souls.launch, the soul's own launch.
+  const launch = launchLayers({ definition: soulEntry.definition, entry: soulEntry, key: soulKeyOf(soulEntry), local });
+  return { local, deployment, lock, discovery, soulEntry, resolution, remoteOptions, spawn, launch };
 }
 
 /** E_REMOTE_UNREADABLE reasons (lib/remote.mjs classifyRemoteFailure) that mean "the

package/lib/launch-preference.mjs

@@ -0,0 +1,87 @@
+/**
+ * Soul launch preferences (0.30, feature `launch-preference`; docs/design/2026-09-28-soul-launch-preference.md,
+ * docs/desktop-cli-api.md "Launch preferences"). PURE: no I/O. A soul may declare `launch: {harness, model?}`;
+ * a machine overrides it in oats-local.yaml `souls.launch` (a soul key or "*" → a launch configuration's name
+ * or an inline {harness, model?}). For a NEW selection the first layer with a value decides: the flags, then
+ * souls.launch.<key>, souls.launch."*", the soul's launch, the host default. A home's recorded launch stays
+ * frozen: a plain start/restart never re-reads these layers (only --reselect-launch or a respawn does).
+ */
+import { oatsError } from "./errors.mjs";
+
+export const LOCAL_FILE = "oats-local.yaml";
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+/** A coded error whose details also sit on `details` (the CLI boundary renders them). */
+function fail(code, message, details) { const e = oatsError(code, message, details); e.details = details; return e; }
+const pointerKey = (k) => String(k).replace(/~/g, "~0").replace(/\//g, "~1");
+
+/** A preference value as `{harness, model}` (`model` null when absent); anything else → null. */
+export function preferenceOf(v) {
+  return isObject(v) && typeof v.harness === "string" ? { harness: v.harness, model: typeof v.model === "string" && v.model ? v.model : null } : null;
+}
+
+/** Where a soul's own `launch` lives: `<repoKey>:<path>/soul.yaml#/launch`, or `package:<id>:<path>/…` for a package soul. */
+export function soulLaunchAt(entry) {
+  const file = `${entry?.path ? `${entry.path}/` : ""}soul.yaml#/launch`;
+  const pkg = typeof entry?.package === "string" ? entry.package : entry?.package?.id;
+  return pkg ? `package:${pkg}:${file}` : `${entry?.repoKey ?? "?"}:${file}`;
+}
+
+/**
+ * The layers a new selection reads, without flags: `declared` (the soul's own launch, or null) and `layer`
+ * — the deciding one, `{ from: "local" | "local-default" | "soul", at, value }` (`value` a launch
+ * configuration's name or `{harness, model}`) — or null (the host default).
+ * `definition` is the soul.yaml content; `key` its soul key (soulKeyOf); `local` the oats-local.yaml value.
+ */
+export function launchLayers({ definition, entry, key, local }) {
+  const declared = preferenceOf(definition?.launch);
+  const byKey = isObject(local?.souls?.launch) ? local.souls.launch : {};
+  const pick = (k, from) => {
+    if (!Object.hasOwn(byKey, k)) return null;
+    const v = byKey[k];
+    return { from, at: `${LOCAL_FILE}#/souls/launch/${pointerKey(k)}`, value: typeof v === "string" ? v : preferenceOf(v) };
+  };
+  const layer = (key !== undefined && key !== "*" ? pick(key, "local") : null) ?? pick("*", "local-default")
+    ?? (declared ? { from: "soul", at: soulLaunchAt(entry), value: declared } : null);
+  return { declared, layer };
+}
+
+/**
+ * The selection a NEW launch makes from the flags and the layers: `{ selection, preference, from, at }` for
+ * resolveLaunchSelection. `--launch-config` or `--harness` decides (`from: "flag"`); otherwise the layer does
+ * (a name selects that configuration; an inline or soul preference is `preference`), and `--model` alone
+ * replaces only the model. No layer: the host default (`from: "host"`).
+ */
+export function selectionFrom({ flags = {}, layers }) {
+  const selection = { launchConfig: flags.launchConfig, harness: flags.harness, model: flags.model };
+  if (flags.launchConfig !== undefined || flags.harness !== undefined) return { selection, preference: null, from: "flag", at: null };
+  const layer = layers?.layer;
+  if (!layer) return { selection, preference: null, from: "host", at: null };
+  if (typeof layer.value === "string") return { selection: { ...selection, launchConfig: layer.value }, preference: null, from: layer.from, at: layer.at };
+  return { selection: { ...selection, launchConfig: "none" }, preference: { ...layer.value, from: layer.from }, from: layer.from, at: layer.at };
+}
+
+/** A launch configuration the layer names but this oats-local.yaml does not declare. */
+export function launchConfigUnknown({ name, from, at }) {
+  return fail("E_LAUNCH_CONFIG_UNKNOWN", `${at ?? "the launch preference"} names launch configuration ${JSON.stringify(name)}, which ${LOCAL_FILE} does not declare (launch-configs:); oats launch-config list shows what is`, { name, from, at });
+}
+
+/** The fix for a missing harness, by the layer that chose it. */
+export function harnessFix(harness, from) {
+  if (from === "flag") return `install ${harness}, or choose another --harness / --launch-config`;
+  if (from === "local" || from === "local-default") return `install ${harness}, or change ${LOCAL_FILE} souls.launch`;
+  return `install ${harness}, or override it on this machine in ${LOCAL_FILE} souls.launch`;
+}
+/** E_HARNESS_UNAVAILABLE: the chosen harness has no executable here. Never a fallback to another harness. */
+export function harnessUnavailable({ harness, from, at, why }) {
+  const source = from === "flag" ? "the spawn flags" : from === "host" ? "the host default" : at ?? from;
+  const fix = harnessFix(harness, from);
+  return fail("E_HARNESS_UNAVAILABLE", `${harness} is not installed on this machine (${why}); ${source} chose it — ${fix}`, { harness, from, at: at ?? null, fix });
+}
+
+/** The closed `Launch` report: `{declared, effective: {harness, model, launchConfig}, from, at, problem}`. */
+export function launchReport({ declared = null, harness, model = null, launchConfig = null, from, at = null, problem = null }) {
+  return { declared: declared ? { harness: declared.harness, model: declared.model ?? null } : null, effective: { harness, model: model || null, launchConfig: launchConfig || null }, from, at: at ?? null, problem };
+}
+
+/** `modelFrom` for a model a preference layer supplied. */
+export const MODEL_SOURCE = { soul: "soul preference", local: "local preference", "local-default": "local-default preference" };

package/lib/materialize.mjs

@@ -576,7 +576,7 @@ export function driftOf(instanceJson, discovery, { lock } = {}) {
  * → { name, repoKey, commit, current: { commit } | null, status: "current"|"moved"|"missing", reason? } | null
  *
  * Decision 17 for the SOUL SOURCE: a workspace spawn records `instance.json.workspace.soul =
- * { repoKey, commit, team }` (the member and commit the soul was fetched from). The member row
+ * { repoKey, commit }` (the member and commit the soul was fetched from). The member row
  * for `repoKey` in `discovery.members` is the current state: a different commit → "moved", the
  * soul gone from the member → "missing" (reason "soul-absent"), no usable row → "missing"
  * (reason "unconfirmed" / the row's reason). A standalone view's own member row is unconfirmed
@@ -595,7 +595,7 @@ export function soulDriftOf(instanceJson, discovery) {
     // A package soul: "moved" means the package pin moved (another version/commit is locked now).
     const pkg = { package: soul.package.id, version: soul.package.version ?? null };
     const soulName = typeof soul.name === "string" ? soul.name : name;
-    const base = { name: soulName, repoKey: soul.repoKey, commit, team: soul.team ?? null, ...pkg };
+    const base = { name: soulName, repoKey: soul.repoKey, commit, ...pkg };
     const listed = Array.isArray(discovery?.packageSouls) ? discovery.packageSouls.filter((s) => s && s.package === soul.package.id) : [];
     const now = listed.find((s) => s.name === soulName) || null;
     if (!now) return { ...base, current: null, status: "missing", reason: listed.length ? "soul-absent" : "package-absent" };
@@ -604,7 +604,7 @@ export function soulDriftOf(instanceJson, discovery) {
   const members = Array.isArray(discovery?.members) ? discovery.members : [];
   const member = members.find((m) => m && m.key === soul.repoKey) || null;
   const standaloneOwn = discovery?.standalone === true && member && member.key === discovery.key && typeof member.commit === "string";
-  const base = { name, repoKey: soul.repoKey, commit, team: soul.team ?? null };
+  const base = { name, repoKey: soul.repoKey, commit };
   if (!member || (!member.confirmed && !standaloneOwn) || typeof member.commit !== "string") {
     return { ...base, current: null, status: "missing", reason: member ? (member.reason || "unconfirmed") : "unconfirmed" };
   }