@awebai/oats 0.29.3 → 0.30.0

package/lib/core.mjs

@@ -44,6 +44,8 @@ import { killGroup } from "./process-group.mjs";
 import { ensureHerdr, allocateHerdr, launchHerdr, inspectHerdr, stopHerdr, validHerdrTarget, herdrSnapshot, herdrCommand } from "./herdr.mjs";
 
 import { oatsError } from "./errors.mjs";
+import { envRows, recordedTeams, teamsEnv } from "./teams.mjs";
+import { harnessUnavailable, launchConfigUnknown, launchLayers, launchReport, selectionFrom } from "./launch-preference.mjs";
 async function materializePreparedDefault(prepared, home) { const m = await import("./instance-resolution.mjs"); return m.materializePrepared(prepared, home); }
 // Capability rows for a PREPARED spawn (workspace model): the one function that
 // turns a Resolution's modules into the row shape hooks/environment/requirements/
@@ -856,7 +858,7 @@ function readCatalogFile() {
   // Capability aliases (0.19.1 migration contract): legacy capability id →
   // official package id. Identity mappings (package id == capability id) need
   // no entry; an alias exists for capabilities a package exports under another
-  // package identity (oats.review is exported by package oats.dev).
+  // package identity (oats.developer is exported by package oats.engineering).
   //
   // The object form may also carry "capability": the id the package exports
   // TODAY in place of the legacy id (a RENAMING alias, the oas.* → oats.*
@@ -1009,9 +1011,9 @@ function layerRows(resolution) {
 export function resolvedFromPrepared(prepared, contextDir) {
   return {
     capabilities: Array.isArray(prepared.capabilityRows) && prepared.capabilityRows.length ? prepared.capabilityRows : plannedCapabilityRows(prepared.resolution),
-    workspace: { key: prepared.discovery?.key ?? null, name: prepared.discovery?.workspace?.name ?? null, deployment: prepared.deployment ?? null, commit: prepared.discovery?.commit ?? null, standalone: prepared.discovery?.standalone === true, revision: prepared.resolution.revision, team: prepared.resolution.soul?.team ?? null, slots: prepared.resolution.slots },
+    workspace: { key: prepared.discovery?.key ?? null, name: prepared.discovery?.workspace?.name ?? null, deployment: prepared.deployment ?? null, commit: prepared.discovery?.commit ?? null, standalone: prepared.discovery?.standalone === true, revision: prepared.resolution.revision, slots: prepared.resolution.slots },
     payloads: prepared.resolution.payloads ?? {},
-    teams: prepared.resolution.teams ?? [], teamsSource: "live",
+    teams: prepared.resolution.teams ?? [], defaultTeam: prepared.resolution.defaultTeam ?? null, teamsSource: "live",
     layers: layerRows(prepared.resolution),
     launchConfigs: launchConfigsAt(contextDir || prepared.deployment),
   };
@@ -1020,20 +1022,17 @@ export function resolvedFromPrepared(prepared, contextDir) {
 /** The resolved view of an EXISTING home: what it recorded at spawn (its
  *  capability rows, workspace and payloads) and its deployment's launch
  *  configurations. Never re-resolved against the scope. The one live part is
- *  `teams` (teams contract decision 6): a caller that computed the home's live
- *  eligible teams (liveTeams) passes them; otherwise the spawn-time record. */
-export function resolvedFromHome(home, meta, { teams, teamsSource } = {}) {
-  // The team facts read `workspace.team` and `workspace.slots.messaging` (teamEnv); a home records
-  // the soul's primary label under `workspace.soul.team` and its messaging module among its
-  // capabilities — shaped here exactly as the in-home command dispatch shapes them.
+ *  the teams (team model v2): a caller that computed the home's live teams
+ *  (liveTeams) passes them; otherwise the spawn-time record. */
+export function resolvedFromHome(home, meta, { teams, defaultTeam, teamsSource } = {}) {
   const ws = meta?.workspace && typeof meta.workspace === "object" ? meta.workspace : null;
   const messaging = (Array.isArray(meta?.capabilities) ? meta.capabilities : []).find((c) => c?.layer === "messaging")?.id ?? null;
+  const t = Array.isArray(teams) ? { teams, defaultTeam: defaultTeam ?? null, teamsSource: teamsSource === "live" ? "live" : "recorded" } : { ...recordedTeams(meta), teamsSource: "recorded" };
   return {
     capabilities: Array.isArray(meta?.capabilityRuntime) ? meta.capabilityRuntime : [],
-    workspace: ws ? { ...ws, team: ws.soul?.team ?? null, slots: { messaging } } : null,
+    workspace: ws ? { ...ws, slots: { messaging } } : null,
     payloads: meta?.providers ?? {},
-    teams: Array.isArray(teams) ? teams : Array.isArray(meta?.teams) ? meta.teams : null,
-    teamsSource: Array.isArray(teams) ? (teamsSource === "live" ? "live" : "recorded") : "recorded",
+    ...t,
     layers: ws && typeof ws.layers === "object" && ws.layers ? ws.layers : {}, // recorded at spawn; none before layers-from
     launchConfigs: launchConfigsAt(home),
   };
@@ -1377,7 +1376,7 @@ export function safeHarnessSourceRef(ref) {
 /**
  * Run a lifecycle event's hooks for every active capability. Env contract:
  * OATS_EVENT/OATS_INSTANCE/OATS_HOME/OATS_AGENT/OATS_CONTEXT/OATS_LEVEL/OATS_SETTINGS/OATS_META,
- * plus the team/workspace facts (teamEnv: OATS_TEAM_SCOPE/_ID/_LABEL, OATS_WORKSPACE_NAME/_KEY);
+ * plus the team/workspace facts (teamEnv: OATS_TEAM_SCOPE, OATS_DEFAULT_TEAM*, OATS_TEAMS, OATS_WORKSPACE_NAME/_KEY);
  * cwd = the instance home. A hook may print JSON { meta, brief, warning, launch, env } — meta
  * is persisted per capability in instance.json (and fed back as OATS_META at retire), brief
  * is added to TASK.md, warning surfaces in the spawn result; launch maps harness → extra
@@ -1482,37 +1481,22 @@ export function instanceSoulDir(home, meta = undefined) {
   return typeof meta?.soulDir === "string" && isAbsolute(meta.soulDir) ? meta.soulDir : undefined;
 }
 
-/** The team facts a lifecycle hook receives (workspace model only, lead decision
- * c3-7): the team SCOPE is the deployment directory, the team ID is the messaging
- * slot's merged payload `team` (workspace base ⊕ soul ⊕ host ⊕ spawn; no byTeam entry
- * is merged since teams amendment K): the workspace's default team if one is set; empty = the
- * provider's default (for oats.aweb, the root's active team). The provider also gets
- * the soul's primary team LABEL and the workspace's name and canonical key, so it can
- * derive the workspace's default team; each label's mapped payload is in
- * OATS_TEAMS.
- * OATS_TEAM_NAME (the 0.25 `team:` block's name) is always empty, so an ambient
- * value never reaches a hook. Human decision 2026-09-24 (messaging default).
+/** The team and workspace facts a lifecycle hook, command or provider check receives (workspace
+ * model only, lead decision c3-7): OATS_TEAM_SCOPE is the deployment directory; OATS_WORKSPACE_NAME /
+ * _KEY the workspace's name and canonical key; OATS_TEAM_NAME (the 0.25 `team:` block's name) is always
+ * empty, so an ambient value never reaches a hook.
  *
- * Teams contract 2026-09-25 (decision 4): `resolved.teams` is the ELIGIBLE teams,
- * `[{ label, team, mapped, payload }]` in soul order. OATS_TEAM_LABELS is their
- * labels comma-joined and OATS_TEAMS their JSON (`[]` = no label: the workspace's default team only).
- * Both are empty when the teams are not known (a home spawned before 0.26.0 whose
- * workspace cannot be read now) — empty means "unknown", never "none".
- * OATS_TEAMS_SOURCE says where the list came from: `live` (the workspace read now,
- * or a fresh resolution) or `recorded` (the spawn-time list, when a live read could
- * not answer or was not made); empty with OATS_TEAMS. A provider LEAVES a joined
- * team only on a `live` list — a recorded one lacks teams mapped since the spawn. */
+ * Team model v2 (docs/desktop-cli-api.md, The provider environment): `resolved.teams` are the soul's
+ * TeamRows here and `resolved.defaultTeam` its DefaultTeam; teamsEnv sets OATS_DEFAULT_TEAM(_ID,_FROM),
+ * OATS_TEAMS (mapped rows only) and OATS_TEAMS_SOURCE (`live`: the workspace + oats-local.yaml read now,
+ * or a fresh resolution; `recorded`: the spawn-time record). A provider LEAVES a joined team only on a
+ * `live` list. Teams not known (`resolved.teams` not an array): every team name unset. */
 export function teamEnv(resolved) {
   const ws = resolved?.workspace && typeof resolved.workspace === "object" ? resolved.workspace : {};
-  const messaging = ws.slots?.messaging;
-  const payload = messaging ? resolved.payloads?.[messaging] : null;
-  const teamId = payload && typeof payload === "object" && typeof payload.team === "string" ? payload.team : "";
+  const known = Array.isArray(resolved?.teams);
   return {
-    OATS_TEAM_NAME: "", OATS_TEAM_ID: teamId, OATS_TEAM_SCOPE: typeof ws.deployment === "string" ? ws.deployment : "",
-    OATS_TEAM_LABEL: typeof ws.team === "string" ? ws.team : "",
-    OATS_TEAM_LABELS: Array.isArray(resolved?.teams) ? resolved.teams.map((t) => t.label).join(",") : "",
-    OATS_TEAMS: Array.isArray(resolved?.teams) ? JSON.stringify(resolved.teams) : "",
-    OATS_TEAMS_SOURCE: Array.isArray(resolved?.teams) && (resolved.teamsSource === "live" || resolved.teamsSource === "recorded") ? resolved.teamsSource : "",
+    OATS_TEAM_NAME: "", OATS_TEAM_SCOPE: typeof ws.deployment === "string" ? ws.deployment : "",
+    ...teamsEnv(known ? { teams: resolved.teams, defaultTeam: resolved.defaultTeam ?? null, source: resolved.teamsSource } : null),
     OATS_WORKSPACE_NAME: typeof ws.name === "string" ? ws.name : "", OATS_WORKSPACE_KEY: typeof ws.key === "string" ? ws.key : "",
   };
 }
@@ -1881,7 +1865,9 @@ export function resolveClaudeBinary(contextDir) {
 export function modelFromOf(modelSource, { at = "spawn", prior = null } = {}) {
   if (typeof modelSource !== "string") return prior ?? null;
   if (modelSource === "explicit") return at;
-  if (modelSource === "soul default") return "soul";
+  if (modelSource === "soul default" || modelSource === "soul preference") return "soul";
+  if (modelSource === "local preference") return "local";
+  if (modelSource === "local-default preference") return "local-default";
   if (modelSource.startsWith("launch-config ")) return "launch-config";
   if (modelSource === "recorded") return prior ?? null;
   if (modelSource.startsWith("native default")) return "harness-default";
@@ -2096,7 +2082,7 @@ export function missingLaunchEnvRefs(configEnv, env = process.env) {
  *  frozen model on the same harness, else the harness's native default. */
 /** Sentinel a caller passes as `model` to mean "the harness's own default, not the configured/soul preference". */
 export const NATIVE_DEFAULT_MODEL = "@native-default";
-export function resolveLaunchSelection({ launchConfigs = {}, agent, frozen, selection = {} }) {
+export function resolveLaunchSelection({ launchConfigs = {}, agent, frozen, selection = {}, preference = null }) {
   const bad = (code, msg) => { throw oatsError(code, msg); };
   let wanted = selection.launchConfig;
   let config = null;
@@ -2116,7 +2102,9 @@ export function resolveLaunchSelection({ launchConfigs = {}, agent, frozen, sele
     config = launchConfigs[wanted];
     if (selection.harness && selection.harness !== config.harness) bad("E_LAUNCH_CONFIG_MISMATCH", `launch configuration ${wanted} starts ${config.harness}; --harness ${selection.harness} disagrees with it (select another configuration, or --launch-config none with --harness)`);
   }
-  const harness = config?.harness || selection.harness || (frozen ? frozen.harness : agent?.harness || "pi");
+  // A launch preference (feature launch-preference: an inline or soul {harness, model}) stands where the
+  // host default would: below the flags and a selected configuration.
+  const harness = config?.harness || selection.harness || (frozen ? frozen.harness : preference?.harness || agent?.harness || "pi");
   if (!LAUNCH_HARNESSES.includes(harness)) bad("E_UNSUPPORTED_HARNESS", `unknown harness "${harness}" (pi|claude|codex)`);
   let model, modelSource;
   // K6: an EXPLICIT "use the harness's native default" is distinct from an
@@ -2131,6 +2119,10 @@ export function resolveLaunchSelection({ launchConfigs = {}, agent, frozen, sele
   } else if (config?.model) {
     model = config.frozen ? config.model : resolveModelPreference(config.model, harness); modelSource = config.frozen ? "recorded" : `launch-config ${config.name}`;
     if (!model) bad("E_MODEL_UNKNOWN", `launch configuration ${config.name} names model ${JSON.stringify(config.model)}, which has no entry usable by harness ${harness}`);
+  } else if (preference && preference.harness === harness) {
+    // A preference is a unit: its model, or the harness's own — never a lower layer's.
+    model = preference.model ? resolveModelPreference(preference.model, harness) : ""; modelSource = model ? `${preference.from} preference` : "native default";
+    if (preference.model && !model) bad("E_MODEL_UNKNOWN", `the ${preference.from} launch preference names model ${JSON.stringify(preference.model)}, which has no entry usable by harness ${harness}`);
   } else if (frozen) {
     if (frozen.harness === harness) { model = frozen.model || ""; modelSource = model ? "recorded" : "native default"; }
     else { model = ""; modelSource = "native default (harness changed)"; }
@@ -2141,6 +2133,50 @@ export function resolveLaunchSelection({ launchConfigs = {}, agent, frozen, sele
   } else { model = resolveModelPreference(agent?.model || "", harness); modelSource = model ? "soul default" : "native default"; }
   return { config, harness, model, modelSource, configuredYolo: config?.yolo };
 }
+/** A home's launch layers now (feature launch-preference; --reselect-launch and inspect's launchCurrent): its
+ *  RECORDED soul's launch (the soul copy it runs) and its deployment's oats-local.yaml souls.launch. */
+export function homeLaunchLayers(realHome, meta) {
+  const deployment = dirname(dirname(dirname(dirname(realHome))));
+  const found = loadLocal(deployment);
+  if (!found.path || resolve(dirname(found.path)) !== resolve(deployment)) throw oatsError("E_LOCAL_MISSING", `${deployment} has no oats-local.yaml: --reselect-launch reads its souls.launch`);
+  const soul = isPlainObject(meta?.workspace?.soul) ? meta.workspace.soul : {};
+  const soulDir = instanceSoulDir(realHome, meta);
+  const file = soulDir ? join(soulDir, "soul.yaml") : null;
+  const definition = file && existsSync(file) ? withConfigFile(file, () => parseYamlNested(readFileSync(file, "utf8"))) : null;
+  const key = soul.package && typeof soul.qualifiedName === "string" ? soul.qualifiedName : meta.agent;
+  return launchLayers({ definition, entry: { repoKey: soul.repoKey ?? null, path: typeof soul.path === "string" ? soul.path : null, package: soul.package?.id ?? null }, key, local: found.local });
+}
+/** A NEW launch selection (a spawn, or a start/restart that reselects) from the flags and the launch
+ *  layers (lib/launch-preference.mjs). → { launchSelection (resolveLaunchSelection's), launchChoice:
+ *  { from, at, declared } }. A configuration a layer names but the host lacks is E_LAUNCH_CONFIG_UNKNOWN
+ *  naming the layer. Never reads a frozen recipe. */
+export function selectNewLaunch({ launchConfigs = {}, agent, flags = {}, layers = null }) {
+  const choice = selectionFrom({ flags, layers });
+  const named = choice.from !== "flag" && choice.selection.launchConfig !== undefined && choice.selection.launchConfig !== "none" ? choice.selection.launchConfig : null;
+  if (named !== null && !Object.hasOwn(launchConfigs, named)) throw launchConfigUnknown({ name: named, from: choice.from, at: choice.at });
+  const launchSelection = resolveLaunchSelection({ launchConfigs, agent: layers ? {} : agent, selection: choice.selection, preference: choice.preference });
+  return { launchSelection, launchChoice: { from: choice.from, at: choice.at, declared: layers?.declared ?? null } };
+}
+/** The `Launch` report (feature launch-preference) a spawn with no flags would decide HERE, for listings
+ *  (`oats souls`, `inspect --soul`): the same layers as selectNewLaunch, but no model catalogue is probed
+ *  (`model` is the configured id) and a spawn's refusal becomes `problem` {code, message, fix}. `contextDir`
+ *  is the deployment (where a harness executable resolves). */
+export function launchReportFor({ layers, launchConfigs = {}, contextDir }) {
+  const choice = selectionFrom({ layers });
+  const report = (harness, model, launchConfig, problem = null) => launchReport({ declared: layers?.declared ?? null, harness, model, launchConfig, from: choice.from, at: choice.at, problem });
+  let harness = "pi", model = null, config = null;
+  if (choice.selection.launchConfig !== undefined && choice.selection.launchConfig !== "none") {
+    // An unknown configuration launches nothing (`problem`); `effective` stays a real launch — the host
+    // default — so a reader's closed decoder never meets a null harness.
+    const name = choice.selection.launchConfig;
+    if (!Object.hasOwn(launchConfigs, name)) { const e = launchConfigUnknown({ name, from: choice.from, at: choice.at }); return report("pi", null, null, { code: e.code, message: e.message, fix: `declare launch configuration ${name} (oats launch-config set), or change oats-local.yaml souls.launch` }); }
+    config = launchConfigs[name]; harness = config.harness; model = typeof config.model === "string" && config.model ? config.model : null;
+  } else if (choice.preference) { harness = choice.preference.harness; model = choice.preference.model ?? null; }
+  const exe = resolveLaunchExecutable({ harness, declared: config?.executable, declaringDir: config?.source, contextDir });
+  if (!exe.path && !config?.executable) { const e = harnessUnavailable({ harness, from: choice.from, at: choice.at, why: exe.missing }); return report(harness, model, config?.name, { code: e.code, message: e.message, fix: e.details.fix }); }
+  if (!exe.path) return report(harness, model, config.name, { code: "E_LAUNCH_EXECUTABLE", message: `launch configuration ${config.name}: ${exe.missing}`, fix: `fix the executable of launch configuration ${config.name} (oats launch-config set)` });
+  return report(harness, model, config?.name);
+}
 /** The pane environment carrying each reference's value under a
  *  kernel-owned alias (OATS_LAUNCH_REF_<NAME>), which no configuration can
  *  name: the command says NAME="$OATS_LAUNCH_REF_NAME", so no source
@@ -2245,7 +2281,7 @@ function requirementsWithArgsMessage(harness, providers, config) {
  *  collects every failed check into `preflight` instead of throwing. A home
  *  that records no launch recipe (an earlier kernel spawned it) is not planned:
  *  E_LAUNCH_LEGACY, re-spawn it from the deployment. */
-export function planLaunch({ home, instance, meta, contextDir, agentLike, selection = {}, launchConfigs, resolvedCfg, env = process.env, preview = false, assertRoots }) {
+export function planLaunch({ home, instance, meta, contextDir, agentLike, selection = {}, launchConfigs, resolvedCfg, env = process.env, preview = false, assertRoots, reselect = null }) {
   assertRoots?.();
   const problems = [];
   const fail = (check, code, detail) => { if (!preview) throw oatsError(code, detail); problems.push({ check, ok: false, detail, code }); };
@@ -2256,13 +2292,27 @@ export function planLaunch({ home, instance, meta, contextDir, agentLike, select
   // The home's deployment declares the launch configurations (its oats-local.yaml,
   // found walking up from the home) — never the context directory, which may be a
   // member clone outside the deployment.
-  const chosen = resolveLaunchSelection({ launchConfigs: launchConfigs || (home ? launchConfigsAt(home) : resolvedCfg?.launchConfigs) || {}, agent: agentLike, frozen, selection });
+  const scopeConfigs = launchConfigs || (home ? launchConfigsAt(home) : resolvedCfg?.launchConfigs) || {};
+  // A NEW selection (feature launch-preference) — `reselect` (the home's launch layers, --reselect-launch)
+  // or explicit --launch-config / --harness — records which layer decided it (`launchChoice`); otherwise
+  // the recorded launch stays frozen (launchChoice null).
+  let chosen, launchChoice = null;
+  if (reselect) ({ launchSelection: chosen, launchChoice } = selectNewLaunch({ launchConfigs: scopeConfigs, agent: {}, flags: { launchConfig: selection.launchConfig, harness: selection.harness, model: selection.model }, layers: reselect }));
+  else {
+    chosen = resolveLaunchSelection({ launchConfigs: scopeConfigs, agent: agentLike, frozen, selection });
+    if (selection.launchConfig !== undefined || selection.harness !== undefined) launchChoice = { from: "flag", at: null, declared: meta?.launchDeclared ?? null };
+  }
   const { config, harness, model, modelSource } = chosen;
   const yolo = resolveYolo(selection.yolo ?? chosen.configuredYolo ?? (frozen ? frozen.yolo : agentLike?.yolo ?? resolvedCfg?.yolo));
   const executable = config?.frozen
     ? { path: config.executablePath, declared: frozen.executableDeclared ?? null, resolvedFrom: frozen.executableResolvedFrom || "recorded", missing: existsSync(config.executablePath) ? undefined : `${config.executablePath} (recorded) does not exist` }
     : resolveLaunchExecutable({ harness, declared: config?.executable, declaringDir: config?.source, contextDir });
-  const exeProblem = executable.path ? checkLaunchExecutable(executable.path) : executable.missing;
+  if (!executable.path && !config?.executable && launchChoice) {
+    const e = harnessUnavailable({ harness, from: launchChoice.from, at: launchChoice.at, why: executable.missing });
+    if (!preview) throw e;
+    problems.push({ check: "executable", ok: false, detail: e.message, code: e.code });
+  }
+  const exeProblem = executable.path ? checkLaunchExecutable(executable.path) : !config?.executable && launchChoice ? null : executable.missing;
   if (exeProblem) fail("executable", "E_LAUNCH_EXECUTABLE", `launch configuration ${config?.name || "(harness default)"}: ${exeProblem}`); else problems.push({ check: "executable", ok: true, detail: `${executable.path} (${executable.resolvedFrom})` });
   // Capability contributions: recorded at spawn with provenance; a harness
   // switch needs the new harness's launch args from the same capabilities.
@@ -2330,7 +2380,7 @@ export function planLaunch({ home, instance, meta, contextDir, agentLike, select
   const inst = instance || meta?.instance || basename(home);
   const command = renderLaunchRecipe(recipe, { home, instance: inst });
   const selectionSource = frozen ? (config?.frozen || (!config && !selection.launchConfig && !selection.harness) ? "frozen" : "config") : "config";
-  return { recipe, command, harness, model: model || undefined, modelSource, yolo, config, executable, preflight: problems, ok: problems.every((c) => c.ok), selectionSource, frozen, ...(hooks.meta ? { hookMeta: hooks.meta } : {}) };
+  return { recipe, command, harness, model: model || undefined, modelSource, yolo, config, executable, preflight: problems, ok: problems.every((c) => c.ok), selectionSource, frozen, launchChoice, warnings: hooks.warnings || [], ...(hooks.meta ? { hookMeta: hooks.meta } : {}) };
 }
 /** The environment a planned launch runs under: the host's base, the
  *  capabilities' validated env, the configuration's literals and its
@@ -2429,8 +2479,10 @@ function* spawnBody(root, agent, o = {}) {
   const preflightStarted = Date.now(), preflightBudgetMs = o.preview === true ? (Number(process.env.OATS_PREVIEW_PREFLIGHT_BUDGET_MS) || 20000) : undefined;
   let preflight = { status: "complete", budgetMs: preflightBudgetMs ?? null };
   if (o.preview === true) previewPreflightBudget = { deadline: preflightStarted + preflightBudgetMs };
-  let launchSelection;
-  try { launchSelection = resolveLaunchSelection({ launchConfigs: launchConfigsAt(root), agent, selection: { launchConfig: o.launchConfig, harness: o.harness, model: o.model } }); }
+  // Feature launch-preference: the flags, else the machine's souls.launch, else the soul's own launch,
+  // else the host default — `launchChoice` says which layer decided (instance.json launchFrom/launchAt).
+  let launchSelection, launchChoice;
+  try { ({ launchSelection, launchChoice } = selectNewLaunch({ launchConfigs: launchConfigsAt(root), agent, flags: { launchConfig: o.launchConfig, harness: o.harness, model: o.model }, layers: o.prepared.launch })); }
   catch (e) { previewPreflightBudget = null; throw e; }
   const launchConfig = launchSelection.config;
   const harness = launchSelection.harness;
@@ -2781,7 +2833,10 @@ function* spawnBody(root, agent, o = {}) {
 
   // Prerequisites must fail before creating a home, worktree, or identity.
   const executable = resolveLaunchExecutable({ harness, declared: launchConfig?.executable, declaringDir: launchConfig?.source, contextDir: repoAbs });
-  if (!executable.path) throw new Error(executable.missing);
+  // No executable for the chosen harness (none declared by a configuration): E_HARNESS_UNAVAILABLE names the
+  // layer that chose it and the fix. Never a fallback to another harness.
+  if (!executable.path && !launchConfig?.executable) { previewPreflightBudget = null; throw harnessUnavailable({ harness, from: launchChoice.from, at: launchChoice.at, why: executable.missing }); }
+  if (!executable.path) throw oatsError("E_LAUNCH_EXECUTABLE", `launch configuration ${launchConfig.name}: ${executable.missing}`);
   { const bad = checkLaunchExecutable(executable.path); if (bad) throw oatsError("E_LAUNCH_EXECUTABLE", `launch configuration ${launchConfig?.name || "(harness default)"}: ${bad}`); }
   const bin = executable.path;
   const missingRefs = missingLaunchEnvRefs(launchConfig?.env || {}, process.env);
@@ -2848,24 +2903,24 @@ function* spawnBody(root, agent, o = {}) {
     // R5 (0.25.2, decision 14): the preview shows the provider payloads the apply
     // will record — `providers` is the --provider map exactly as parsed (what the
     // operator typed; prepareInstance keeps it on prepared.spawn.providers) and
-    // `settings.<cap>` is the MERGED payload per module (soul ⊕ workspace byTeam ⊕
+    // `settings.<cap>` is the MERGED payload per module (workspace ⊕ soul ⊕
     // local.settings ⊕ --provider), i.e. what the provider receives. Reserved and
     // poison keys were refused by resolveSoul before this point (E_WORKSPACE_SCHEMA).
     const preparedProviders = structuredClone(o.prepared.spawn?.providers && typeof o.prepared.spawn.providers === "object" ? o.prepared.spawn.providers : {});
     // Addendum 5: where each leaf of `settings.<cap>` came from (JSON pointer → { kind, at }):
-    // manifest-default | workspace | soul | host | spawn, the last layer that set it (no byTeam
-    // entry is merged since teams amendment K, so no `workspace-team` origin appears).
+    // manifest-default | workspace | soul | host | spawn, the last layer that set it.
     const preparedSettingsOrigins = Object.fromEntries(o.prepared.resolution.modules.map((m) => [m.name, structuredClone(o.prepared.resolution.payloadOrigins?.[m.name] ?? {})]));
     const preparedSettings = Object.fromEntries(o.prepared.resolution.modules.map((m) => [m.name, structuredClone(o.prepared.resolution.payloads?.[m.name] && typeof o.prepared.resolution.payloads[m.name] === "object" ? o.prepared.resolution.payloads[m.name] : {})]));
     return deliver({
-      // Teams contract (item 7): the ELIGIBLE teams (one per soul label, primary first) — the choice a
-      // Desktop offers before anything is minted; joining is the messaging provider's explicit act.
-      ...{ modules: o.prepared.preview ?? null, team: o.prepared.soulEntry?.team ?? null, teams: structuredClone(o.prepared.resolution.teams ?? []), resolution: o.prepared.resolution.revision, declRevision: o.prepared.resolution.declRevision ?? null, payloadRevision: o.prepared.resolution.payloadRevision ?? null, workspace: o.prepared.discovery?.key ?? null, standalone: o.prepared.discovery?.standalone === true, providers: preparedProviders, settings: preparedSettings, settingsOrigins: preparedSettingsOrigins },
+      // Team model v2: the soul's teams here (unmapped rows included) and its default — the choice a
+      // Desktop offers before anything is minted; joining any but the default is the provider's explicit act.
+      ...{ modules: o.prepared.preview ?? null, teams: structuredClone(o.prepared.resolution.teams ?? []), defaultTeam: structuredClone(o.prepared.resolution.defaultTeam ?? null), resolution: o.prepared.resolution.revision, declRevision: o.prepared.resolution.declRevision ?? null, payloadRevision: o.prepared.resolution.payloadRevision ?? null, workspace: o.prepared.discovery?.key ?? null, standalone: o.prepared.discovery?.standalone === true, providers: preparedProviders, settings: preparedSettings, settingsOrigins: preparedSettingsOrigins },
       spawnPreviewApi: 2, preview: true, agent: agent.name, kind: agent.kind || "persistent", instance, home, repo: repoAbs, work,
       subject: o.subject ?? { soul: agent.name, agentsRoot: root, context: null },
       decision, preflight,
       backendStatus: launch ? { name: backend, installed: !!which(backend), started: false } : null,
       harness, model: model || null, modelSource: launchSelection.modelSource ?? null, launchConfig: launchConfig?.name ?? null, yolo, backend,
+      launch: launchReport({ declared: launchChoice.declared, harness, model, launchConfig: launchConfig?.name, from: launchChoice.from, at: launchChoice.at }),
       branch: plannedBranch, base: plannedBase, worktree: work === "worktree" ? join(home, "work") : null,
       relation: relation || null, parentInstance: parentInstance && parentInstance !== instance ? parentInstance : null,
       policy: { childSpawns: ownChildPolicy }, executable: bin, capabilities: preparedCapabilities,
@@ -3427,6 +3482,8 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
     const meta = {
       agent: agent.name, kind: agent.kind || "persistent", instance, home, soulDir: homeSoulTarget,
       repo: repoAbs, work, branch, harness, model: model || undefined, modelFrom: modelFromOf(launchSelection.modelSource, { at: "spawn" }) ?? undefined,
+      // Feature launch-preference: the layer that decided this launch, and the soul's own preference then.
+      launchFrom: launchChoice.from, launchAt: launchChoice.at, launchDeclared: launchChoice.declared,
       ...(yolo !== undefined ? { yolo } : {}),
       parentInstance: parentInstance && parentInstance !== instance ? parentInstance : undefined,
       siblingInstance: siblingInstance && siblingInstance !== instance ? siblingInstance : undefined,
@@ -3503,11 +3560,13 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
       try { const prior = JSON.parse(readFileSync(join(home, "instance.json"), "utf8")); if (prior.modules) meta.modules = prior.modules; if (prior.providers) meta.providers = prior.providers; } catch { /* materialize wrote it; absent means nothing to carry */ }
       // M5/3a: the workspace's name and the deployment directory are recorded, so a home
       // answers them (inspect/operation run --home, OATS_WORKSPACE_NAME) without discovery.
-      meta.workspace = { key: o.prepared.discovery?.key ?? null, name: o.prepared.discovery?.workspace?.name ?? null, deployment: o.prepared.deployment ?? null, commit: o.prepared.discovery?.commit ?? null, resolution: o.prepared.resolution.revision, standalone: o.prepared.discovery?.standalone === true, soul: { id: preparedSoulIdOf(o.prepared.soulEntry), repoKey: o.prepared.soulEntry.repoKey, commit: o.prepared.soulEntry.commit, team: o.prepared.soulEntry.team ?? null, labels: [...(o.prepared.soulEntry.labels ?? (o.prepared.soulEntry.team ? [o.prepared.soulEntry.team] : []))], ...(typeof o.prepared.soulEntry.package === "string" ? { name: o.prepared.soulEntry.name, qualifiedName: o.prepared.soulEntry.qualifiedName, package: { id: o.prepared.soulEntry.package, version: o.prepared.soulEntry.version, commit: o.prepared.soulEntry.commit, digest: o.prepared.soulEntry.digest, path: o.prepared.soulEntry.path } } : {}) }, layers: layerRows(o.prepared.resolution) };
-      // Teams contract (decision 6): the eligible teams at spawn, recorded as EVIDENCE beside
-      // `providers` (never inside that capability-keyed map). A home's hooks and operations get
-      // the LIVE set (liveTeams); this is what they fall back to when discovery cannot answer.
-      meta.teams = structuredClone(o.prepared.resolution.teams ?? []);
+      meta.workspace = { key: o.prepared.discovery?.key ?? null, name: o.prepared.discovery?.workspace?.name ?? null, deployment: o.prepared.deployment ?? null, commit: o.prepared.discovery?.commit ?? null, resolution: o.prepared.resolution.revision, standalone: o.prepared.discovery?.standalone === true, soul: { id: preparedSoulIdOf(o.prepared.soulEntry), repoKey: o.prepared.soulEntry.repoKey, commit: o.prepared.soulEntry.commit, ...(typeof o.prepared.soulEntry.package === "string" ? { name: o.prepared.soulEntry.name, qualifiedName: o.prepared.soulEntry.qualifiedName, package: { id: o.prepared.soulEntry.package, version: o.prepared.soulEntry.version, commit: o.prepared.soulEntry.commit, digest: o.prepared.soulEntry.digest, path: o.prepared.soulEntry.path } } : {}) }, layers: layerRows(o.prepared.resolution) };
+      // Team model v2: the teams at spawn, exactly as the providers received them (OATS_TEAMS: mapped
+      // rows only) and the default, recorded as EVIDENCE beside `providers` (never inside that
+      // capability-keyed map). A home's hooks and operations get the LIVE set (liveTeams); this is
+      // what they fall back to when the workspace cannot answer.
+      meta.teams = envRows(o.prepared.resolution.teams ?? []);
+      meta.defaultTeam = structuredClone(o.prepared.resolution.defaultTeam ?? null);
     }
     const spawnWarnings = warnings;
 
@@ -4202,6 +4261,77 @@ export function inspectInstanceSession(home) {
  *  there after the grace is reported still running, nothing is killed harder.
  *  A no-launch or already-idle instance is a no-op that says so. */
 function tmuxServerLost(e) { return /no server running on |(?:error connecting to|failed to connect to) .*(?:No such file or directory|Connection refused)/i.test(String(e.stderr ?? e.message ?? "")); }
+/**
+ * The live processes (other than this one and its children) whose working
+ * directory is inside `home`: `lsof -a -d cwd` over the host, one call.
+ * → { ok: true, processes: [{pid, command}] } | { ok: false, error } (the scan
+ * could not run: a caller must treat that as unknown, never as none).
+ */
+export function processesInHome(home, io) {
+  let out;
+  try { out = (io?.exec || execFileSync)("lsof", ["-a", "-d", "cwd", "-F", "pRcn", "-w"], { encoding: "utf8", timeout: 20000, maxBuffer: 16 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] }); }
+  catch (e) {
+    // lsof exits 1 with a full listing when some process could not be read; only no output is a failed scan.
+    if (typeof e?.stdout === "string" && /^p\d+$/m.test(e.stdout)) out = e.stdout;
+    else return { ok: false, error: e?.code === "ENOENT" ? "lsof is not on PATH" : String(e?.stderr || e?.message || "lsof failed").trim().split("\n")[0] };
+  }
+  const realHome = realPathOrNearest(home);
+  const processes = [];
+  let cur = {};
+  for (const line of String(out).split("\n")) {
+    const tag = line[0], value = line.slice(1);
+    if (tag === "p") cur = { pid: Number(value) };
+    else if (tag === "R") cur.ppid = Number(value);
+    else if (tag === "c") cur.command = value;
+    else if (tag === "n" && cur.pid && cur.pid !== process.pid && cur.ppid !== process.pid) {
+      const cwd = realPathOrNearest(value);
+      if (cwd === realHome || cwd.startsWith(`${realHome}/`)) processes.push({ pid: cur.pid, command: cur.command ?? "?" });
+    }
+  }
+  return { ok: true, processes };
+}
+
+/**
+ * A home without a valid independent session receipt (spawned before 0.25.9)
+ * has no endpoint OATS may quiesce. It can still be observed ABSENT, which is
+ * all a retirement needs: `{ absent: true, backend, note }` only when
+ * instance.json records no launch, or the recorded tmux server is gone, or it
+ * no longer has the recorded window and no pane on it works in this home —
+ * AND no live process on the host works in the home (a harness started by
+ * hand on another server is invisible to the recorded endpoint).
+ * Anything else (the window is there, a pane or a process works in the home,
+ * the process scan cannot run, a Herdr target, a launch without an endpoint,
+ * tmux failing otherwise) is `{ absent: false, note }`: live or ambiguous,
+ * never killed on mutable metadata.
+ */
+export function observeSessionWithoutReceipt(home, meta, io) {
+  const recorded = recordedSessionAbsence(home, meta, io);
+  if (!recorded.absent) return recorded;
+  const scan = processesInHome(home, io);
+  if (!scan.ok) return { absent: false, backend: recorded.backend, note: `could not scan for a process working in this home (${scan.error})` };
+  if (scan.processes.length) return { absent: false, backend: recorded.backend, note: `a process works in this home (${scan.processes.slice(0, 5).map((p) => `pid ${p.pid} ${p.command}`).join(", ")}${scan.processes.length > 5 ? `, and ${scan.processes.length - 5} more` : ""}); stop it, then retire` };
+  return recorded;
+}
+function recordedSessionAbsence(home, meta, io) {
+  const tmux = meta?.tmux;
+  if (meta?.sessionTarget) return { absent: false, backend: "herdr", note: "instance.json records a Herdr session, which cannot be observed without the receipt" };
+  // A --no-launch home keeps its planned tmux names with `launched: false`: nothing was started there.
+  if (meta?.launched !== true) return { absent: true, backend: null, note: "no session receipt (a home from before 0.25.9); instance.json records no launch" };
+  if (!tmux) return { absent: false, backend: null, note: "instance.json records a launch but no session endpoint" };
+  if (![tmux.session, tmux.window, tmux.socket].every((v) => typeof v === "string" && v.length > 0)) return { absent: false, backend: "tmux", note: "instance.json records an incomplete tmux endpoint" };
+  const where = `${tmux.session}:${tmux.window} on ${tmux.socket}`;
+  let rows;
+  try { rows = tmuxOn(tmux.socket, ["list-panes", "-a", "-F", "#{session_name}\t#{window_name}\t#{pane_current_path}"], io).split("\n").filter(Boolean).map((l) => l.split("\t")); }
+  catch (e) {
+    if (tmuxServerLost(e)) return { absent: true, backend: "tmux", note: `no session receipt (a home from before 0.25.9); the recorded tmux server ${tmux.socket} is not running` };
+    return { absent: false, backend: "tmux", note: `tmux could not list ${tmux.socket}: ${String(e.stderr ?? e.message ?? "").trim() || "tmux failed"}` };
+  }
+  if (rows.some(([s, w]) => s === tmux.session && w === tmux.window)) return { absent: false, backend: "tmux", note: `the recorded window ${where} is still present` };
+  const realHome = realPathOrNearest(home);
+  const inHome = rows.find(([, , cwd]) => { const p = cwd ? realPathOrNearest(cwd) : ""; return p === realHome || p.startsWith(`${realHome}/`); });
+  if (inHome) return { absent: false, backend: "tmux", note: `a tmux pane (${inHome[0]}:${inHome[1]}) on ${tmux.socket} works in this home` };
+  return { absent: true, backend: "tmux", note: `no session receipt (a home from before 0.25.9); the recorded window ${where} is gone` };
+}
 export function stopInstanceSession(home, o = {}) {
   if (typeof home !== "string" || !isAbsolute(home)) throw oatsError("E_BAD_ARGS", "session stop needs an absolute instance home");
   if (o.graceMs !== undefined && (!Number.isSafeInteger(o.graceMs) || o.graceMs < 1 || o.graceMs > 300000)) throw oatsError("E_BAD_ARGS", "stop grace must be 1-300000 ms");
@@ -4464,6 +4594,7 @@ export function prepareLaunchHooks({ frozen, harness, resolvedCfg, home, meta, c
   const contributions = (frozen.hooks?.contributions || []).map((c) => ({ ...c }));
   const env = { ...(frozen.hooks?.env || {}) };
   const refreshed = [];
+  let warnings = [];
   // The providers that took part in this home's launch are the CAPTURED ones
   // (its recorded contributions). Each is resolved by id through the scope's
   // current installed manifest and trust, whatever the scope's bindings say
@@ -4512,12 +4643,15 @@ export function prepareLaunchHooks({ frozen, harness, resolvedCfg, home, meta, c
     // renewed session grant, for instance — left the ORIGINAL id on record and
     // retire undid the wrong one. Carry it to the caller; the start records it.
     hookMeta = res.meta && Object.keys(res.meta).length ? res.meta : undefined;
+    // The hooks' advisory warnings go to the start's answer and events, as
+    // spawn's do; they were dropped here before 0.30.
+    warnings = [...(res.warnings || [])];
   }
   const unprepared = contributions.filter((c) => !refreshed.includes(c.capability) && c.launch && c.launch[frozen.harness] !== undefined && c.launch[harness] === undefined).map((c) => c.capability);
   if (unprepared.length) throw oatsError("E_LAUNCH_PREPARATION", `${unprepared.join(", ")} contributed ${frozen.harness} launch arguments at spawn and none for ${harness}; change that capability's setting (for example its delivery mode), or the provider must declare a launch hook; nothing was stopped`);
   const launch = {};
   for (const c of contributions) { for (const [rt, args] of Object.entries(c.launch || {})) if (args) launch[rt] = `${launch[rt] ? `${launch[rt]} ` : ""}${args}`; }
-  return { launch, env, contributions, refreshed, ...(hookMeta ? { meta: hookMeta } : {}) };
+  return { launch, env, contributions, refreshed, warnings, ...(hookMeta ? { meta: hookMeta } : {}) };
 }
 
 
@@ -4582,7 +4716,7 @@ export function startInstanceSession(home, o = {}) {
   // The independent receipt first (retire and session consult it), then the
   // mutable metadata; both tmp+rename. A failure between them is what the
   // pending receipt exists for.
-  const record = (meta, { id, backend, target, model, command, startedAt, reused, launch, harness: newHarness, yolo: newYolo, stop, nativeRecordId, hookMeta, modelFrom }, clearPending = true) => {
+  const record = (meta, { id, backend, target, model, command, startedAt, reused, launch, harness: newHarness, yolo: newYolo, stop, nativeRecordId, hookMeta, modelFrom, launchFrom, launchAt, launchDeclared }, clearPending = true) => {
     checkRoots();
     const baselinePath = retirementBaselinePath(realHome);
     let baseline;
@@ -4598,6 +4732,7 @@ export function startInstanceSession(home, o = {}) {
     if (!recorded) restarts.push({ startedAt, model: model ?? null, reused });
     const next = { ...meta, model, command, launched: true, startId: id, restarts, restartCount: (meta.restartCount || 0) + (recorded ? 0 : 1), ...(modelFrom ? { modelFrom } : {}),
       ...(launch ? { launch } : {}), ...(newHarness ? { harness: newHarness } : {}), ...(newYolo !== undefined ? { yolo: newYolo } : {}),
+      ...(launchFrom ? { launchFrom, launchAt: launchAt ?? null, launchDeclared: launchDeclared ?? null } : {}),
       // Launch-hook meta lands per capability over the spawn's record; a hook
       // that answered without meta keeps its previous entry (retire reads it).
       ...(hookMeta ? { capabilityMeta: { ...(meta.capabilityMeta || {}), ...hookMeta } } : {}) };
@@ -4605,7 +4740,7 @@ export function startInstanceSession(home, o = {}) {
     else { next.tmux = { session: target.session, window: target.window, socket: resolve(target.socket) }; delete next.sessionTarget; }
     writeJsonAtomic(metaPath, next);
     if (clearPending) { checkRoots(); rmSync(pendingPath, { force: true }); }
-    return { instance: meta.instance, agent: meta.agent, home: realHome, harness: next.harness, backend, model: model ?? null, launchConfig: next.launch?.launchConfig ?? null, yolo: next.yolo ?? null, target, startedAt, restartCount: next.restartCount, reused, ...(nativeRecordId ? { nativeRecordId } : {}), ...(stop ? { stop } : {}) };
+    return { instance: meta.instance, agent: meta.agent, home: realHome, harness: next.harness, backend, model: model ?? null, launchConfig: next.launch?.launchConfig ?? null, yolo: next.yolo ?? null, target, startedAt, restartCount: next.restartCount, reused, warnings: [], ...(nativeRecordId ? { nativeRecordId } : {}), ...(stop ? { stop } : {}) };
   };
   try { mkdirSync(lock); }
   catch (e) {
@@ -4679,9 +4814,12 @@ export function startInstanceSession(home, o = {}) {
     // model, re-rendered in place), or, under a selection, the recipe
     // re-resolved against the home's current scoped configuration. Every
     // preflight happens here, before anything is observed or stopped.
-    const selected = o.launchConfig !== undefined || o.harness !== undefined || o.yolo !== undefined;
+    // --reselect-launch (feature launch-preference): apply the home's launch layers now (souls.launch,
+    // the recorded soul's launch, the host default) instead of the frozen recipe.
+    const reselect = o.reselectLaunch === true ? homeLaunchLayers(realHome, meta) : null;
+    const selected = reselect !== null || o.launchConfig !== undefined || o.harness !== undefined || o.yolo !== undefined;
     const hasRecipe = meta.launch && typeof meta.launch === "object";
-    let launchPlan = null, explicitModelFrom = null;
+    let launchPlan = null, explicitModelFrom = null, warnings = [];
     if (selected || hasRecipe) {
       // Every start of a home with a recipe (ordinary, model-only, or under a
       // selection) goes through the one planner: recipe shape, the recorded
@@ -4689,13 +4827,18 @@ export function startInstanceSession(home, o = {}) {
       // the captured settings and current trust. A home without a recipe that
       // is asked for a selection is refused (E_LAUNCH_LEGACY).
       const context = meta.repo && existsSync(meta.repo) ? resolve(meta.repo) : dirname(dirname(dirname(dirname(realHome))));
-      // o.teams: the home's LIVE eligible teams, computed by an async caller (liveTeams) — the
-      // launch hook re-checks joined memberships against them (teams contract decision 6).
-      const resolvedCfg = resolvedFromHome(realHome, meta, { teams: o.teams, teamsSource: o.teamsSource });
+      // o.teams / o.defaultTeam: the home's LIVE teams, computed by an async caller (liveTeams) —
+      // the launch hook re-checks joined memberships against them.
+      const resolvedCfg = resolvedFromHome(realHome, meta, { teams: o.teams, defaultTeam: o.defaultTeam, teamsSource: o.teamsSource });
       let agent; try { agent = findAgent(dirname(dirname(dirname(realHome))), meta.agent); } catch { agent = undefined; }
-      const plan = planLaunch({ home: realHome, instance: meta.instance, meta, contextDir: context, agentLike: agent || { harness: meta.harness, model: meta.model, yolo: meta.yolo }, selection: { launchConfig: o.launchConfig, harness: o.harness, model: o.model, yolo: o.yolo }, resolvedCfg, env: o.env || process.env, assertRoots: checkRoots });
-      launchPlan = { recipe: plan.recipe, command: plan.command, harness: plan.harness, model: plan.model, yolo: plan.yolo, modelFrom: modelFromOf(plan.modelSource, { at: "start", prior: meta.modelFrom ?? null }), ...(plan.hookMeta ? { hookMeta: plan.hookMeta } : {}) };
+      const plan = planLaunch({ home: realHome, instance: meta.instance, meta, contextDir: context, agentLike: agent || { harness: meta.harness, model: meta.model, yolo: meta.yolo }, selection: { launchConfig: o.launchConfig, harness: o.harness, model: o.model, yolo: o.yolo }, reselect, resolvedCfg, env: o.env || process.env, assertRoots: checkRoots });
+      launchPlan = { recipe: plan.recipe, command: plan.command, harness: plan.harness, model: plan.model, yolo: plan.yolo, modelFrom: modelFromOf(plan.modelSource, { at: "start", prior: meta.modelFrom ?? null }), ...(plan.hookMeta ? { hookMeta: plan.hookMeta } : {}),
+        ...(plan.launchChoice ? { launchFrom: plan.launchChoice.from, launchAt: plan.launchChoice.at, launchDeclared: plan.launchChoice.declared } : {}) };
       command = launchPlan.command; model = launchPlan.model;
+      // The launch hooks have run: their warnings are events now, whatever
+      // the start does next, and the answer carries them.
+      warnings = plan.warnings;
+      for (const message of warnings) appendEvent(realHome, { kind: "launch-warning", data: { message } });
     } else if (o.model !== undefined && o.model !== null && String(o.model).trim() !== "") {
       const resolved = resolveModelPreference(String(o.model), harness);
       if (!resolved) throw oatsError("E_MODEL_UNKNOWN", `model preference ${JSON.stringify(o.model)} has no entry usable by harness ${harness}; give a ${harness} model id`);
@@ -4711,6 +4854,7 @@ export function startInstanceSession(home, o = {}) {
     const paneEnvExports = paneEnv.map((r) => `export ${r.name}=${shq(r.value)}; `).join("");
     checkRoots(); // launch hooks/preparation have run; no backend has been observed
     const planExtra = launchPlan ? { launch: launchPlan.recipe, harness: launchPlan.harness, yolo: launchPlan.yolo, ...(launchPlan.modelFrom ? { modelFrom: launchPlan.modelFrom } : {}),
+      ...(launchPlan.launchFrom ? { launchFrom: launchPlan.launchFrom, launchAt: launchPlan.launchAt, launchDeclared: launchPlan.launchDeclared } : {}),
       ...(launchPlan.hookMeta ? { hookMeta: launchPlan.hookMeta } : {}) } : (explicitModelFrom ? { modelFrom: explicitModelFrom } : {});
     let target = receipt.target;
     let state = { present: false, state: "not-launched" };
@@ -4810,7 +4954,7 @@ export function startInstanceSession(home, o = {}) {
     // Keep launch evidence until the command exits or the target disappears.
     // A transient child (for example cat TASK.md) is not proof that startup
     // has finished. A later start reconciles the receipt without a watcher.
-    try { return record(meta, { id, backend, target, model, command, startedAt, reused, ...planExtra, ...(stopReceipt ? { stop: stopReceipt } : {}) }, false); }
+    try { return { ...record(meta, { id, backend, target, model, command, startedAt, reused, ...planExtra, ...(stopReceipt ? { stop: stopReceipt } : {}) }, false), warnings }; }
     catch (e) {
       if (e.code && String(e.code).startsWith("E_")) throw e;
       throw oatsError("E_SESSION_START_INCOMPLETE", `${meta.instance} was started (${backend === "herdr" ? `Herdr pane ${target.paneId}` : `tmux ${target.session}:${target.window} on ${target.socket}`}) but its metadata could not be recorded: ${e.message}; the actual target is kept in ${pendingPath} and the next start adopts it instead of allocating another`);
@@ -5384,9 +5528,17 @@ export function retireInstance(root, name, o = {}) {
   let runtimeAuthority;
   if (liveMeta || quarantine) {
     runtimeAuthority = initialObservation.runtimeAuthority;
-    if (!runtimeAuthority) {
-      throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `cannot quiesce ${name}: independent runtime endpoint authority is missing or invalid`);
+    // A home without its receipt (spawned before 0.25.9) has nothing OATS may
+    // quiesce; when its session is observably absent, quiescing is vacuous and
+    // the retirement goes on (hooks, work preservation). Live or ambiguous
+    // still refuses, --force included: a harness is never left running under
+    // a removed home.
+    const unowned = runtimeAuthority ? null : observeSessionWithoutReceipt(found.home, meta);
+    if (unowned && !unowned.absent) {
+      throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `cannot quiesce ${name}: independent runtime endpoint authority is missing or invalid, and its session is not observably absent (${unowned.note}); stop that session yourself, then retire again`);
     }
+  }
+  if (runtimeAuthority) {
     const endpointAgrees = runtimeAuthority.sessionTarget
       ? !meta.tmux && ["backend", "binary", "socket", "workspaceId", "paneId", "terminalId", "protocol"].every((key) => meta.sessionTarget?.[key] === runtimeAuthority.sessionTarget[key])
       : !meta.sessionTarget && meta.tmux?.session === runtimeAuthority.tmux?.session

package/lib/instance-events.mjs

@@ -26,7 +26,7 @@ export const EVENTS_API = 2;
 const HOME_LOG = ".oats-events.jsonl";
 const MAX_BYTES = 4 * 1024 * 1024;
 
-export const EVENT_KINDS = ["spawned", "launched", "restarted", "stopped", "stop-refused", "retire-planned", "retired", "worktree-retained", "worktree-removed", "branch-deleted", "child-spawn-refused", "recomposed"];
+export const EVENT_KINDS = ["spawned", "launched", "restarted", "stopped", "stop-refused", "retire-planned", "retired", "worktree-retained", "worktree-removed", "branch-deleted", "child-spawn-refused", "launch-warning", "recomposed"];
 
 function workspaceLogPath(home) {
   // <workspace>/.agents/events/<agent>--<instance>.jsonl — deployment-private