@awebai/oats 0.31.0 → 0.32.0

package/bin/oats.mjs

@@ -19,7 +19,7 @@
  */
 import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readSync, realpathSync, rmdirSync, rmSync, writeFileSync } from "node:fs";
 import { execFileSync, spawnSync } from "node:child_process";
-import { homedir, tmpdir } from "node:os";
+import { constants as osConstants, homedir, tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { runtimeNameWarning, noteRuntimeName } from "../lib/deprecation.mjs";
@@ -28,16 +28,17 @@ import {
   LAYERS, OATS_VERSION, manifestOperations, upgradeHomeMeta,
   capabilityManifests, capabilityTrust, capabilityExecutablePath,
   officialPackageCatalog, officialCatalogFile, officialCapabilityAliases, resolvedFromHome, resolvedFromPrepared, teamEnv, isWorkspaceHome, preWorkspaceHome, isCapturedHome, capturedHomeRefusal, composeInstanceAgentsMd, parseYamlNested, withConfigFile,
-  findInstanceHome, findInstanceHomes, workspaceOf, stopInstanceSession, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, instanceSoulDir, recordedKernelBin, launchConfigsAt, launchReportFor, explicitInstanceName, retireInstance, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, defaultRepo, RELATIONS, validateLaunchConfig, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
+  findInstanceHome, findInstanceHomes, workspaceOf, stopInstanceSession, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, instanceSoulDir, recordedKernelBin, launchConfigsAt, launchReportFor, explicitInstanceName, retireInstance, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, defaultRepo, RELATIONS, validateLaunchConfig, validateLaunchConfigDefaults, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
 } from "../lib/core.mjs";
 import {
-  writeFileAtomic, LOCK_FILE, readLock, writeLock, resolvePackages, memoizedRemote,
+  writeFileAtomic, LOCK_FILE, readLock, readLockIfPresent, writeLock, resolvePackages, memoizedRemote,
   classifyPackageValue, parsePackageRequest } from "../lib/packages.mjs";
-import { loadLocal, validateWorkspace, validateLocal, discoverPackageSouls, workspaceWarnings } from "../lib/workspace.mjs";
+import { loadLocal, validateWorkspace, validateLocal, discoverPackageSouls, workspaceWarnings, memberRowByKey } from "../lib/workspace.mjs";
 import { recordedTeams, reportRows, soulKeyOf, soulTeams, teamModel } from "../lib/teams.mjs";
 import { launchLayers } from "../lib/launch-preference.mjs";
 import { parseConfigData } from "../lib/config-data.mjs";
 import * as remoteModule from "../lib/remote.mjs";
+import { activateLocalInputs, localRevision } from "../lib/local-inputs.mjs";
 import YAML from "yaml";
 import { attachArgv, checkRemote, forgetSnapshot, getServer, inspectRemote, startRemote, restartRemote, launchConfigRemote, scheduleRemote, listSnapshots, readServers, rosterGroups, routeCommand, targetOf, validateServer, writeServers, SERVERS_FILE } from "../lib/servers.mjs";
 import { spawnSync as spawnSyncProc } from "node:child_process";
@@ -367,7 +368,7 @@ async function inspectCmd() {
   if (t) {
     if (t.resolutionError) return bail(t.resolutionError.code, t.resolutionError.message, t.resolutionError.details ?? undefined);
     const doc = inspectDocument(t, { kernel: OATS_VERSION });
-    if (JSON_MODE) { jsonOk(doc); return; }
+    if (JSON_MODE) { jsonOk(withObservation(doc)); return; }
     printWorkspaceInspect(doc); return;
   }
 }
@@ -536,6 +537,7 @@ async function workspaceOperation(t, { bail, address, layer, opName }) {
   const env = { ...lp.env(mod.name, settings), OATS_OPERATION: address, OATS_CONTEXT: t.deployment, OATS_ROOT: t.agentsRoot, PI_AGENTS_ROOT: t.agentsRoot };
   if (op.context === "home") Object.assign(env, { OATS_INSTANCE: t.meta.instance, OATS_INSTANCE_HOME: t.home, OATS_HOME: t.home, PI_AGENT_INSTANCE: t.meta.instance, PI_AGENT_HOME: t.home });
   else for (const k of ["OATS_INSTANCE", "OATS_INSTANCE_HOME", "OATS_HOME", "PI_AGENT_INSTANCE", "PI_AGENT_HOME"]) delete env[k];
+  await readSession?.closeBatches(); // no idle `git cat-file --batch` child held for the provider's whole run
   const r = spawnSync("node", [abs, ...rest, ...argFlags, "--json"], { cwd, env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 16 * 1024 * 1024, timeout: OPERATION_TIMEOUT_MS, killSignal: "SIGTERM" });
   finishOperation({ r, bail, address, provider, op, argFlags, cwd, home: t.home, meta: t.meta, api: INSPECT_OPERATIONS_API });
 }
@@ -686,6 +688,7 @@ function serializeLaunchConfigs(map) {
     }
     if (e.model !== undefined) lines.push(`    model: ${yamlQuoted(e.model)}`);
     if (e.yolo !== undefined) lines.push(`    yolo: ${e.yolo}`);
+    if (e.default === true) lines.push("    default: true");
   }
   return lines.join("\n") + "\n";
 }
@@ -700,6 +703,7 @@ function normalizeLaunchConfig(e) {
     ...(e.env && Object.keys(e.env).length ? { env: Object.fromEntries(Object.keys(e.env).sort().map((n) => [n, typeof e.env[n] === "string" ? e.env[n] : { fromEnv: e.env[n].fromEnv }])) } : {}),
     ...(e.model !== undefined ? { model: e.model } : {}),
     ...(e.yolo !== undefined ? { yolo: e.yolo } : {}),
+    ...(e.default === true ? { default: true } : {}),
   };
 }
 function readLaunchConfigsModel(local) {
@@ -716,7 +720,7 @@ function readLaunchConfigsModel(local) {
  *  `set --keep-env`. */
 function publicLaunchConfig(e, extra = {}) {
   const env = Object.fromEntries(Object.keys(e.env || {}).sort().map((n) => [n, typeof e.env[n] === "string" ? { redacted: true } : { fromEnv: e.env[n].fromEnv }]));
-  return { harness: e.harness, executable: e.executable ?? null, args: [...(e.args || [])], env, model: e.model ?? null, yolo: e.yolo ?? null, ...extra };
+  return { harness: e.harness, executable: e.executable ?? null, args: [...(e.args || [])], env, model: e.model ?? null, yolo: e.yolo ?? null, default: e.default === true, ...extra };
 }
 /** The scope a launch-config command reads: --dir (or cwd), a running
  *  home's recorded context (--home), or a soul's own member context
@@ -766,7 +770,7 @@ function launchPreview(bail) {
       // (E_LAUNCH_LEGACY: re-spawn it from the deployment).
       let d;
       try { d = describeLaunchCommand(meta.command); } catch (e) { bail(e.code || "E_LAUNCH_COMMAND_UNSUPPORTED", e.message); }
-      jsonOk({ context, selected, selection: { source: "frozen-command", launchConfig: null, harness: null, model: null, yolo: null }, harness: meta.harness, model: meta.model || null, modelSource: meta.model ? "recorded" : "native default", yolo: meta.yolo ?? null, launchConfig: null, launchConfigSource: null, executable: { path: d.executable, declared: null, resolvedFrom: "recorded" }, argv: d.argv, environment: d.environment, command: redactLaunchCommand(meta.command), prompt: { kind: "task-file", file: "TASK.md" }, hooks: null, preflight: [{ check: "recipe", ok: true, detail: "frozen command; a selection is refused (E_LAUNCH_LEGACY): re-spawn it" }], ok: true });
+      jsonOk({ context, selected, selection: { source: "frozen-command", launchConfig: null, harness: null, model: null, yolo: null }, harness: meta.harness, model: meta.model || null, modelSource: meta.model ? "recorded" : "native default", yolo: meta.yolo ?? null, launchConfig: null, launchConfigSource: null, launchConfigDefault: false, executable: { path: d.executable, declared: null, resolvedFrom: "recorded" }, argv: d.argv, environment: d.environment, command: redactLaunchCommand(meta.command), prompt: { kind: "task-file", file: "TASK.md" }, hooks: null, preflight: [{ check: "recipe", ok: true, detail: "frozen command; a selection is refused (E_LAUNCH_LEGACY): re-spawn it" }], ok: true });
       return;
     }
     const agentsRoot = agentsRootOfHome(home);
@@ -788,7 +792,7 @@ function launchPreview(bail) {
   const command = renderLaunchRecipe(recipe, { home, instance, redact: true });
   const d = describeLaunchCommand(command);
   const environment = d.environment.map((e) => e.reference && recipe.env[e.name]?.fromEnv ? { name: e.name, fromEnv: recipe.env[e.name].fromEnv } : e);
-  jsonOk({ context, selected, selection: { source: plan.selectionSource, launchConfig: recipe.launchConfig, harness: sel.harness ?? null, model: sel.model ?? null, yolo: sel.yolo ?? null }, harness: plan.harness, model: recipe.model, modelSource: plan.modelSource, yolo: recipe.yolo ?? null, launchConfig: recipe.launchConfig, launchConfigSource: recipe.launchConfigSource, executable: { path: plan.executable.path, declared: plan.executable.declared ?? null, resolvedFrom: plan.executable.resolvedFrom }, argv: d.argv, environment, command, prompt: recipe.prompt, hooks: redactLaunchRecipe(recipe).hooks, preflight: plan.preflight, ok: plan.ok });
+  jsonOk({ context, selected, selection: { source: plan.selectionSource, launchConfig: recipe.launchConfig, harness: sel.harness ?? null, model: sel.model ?? null, yolo: sel.yolo ?? null }, harness: plan.harness, model: recipe.model, modelSource: plan.modelSource, yolo: recipe.yolo ?? null, launchConfig: recipe.launchConfig, launchConfigSource: recipe.launchConfigSource, launchConfigDefault: recipe.launchConfigDefault === true, executable: { path: plan.executable.path, declared: plan.executable.declared ?? null, resolvedFrom: plan.executable.resolvedFrom }, argv: d.argv, environment, command, prompt: recipe.prompt, hooks: redactLaunchRecipe(recipe).hooks, preflight: plan.preflight, ok: plan.ok });
 }
 async function launchConfigCmd() {
   const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
@@ -817,7 +821,7 @@ async function launchConfigCmd() {
     if (!configurations.length) { console.log(`No launch configurations are declared${file ? ` in ${shortPath(file)}` : ` (no oats-local.yaml in reach of ${dir})`}`); return; }
     for (const c of configurations) {
       const env = Object.entries(c.env).map(([n, v]) => v.fromEnv ? `${n}=$${v.fromEnv}` : `${n}=<redacted>`).join(" ");
-      console.log(`${c.name}: ${c.harness}${c.executable ? ` ${c.executable}` : ""}${c.args.length ? ` ${c.args.map((a) => JSON.stringify(a)).join(" ")}` : ""}${env ? ` [${env}]` : ""}${c.model ? ` model ${c.model}` : ""}${c.yolo !== null ? ` yolo ${c.yolo}` : ""}`);
+      console.log(`${c.name}: ${c.harness}${c.default ? ` (this machine's ${c.harness} default)` : ""}${c.executable ? ` ${c.executable}` : ""}${c.args.length ? ` ${c.args.map((a) => JSON.stringify(a)).join(" ")}` : ""}${env ? ` [${env}]` : ""}${c.model ? ` model ${c.model}` : ""}${c.yolo !== null ? ` yolo ${c.yolo}` : ""}`);
     }
     return;
   }
@@ -860,6 +864,8 @@ async function launchConfigCmd() {
     try { validateLaunchConfig(name, entry, `--file ${f}`); } catch (e) { bail(e.code || "E_LAUNCH_CONFIG_INVALID", e.message); }
     if (!Object.hasOwn(entry, "harness")) noteRuntimeName(`runtime in the --file definition (written as harness)`);
     model[name] = normalizeLaunchConfig(entry);
+    // One default per harness, over the file as it would be written (no automatic move).
+    try { validateLaunchConfigDefaults(model, shortPath(file)); } catch (e) { bail(e.code || "E_LAUNCH_CONFIG_INVALID", e.message, e.details); }
   }
   let next;
   try { next = replaceLaunchConfigsBlock(text, serializeLaunchConfigs(model)); } catch (e) { bail(e.code || "E_CONFIG_BROKEN", `${e.message}; nothing was written`); }
@@ -1013,11 +1019,60 @@ async function readinessCmd() {
 // remotes (lib/workspace.mjs), packages resolve to exact commits (lib/packages.mjs,
 // lock v3) and the only persisted state is `oats-lock.json` beside oats-local.yaml.
 
+/** This command's read session (lib/remote.mjs createReadSession): one per process, created at the
+ *  first remote read, closed when the command ends (the `finally` of the dispatch) and, for the
+ *  process.exit paths, on exit — no `git cat-file --batch` child outlives the command. Its git
+ *  children run as their own process groups, so a terminal's Ctrl-C no longer reaches them: a
+ *  SIGINT, SIGTERM or SIGHUP closes the session and exits (128 + the signal number), which kills them. */
+let readSession = null;
+/** The validated `--max-age` seconds (checked once at dispatch: maxAgeRefusal), null when not given. */
+let maxAgeGiven = null;
+function commandSession() {
+  if (!readSession) {
+    readSession = remoteModule.createReadSession({ maxAge: maxAgeGiven ?? 0 });
+    process.on("exit", () => readSession.closeNow());
+    for (const [signal, code] of [["SIGINT", 130], ["SIGTERM", 143], ["SIGHUP", 129]]) process.once(signal, () => {
+      readSession.closeNow();
+      // Another handler (a scheduler lock's release) exits on its own after this one.
+      if (process.listenerCount(signal) === 0) process.exit(code);
+    });
+  }
+  return readSession;
+}
+/** Which kernel command forms take --max-age: THE allow-list (docs/desktop-cli-api.md "Observation reuse").
+ *  → null when this form reads with observation reuse, else the E_BAD_ARGS message. `head` is argv before `--`. */
+const MAX_AGE_READS = "status, workspace status, souls, capabilities, inspect --soul|--home, and the read forms of teams and soul teams";
+function maxAgeRefusal(command, head) {
+  const word = (i) => (head[i] !== undefined && !head[i].startsWith("--") ? head[i] : undefined);
+  const refuse = (form) => `--max-age is not accepted by \`oats ${form}\`: only the read verbs reuse observations (${MAX_AGE_READS})`;
+  if (head.includes("--server")) return "--max-age cannot be combined with --server: observation reuse is local to this machine";
+  switch (command) {
+    case "status": case "souls": case "capabilities": case "inspect": return null;
+    case "workspace": return word(1) === "status" ? null : refuse(["workspace", word(1)].filter(Boolean).join(" "));
+    case "teams": return word(1) === undefined ? null : refuse(`teams ${word(1)}`);
+    case "soul": {
+      if (word(1) !== "teams") return refuse(["soul", word(1)].filter(Boolean).join(" "));
+      const edit = ["--add", "--remove", "--default", "--clear-default"].find((f) => head.includes(f));
+      return edit ? refuse(`soul teams ${edit}`) : null;
+    }
+    default: {
+      const sub = ["package", "schedule", "session", "trigger", "automations", "launch-config", "server", "instance", "operation", "pane"].includes(command) ? word(1) : undefined;
+      return refuse([command, sub].filter(Boolean).join(" "));
+    }
+  }
+}
+/** The observation block: the heads' oldest observedAt and reuse (the read session) and the revision of
+ *  the local configuration this command read (lib/local-inputs.mjs, recording since dispatch). */
+const observationBlock = () => ({ ...commandSession().observation(), localRevision: localRevision() });
+/** A read verb's JSON with the observation block — only when --max-age was given (0 included); without
+ *  it the document is exactly what it was before the feature (Desktop decodes closed shapes). */
+const withObservation = (doc) => (maxAgeGiven === null ? doc : { ...doc, observation: observationBlock() });
+
 /** Remote options threaded into every remote call. OATS_REMOTE_CACHE relocates
- * the content-addressed fetch cache (tests never touch ~/.cache). */
+ * the content-addressed fetch cache (tests never touch ~/.cache); `session` is the command's read session. */
 function remoteOptionsFromEnv() {
   const cacheDir = process.env.OATS_REMOTE_CACHE;
-  return cacheDir ? { cacheDir: resolve(cacheDir) } : {};
+  return { ...(cacheDir ? { cacheDir: resolve(cacheDir) } : {}), session: commandSession() };
 }
 
 /** The v2 deployment context at --dir: { dir, localPath, local, deploymentDir, remoteOptions }. */
@@ -1443,7 +1498,7 @@ async function workspaceCmd() {
     result.warnings.push({ code: "automation-trust-stale", entry, message: `oats-local.yaml automations.trust names ${entry}, which is no workspace trigger or schedule${actx.snapshot ? "" : " (no automations snapshot yet: run oats sync)"}; its member may not have synced yet` });
   }
   await workspaceStatusFacts(result, discovery, lock, ctx);
-  if (JSON_MODE) { jsonOk(result); return; }
+  if (JSON_MODE) { jsonOk(withObservation(result)); return; }
   console.log(`workspace ${workspaceName(discovery)}  (${discovery.key} @ ${short(discovery.commit)})  local ${shortPath(ctx.localPath)}\n`);
   if (standalone) console.log(`  (${standaloneNote(discovery)})\n`);
   console.log("Members:");
@@ -1533,7 +1588,7 @@ async function teamsCmd() {
     else if (sub === "default") result = V.teamsDefault(ctx, label);
   } catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_")) return bail(e.code, e.message, e.details); throw e; }
   const doc = V.teamsDocument(result ? { ...ctx, local: result.local } : ctx);
-  if (JSON_MODE) { jsonOk(result ? { ...doc, changed: result.changed } : doc); return; }
+  if (JSON_MODE) { jsonOk(result ? { ...doc, changed: result.changed } : withObservation(doc)); return; }
   if (result) console.log(result.changed ? `${sub === "add" ? `Declared team ${label}` : sub === "remove" ? `Removed team ${label}` : `The default team is now ${label}`} in ${shortPath(ctx.localPath)}` : "Nothing to change");
   console.log(`default   ${doc.defaultTeam ?? "(none)"}`);
   if (!doc.teams.length) console.log("teams     (none: `oats aweb setup` creates them, or `oats teams add <label> --team <id>`)");
@@ -1560,7 +1615,7 @@ async function soulCmd() {
   else {
     // The soul is named as for spawn: E_SOUL_UNKNOWN / E_SOUL_AMBIGUOUS; package souls come from the lock.
     let lock = null;
-    try { lock = existsSync(join(ctx.deploymentDir, LOCK_FILE)) ? readLock(ctx.deploymentDir) : null; } catch (e) { return bail(e.code || "E_LOCK_SCHEMA", e.message, e.details); }
+    try { lock = readLockIfPresent(ctx.deploymentDir); } catch (e) { return bail(e.code || "E_LOCK_SCHEMA", e.message, e.details); }
     let discovery, entry;
     try {
       const { discoverOrStandalone, findSoulEntry } = await import("../lib/instance-resolution.mjs");
@@ -1577,7 +1632,7 @@ async function soulCmd() {
     if (mutating) result = V.soulTeamsEdit(teamsCtx, key, edit);
     doc = V.soulTeamsDocument(result ? { ...teamsCtx, local: result.local } : teamsCtx, { soul, key });
   } catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_")) return bail(e.code, e.message, e.details); throw e; }
-  if (JSON_MODE) { jsonOk(result ? { ...doc, changed: result.changed } : doc); return; }
+  if (JSON_MODE) { jsonOk(result ? { ...doc, changed: result.changed } : withObservation(doc)); return; }
   if (result) console.log(result.changed ? `Updated the teams of ${key === "*" ? "every soul" : key} in ${shortPath(teamsCtx.localPath)}` : "Nothing to change");
   console.log(`${key === "*" ? "every soul" : key} on this computer: default ${doc.defaultTeam ? `${doc.defaultTeam.label} (${doc.defaultTeam.from})` : "(none)"}`);
   if (doc.teams.length) printTable(["team", "id", "from", "why"], doc.teams.map((t) => [t.default ? `${t.label} (default)` : t.label, t.team ?? "(no id yet)", t.from, t.via.join(",")]));
@@ -1596,7 +1651,7 @@ async function itemsCmd(kind) {
   if (kind === "capabilities") await capabilityFacts(items, discovery, lock, ctx, remote);
   if (kind === "souls") await soulFacts(items, discovery, lock, ctx, remote);
   const standalone = discovery.standalone === true;
-  if (JSON_MODE) { jsonOk({ [`${kind}Api`]: 1, standalone: standalone || undefined, workspace: { name: workspaceName(discovery), key: discovery.key, commit: discovery.commit }, [kind]: items, problems: discovery.problems }); return; }
+  if (JSON_MODE) { jsonOk(withObservation({ [`${kind}Api`]: 1, standalone: standalone || undefined, workspace: { name: workspaceName(discovery), key: discovery.key, commit: discovery.commit }, [kind]: items, problems: discovery.problems })); return; }
   console.log(`${kind} of workspace ${workspaceName(discovery)} (${discovery.key} @ ${short(discovery.commit)})${standalone ? `  — ${standaloneNote(discovery)}` : ""}\n`);
   if (!items.length) console.log("  (none)");
   else if (kind === "souls") printTable(["name", "origin", "teams here", "work"], items.map((s) => [s.name, s.origin, s.teams === null ? "(invalid: oats teams)" : s.teams.map((t) => (t.default ? `${t.label}*` : t.label)).join(",") || "—", s.work ?? "—"]));
@@ -1616,14 +1671,24 @@ async function capabilityFacts(rows, discovery, lock, ctx, remote = remoteModule
   for (const [id, entry] of Object.entries(lock?.packages || {})) {
     try { packages.set(id, await lockedPackageCapabilities(id, entry, { catalog, remote, remoteOptions })); } catch { packages.set(id, null); }
   }
+  // Indexes built once (a scan of every member per row was O(rows × members)): the member row per key
+  // (memberRowByKey); the member rows per (key, commit), in row order.
+  const capOf = (member, name) => member?.capabilities.find((c) => c.name === name);
+  const rowsAt = new Map();
+  for (const r of rows) {
+    if (r.kind === "package") continue;
+    const k = `${r.repoKey}\0${r.commit}`;
+    if (!rowsAt.has(k)) rowsAt.set(k, []);
+    rowsAt.get(k).push(r);
+  }
   // A member capability's fingerprint is its Git tree at the commit (one listing per member commit); a
   // package's is the package integrity (the lock).
   const trees = new Map();
   const treeOf = async ({ repoKey, commit }, ref, dir) => {
     const key = `${repoKey}\0${commit}`;
     if (!trees.has(key)) {
-      const member = discovery.members.find((m) => m.key === repoKey);
-      const dirs = rows.filter((r) => r.kind !== "package" && r.repoKey === repoKey && r.commit === commit).map((r) => member?.capabilities.find((c) => c.name === r.name)?.path).filter(Boolean);
+      const member = memberRowByKey(discovery.members, repoKey);
+      const dirs = (rowsAt.get(key) || []).map((r) => capOf(member, r.name)?.path).filter(Boolean);
       trees.set(key, remoteModule.remoteTreeOids(ref, commit, [...new Set(dirs)], remoteOptions).catch(() => new Map()));
     }
     return (await trees.get(key)).get(dir) ?? null;
@@ -1634,7 +1699,7 @@ async function capabilityFacts(rows, discovery, lock, ctx, remote = remoteModule
       const read = packages.get(row.package), cap = read?.capabilities.find((c) => c.name === row.name);
       if (cap) ({ manifest, dir } = cap), ref = read.ref;
     } else {
-      const cap = discovery.members.find((m) => m.key === row.repoKey)?.capabilities.find((c) => c.name === row.name);
+      const cap = capOf(memberRowByKey(discovery.members, row.repoKey), row.name);
       if (cap) { manifest = cap.manifest; dir = cap.path; ref = memberRef(discovery, remoteModule, row.repoKey); }
     }
     const provides = manifest ? await capabilityProvides({ ref, commit: row.commit, dir, manifest, remote, remoteOptions }) : { skills: null, commands: null, hooks: null };
@@ -1649,9 +1714,13 @@ async function capabilityFacts(rows, discovery, lock, ctx, remote = remoteModule
  *  discovery and the lock without spawning (soulSpawnability). */
 async function soulFacts(rows, discovery, lock, ctx, remote = remoteModule) {
   const { soulSpawnability } = await import("../lib/instance-resolution.mjs");
-  const entryOf = (row) => row.kind === "package" ? (discovery.packageSouls || []).find((p) => p.qualifiedName === row.qualifiedName)
-    : row.kind === "external" ? (discovery.external || []).map((e) => e.soul).find((x) => x.name === row.name && x.repoKey === row.repoKey)
-    : discovery.members.find((m) => m.key === row.repoKey)?.souls.find((x) => x.name === row.name);
+  // Indexes built once, each keeping the FIRST match as `find` did (a scan per row was O(souls × members)).
+  const first = (pairs) => { const m = new Map(); for (const [k, v] of pairs) if (!m.has(k)) m.set(k, v); return m; };
+  const packageSoul = first((discovery.packageSouls || []).map((p) => [p.qualifiedName, p]));
+  const externalSoul = first((discovery.external || []).map((e) => e.soul).map((x) => [`${x.name}\0${x.repoKey}`, x]));
+  const entryOf = (row) => row.kind === "package" ? packageSoul.get(row.qualifiedName)
+    : row.kind === "external" ? externalSoul.get(`${row.name}\0${row.repoKey}`)
+    : memberRowByKey(discovery.members, row.repoKey)?.souls.find((x) => x.name === row.name);
   for (const row of rows) {
     const entry = entryOf(row);
     row.file = { path: `${row.path}/soul.yaml`, url: remoteModule.browseUrl(row.repoKey, row.commit, `${row.path}/soul.yaml`) };
@@ -1689,7 +1758,7 @@ async function statusDrift(data) {
   if (!anything) return { drift: new Map(), soul: new Map(), souls, unreachable: null };
   const deploymentDir = dirname(ctx.path);
   let lock = null;
-  try { if (existsSync(join(deploymentDir, LOCK_FILE))) lock = readLock(deploymentDir); } catch { lock = null; }
+  try { lock = readLockIfPresent(deploymentDir); } catch { lock = null; }
   let discovery;
   // The standalone view (decisions 10/25) is a discovery too: drift of a standalone
   // instance is computed against its member's current state, not reported "unreachable".
@@ -1707,9 +1776,12 @@ async function statusDrift(data) {
     if (hasSoul(i)) { try { const row = soulDriftOf(i, discovery); if (row) soul.set(key, row); } catch { /* an unreadable soul record shows as no soul row */ } }
   }
   // The roster's soul row reflects the CURRENT member commit too (the pointer may lag a moved member).
+  // First match per key, as `find` gave, from indexes built once (not a scan per agent).
+  const packageSoulAt = new Map();
+  for (const p of discovery.packageSouls || []) { const k = `${p.package}\0${p.path}`; if (!packageSoulAt.has(k)) packageSoulAt.set(k, p); }
   for (const [, stamp] of souls) {
-    if (typeof stamp.package === "string") { const now = (discovery.packageSouls || []).find((p) => p.package === stamp.package && p.path === stamp.path); if (now) stamp.current = now.commit; continue; }
-    const member = discovery.members.find((m) => m && m.key === stamp.repoKey);
+    if (typeof stamp.package === "string") { const now = packageSoulAt.get(`${stamp.package}\0${stamp.path}`); if (now) stamp.current = now.commit; continue; }
+    const member = memberRowByKey(discovery.members, stamp.repoKey);
     if (member && typeof member.commit === "string" && (member.confirmed || (discovery.standalone === true && member.key === discovery.key))) stamp.current = member.commit;
   }
   return { drift, soul, souls, unreachable: null };
@@ -1780,7 +1852,8 @@ async function status() {
         if (s) i.soul = { repoKey: s.repoKey, commit: s.commit, current: s.current?.commit ?? null, status: s.status, ...(s.reason ? { reason: s.reason } : {}), ...(s.package ? { package: s.package, version: s.version, currentVersion: s.current?.version ?? null } : {}) };
       }
     }
-    console.log(JSON.stringify({ root, agents: data, ...(ws ? { workspace: ws.unreachable ? { reachable: false, ...ws.unreachable } : { reachable: true } } : {}), ...(problems.length ? { problems } : {}), ...envelopeWarnings() }, null, 2)); return;
+    const observation = maxAgeGiven === null ? {} : { observation: observationBlock() };
+    console.log(JSON.stringify({ root, agents: data, ...observation, ...(ws ? { workspace: ws.unreachable ? { reachable: false, ...ws.unreachable } : { reachable: true } } : {}), ...(problems.length ? { problems } : {}), ...envelopeWarnings() }, null, 2)); return;
   }
   console.log(`oats status — agents root ${shortPath(root)}\n`);
   if (ws?.unreachable) console.log(`  workspace: unreachable (${ws.unreachable.reason}) — drift unknown\n`);
@@ -2069,7 +2142,7 @@ async function spawnCmd() {
       // (the deployment's cache had no entry for its commit): the result says so.
       if (prepared) r.soulFetched = soulFetched;
       if (JSON_MODE) { jsonOk(r); return; }
-      console.log(`preview ${r.agent} → ${r.instance} (${r.work}${r.branch ? `, branch ${r.branch} from ${r.base.ref}@${r.base.oid.slice(0, 12)}` : ""}) harness ${r.harness}${r.model ? ` model ${r.model}` : ` (${r.modelSource})`}; nothing was created${soulFetched ? " (the soul source was fetched to a temporary copy, not kept)" : ""}`);
+      console.log(`preview ${r.agent} → ${r.instance} (${r.work}${r.branch ? `, branch ${r.branch} from ${r.base.ref}@${r.base.oid.slice(0, 12)}` : ""}) harness ${r.harness}${r.model ? ` model ${r.model}` : ` (${r.modelSource})`}${r.launchConfig ? ` via launch configuration ${r.launchConfig}${r.launchConfigDefault ? ` (this machine's ${r.harness} default)` : ""}` : ""}${r.yolo ? " YOLO" : ""}; nothing was created${soulFetched ? " (the soul source was fetched to a temporary copy, not kept)" : ""}`);
       return;
     }
   } catch (e) {
@@ -2081,7 +2154,7 @@ async function spawnCmd() {
     // A launch refusal (configuration, executable, environment reference,
     // model, harness) is a fact about the selection, not a spawn-mechanism
     // failure: it keeps its own code so a GUI can act on it.
-    if (typeof e?.code === "string" && /^E_LAUNCH_|^E_MODEL_UNKNOWN$|^E_UNSUPPORTED_HARNESS$|^E_HARNESS_UNAVAILABLE$/.test(e.code)) { bail(e.code, e.message, e.details); throw e; }
+    if (typeof e?.code === "string" && /^E_LAUNCH_|^E_MODEL_UNKNOWN$|^E_UNSUPPORTED_HARNESS$|^E_HARNESS_UNAVAILABLE$|^E_CLAUDE_CONFIG_REMOVED$/.test(e.code)) { bail(e.code, e.message, e.details); throw e; }
     // An unmet declared requirement is a fact about the soul's configuration
     // (with a remedy), not a spawn-mechanism failure: keep its code and details.
     if (e?.code === "E_REQUIREMENT_INACTIVE") { bail(e.code, e.message, { soul: e.soul, capabilities: e.capabilities, context: e.context, remedy: e.remedy }); throw e; }
@@ -2782,6 +2855,7 @@ async function capabilityCommand() {
     // OATS_SOUL is the recorded soul or nothing: an ambient value inherited from the
     // invoking process names some other soul (a coordinator's own), never this one.
     const { OATS_SOUL: _ambientSoul, ...inherited } = process.env;
+    await readSession?.closeBatches(); // no idle `git cat-file --batch` child held for the provider's whole run
     const r = spawnSync("node", [abs, ...rest, ...rawArgs.slice(2)], { stdio: "inherit", env: {
       ...inherited, OATS_CAPABILITY: m.capability,
       // Package-runtime boundary: dispatched commands receive the active
@@ -2803,7 +2877,9 @@ async function capabilityCommand() {
     } });
     // Child never ran (spawn error): nothing reached stdout — keep the envelope contract.
     if (r.error) bail("E_CAPABILITY_BROKEN", `oats ${cmd} ${sub}: ${r.error.message || r.error}`);
-    process.exit(r.status ?? 1);
+    // A provider killed by a signal (a Ctrl-C reaches both it and us; our read session's handler
+    // waits for spawnSync) exits as the shell reports a signal death: 128 + its number.
+    process.exit(r.status ?? (r.signal ? 128 + (osConstants.signals[r.signal] ?? 0) : 1));
   }
 }
 
@@ -2861,7 +2937,7 @@ function versionCmd() {
     // Phase B: `instance-modules` and `spawn-provider-payload` are advertised only once spawn
     // runs on resolve/materialize (contract §6); a feature the binary does not implement is
     // never listed.
-    console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends: ["tmux"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations", "readiness", "instance-events", "instance-git", "lifecycle-plans"], features: ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-2", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from"], automationsApi: A.AUTOMATIONS_API, workspaceApi: 2, instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 2, lifecycleApi: 1, readinessApi: 2, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 3, scheduleApi: SCHEDULE_API, operationsApi: 2 }));
+    console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends: ["tmux"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations", "readiness", "instance-events", "instance-git", "lifecycle-plans"], features: ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-2", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "launch-config-default"], automationsApi: A.AUTOMATIONS_API, workspaceApi: 2, instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 2, lifecycleApi: 1, readinessApi: 2, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 3, scheduleApi: SCHEDULE_API, operationsApi: 2 }));
     return;
   }
   console.log(`@awebai/oats ${OATS_VERSION} (desktop API v1)`);
@@ -3253,6 +3329,17 @@ try {
   const selector = head.find((a) => /^--(deployment|resolution|artifact-set)$/.test(a));
   const refuse = (message, details) => { if (JSON_MODE) jsonFail("E_UNSUPPORTED_MODE", message, details); die(message); };
   if (selector) refuse(`${selector}: a captured selector is refused (the captured/portable path was removed in 0.26); run the command in its workspace deployment or instance home instead`, { selector });
+  // --max-age (feature observe-max-age): ONE allow-list for every kernel command, here — never a
+  // per-command copy. A capability namespace's argv is its provider's.
+  if (kernelArgv && head.includes("--max-age")) {
+    const refusal = maxAgeRefusal(cmd, head);
+    if (refusal) cmdFail("E_BAD_ARGS", refusal);
+    const raw = flag("max-age");
+    if (raw === true) cmdFail("E_BAD_ARGS", `--max-age needs a value: whole seconds from 0 to ${remoteModule.MAX_AGE_LIMIT}`);
+    if (!/^\d{1,5}$/.test(raw) || Number(raw) > remoteModule.MAX_AGE_LIMIT) cmdFail("E_BAD_ARGS", `--max-age takes whole seconds from 0 to ${remoteModule.MAX_AGE_LIMIT}, got ${JSON.stringify(raw)}`);
+    maxAgeGiven = Number(raw);
+    activateLocalInputs(); // observation.localRevision: every local config read from here on is recorded
+  }
   const inherited = ["OATS_RESOLUTION", "OATS_DEPLOYMENT"].filter((k) => process.env[k]);
   if (inherited.length && cmd !== "version") refuse(`this environment carries a captured context (${inherited.join(", ")}): the captured/portable path was removed in 0.26, and nothing is run against the current context in its place — retire the captured home and re-spawn it from the deployment`, { inherited });
   if (cmd === "inspect" && head.includes("--request")) {
@@ -3329,7 +3416,8 @@ else if (cmd && !cmd.startsWith("--") && !HELP_WORDS.has(cmd) && JSON_MODE) json
 else {
   if (cmd && !HELP_WORDS.has(cmd) && !cmd.startsWith("--")) console.error(`oats: unknown command "${cmd}" — no kernel subcommand or active capability namespace matches\n`);
   console.log(usageText());
-  process.exit(cmd && !HELP_WORDS.has(cmd) ? 1 : 0);
+  // exitCode, not exit(): the usage is ~20 KB, and exit() cuts off whatever a pipe has not drained yet.
+  process.exitCode = cmd && !HELP_WORDS.has(cmd) ? 1 : 0;
 }
 } // end: every command but onboard
 
@@ -3357,6 +3445,7 @@ Usage:
   oats version [--json]                      kernel version; --json emits the
                                             Desktop CLI API v1 probe payload
   oats status [--json]                       agents, souls, running instances
+      [--max-age <s>]                        reuse head observations up to <s> s old (below)
   oats server add <id> --ssh <alias>         register another machine's OATS (OpenSSH alias,
       --workspace </abs/path> [--oats <p>]   remote workspace, remote oats path; no keys stored;
       [--path <dir:dir>]                    --path = dirs prepended to the remote PATH, e.g. ~/.local/bin)
@@ -3460,7 +3549,7 @@ Usage:
                                             a detached external retirement runs
   oats inspect [--dir <scope>] [--soul <name>   one authoritative JSON answer for a GUI: souls
       [--agents-root <abs>]] [--home <abs>]   (harness defaults, editability, instructions),
-      [--json]                              installed capabilities with health, effective
+      [--max-age <s>] [--json]              installed capabilities with health, effective
                                             layer bindings and activation, declared
                                             operations with availability; --home answers the
                                             running home's recorded modules and their drift
@@ -3501,19 +3590,20 @@ Usage:
       | remove <id>  [--dir <d>]            workspace repo is the current checkout; otherwise
                                             print the line to add (the file travels through Git)
   oats workspace status [--dir <d>] [--json] membership table (confirmed / no-backlink /
-                                            cannot-read / backlink-elsewhere), locked packages
+      [--max-age <s>]                       cannot-read / backlink-elsewhere), locked packages
   oats capabilities [--dir <d>] [--json]     every capability of every confirmed member (a
-                                            private one is listed as repo-owned: usable only by
+      [--max-age <s>]                       private one is listed as repo-owned: usable only by
                                             its own repo's souls) + the locked packages
   oats souls [--dir <d>] [--json]            every soul of every confirmed member + external souls
-                                            (souls have no private mode), with origin
+      [--max-age <s>]                       (souls have no private mode), with origin
                                             (member <key> @ <commit> | package <id> v<ver>) and its
                                             teams on this deployment
   oats teams [--json] | add <label> --team <id> [--description <d>] | remove <label>
       | default <label>  [--dir <d>]        this deployment's teams (shared + local), the
-                                            default; add/remove/default edit oats-local.yaml
+      [--max-age <s>] (the read form only)  default; add/remove/default edit oats-local.yaml
   oats soul teams <soul>|'*' [--add a,b] [--remove a,b] [--default <l> | --clear-default]
       [--dir <d>] [--json]                  which teams a soul (or every soul) belongs to here
+      [--max-age <s>] (without an edit)
   oats instance git <instance> [--home <abs>] [--dir <d>] [--json]
                                              read-only Git observation of the instance's work
                                              tree: branch, status (renames kept), ahead/behind
@@ -3568,6 +3658,18 @@ The turn record (core — every conversation captured, searchable, replicated):
   oats <namespace> <command> [args…]         run an operational command only when its
                                             capability is active (e.g. oats okf harvest)
 
+Observation reuse (feature observe-max-age):
+  --max-age <seconds>                        on the read verbs only — status, workspace status,
+                                            souls, capabilities, inspect --soul|--home, and the
+                                            read forms of teams and soul teams — reuse a remote
+                                            head observation up to <seconds> old (0–86400; 0 is
+                                            live) instead of asking the remote again; the JSON
+                                            then carries observation { observedAt (the oldest
+                                            head used), reused, localRevision (a digest of
+                                            the local configuration read) }. Refused
+                                            (E_BAD_ARGS) by every other command, an edit form,
+                                            and with --server
+
 Layers: ${LAYERS.join(", ")}. Workspace model v2: docs/design/2026-09-23-workspace-module-contracts.md.`;
 }
 } catch (e) {
@@ -3577,4 +3679,7 @@ Layers: ${LAYERS.join(", ")}. Workspace model v2: docs/design/2026-09-23-workspa
   // already names the offending file — the readers re-raise it with one.
   if (JSON_MODE) jsonFail(e.code, e.message);
   die(e.message);
+} finally {
+  // The command's read session: every `git cat-file --batch` child ends before the process does.
+  if (readSession) await readSession.close();
 }

package/docs/configuration.md

@@ -50,6 +50,11 @@ launch-configs:                              # named ways this host starts a har
       CLAUDE_CONFIG_DIR: { fromEnv: PERSONAL_CLAUDE_DIR }
     model: opus
     yolo: false
+  mine:
+    harness: claude
+    default: true                            # this host's baseline for every claude launch (0.32)
+    env:
+      CLAUDE_CONFIG_DIR: /home/ana/.claude-personal
 ```
 
 Schema: [`oats-local.schema.json`](oats-local.schema.json). Unknown keys are
@@ -70,7 +75,7 @@ refused (`E_WORKSPACE_SCHEMA`).
 | `host.name` | This machine's name. A workspace trigger or schedule runs only on the host named by its `runsOn` ([schedules.md](schedules.md)). |
 | `automations.trust` | The workspace triggers and schedules (`<member>/<id>`) this host agrees to run, or `"*"` for every one the workspace places here (0.30). Absent or empty: none runs. See [Who runs workspace automations](#who-runs-workspace-automations). |
 | `triggers.disabled`, `schedules.disabled` | Workspace triggers and schedules (`<member>/<id>`) this host does not run, without a commit. Written by `oats trigger disable` / `oats schedule disable`. |
-| `launch-configs.<name>` | A named way to start a harness on this host, chosen at spawn or session start, never by the soul. See [Launch configurations](#launch-configurations). |
+| `launch-configs.<name>` | A named way to start a harness on this host, chosen at spawn or session start, never by the soul. `default: true` makes it this host's baseline for its harness (0.32). See [Launch configurations](#launch-configurations). |
 | `souls.launch` | This machine's launch preference per soul (0.30): `"*"` for every soul, a soul's own entry (its name, or `<package>/<soul>`) over it. A value is a `launch-configs` name or an inline `{ harness, model? }`. It overrides the soul's own `launch:`; explicit spawn flags win over both. See [Launch preferences](#launch-preferences). |
 
 How teams are resolved, and what a messaging provider does with them, is in
@@ -81,8 +86,9 @@ How teams are resolved, and what a messaging provider does with them, is in
 An entry has `harness` (`pi` \| `claude` \| `codex`, required), `executable`
 (a bare name looked up on `PATH`, or a path relative to this deployment
 directory), `args` (literal, no shell), `env` (a literal string, or
-`{ fromEnv: NAME }` resolved on the host at start), `model` and `yolo`. A
-launch configuration is a host choice: a soul never names one.
+`{ fromEnv: NAME }` resolved on the host at start), `model`, `yolo` and
+`default` (0.32; see [the harness default](#the-harness-default)). A launch
+configuration is a host choice: a soul never names one.
 
 - Select one with `--launch-config <name>` on `oats spawn`,
   `oats session start` and `oats session restart`. A named configuration is
@@ -104,6 +110,50 @@ launch configuration is a host choice: a soul never names one.
 - The old key `runtime` is still read as `harness`, with a
   `deprecated-runtime-name` warning.
 
+### The harness default
+
+`default: true` makes a configuration this host's baseline for its harness
+(0.32, feature `launch-config-default`). Use it for what every launch of a
+harness on this machine needs, whatever soul or preference chose it: an
+account directory (`CLAUDE_CONFIG_DIR`), a wrapper `executable`, an argument.
+
+- **When it applies:** a new launch that picks the harness without naming a
+  configuration: a soul's `launch:`, an inline `souls.launch` preference,
+  `--harness` (on a spawn, or on `session start|restart` of an existing
+  home), `--reselect-launch`, and the host default (`pi`). It supplies the
+  executable, args, env and `yolo`. A `yolo` recorded from a default stays
+  with it: a later `--launch-config none` or another harness does not carry
+  it over.
+- **The model** comes from whatever picked the harness (`--model`, then the
+  preference); the default's `model` is the last fallback, before the
+  harness's own.
+- **A named configuration runs as declared**: `--launch-config <name>` or a
+  `souls.launch` name never inherits from the default. `--launch-config none`
+  (or a `souls.launch` entry of `none`) asks for the bare harness and
+  bypasses it.
+- **One per harness.** A second `default: true` for the same harness is
+  refused (`E_LAUNCH_CONFIG_INVALID`, naming both); move it by clearing the
+  old one first.
+- **Existing homes keep their launch** until `--reselect-launch` or a
+  respawn, like any change of preference. Declaring a default is such a
+  change: `oats readiness --home` warns `launch-changed` on each existing
+  home the default would now apply to, until it is restarted with
+  `--reselect-launch` or respawned.
+- **It is visible.** `oats launch-config list` marks it; `spawn --preview`,
+  `launch-config preview`, `instance.json` and `oats inspect --home` say when
+  a launch's configuration came from the default (`launchConfigDefault`).
+  A default with `yolo: true` turns yolo on for every launch of that harness
+  here: the preview shows it.
+- **Every kernel that reads the deployment needs OATS 0.32+.** OATS 0.31
+  and older refuse the whole `oats-local.yaml` (`E_WORKSPACE_SCHEMA`) once a
+  configuration declares `default`.
+
+`oats-claude-config` (a one-line file naming the claude binary, found walking
+up from the deployment) is no longer read. A new claude launch with one in
+reach is refused (`E_CLAUDE_CONFIG_REMOVED`) naming the file: declare the
+name it holds as the claude default (`executable: <name>`, `default: true`)
+and delete the file. Homes launched with it keep their recorded executable.
+
 ### Launch preferences
 
 A soul says what its role should run on, and each machine may override it
@@ -128,9 +178,11 @@ souls:
   harness and replaces only its model.
 - A **launch configuration** name runs that configuration's full recipe. An
   **inline or soul preference** runs its harness the way this host starts it
-  without a configuration (the executable on `PATH`, no args, no env), with
-  its `model`. A preference without `model` uses the harness's own model; it
-  never borrows a lower layer's.
+  without a configuration: [the harness default](#the-harness-default) if
+  one is declared, else the executable on `PATH` with no args and no env,
+  with the preference's `model`. A preference without `model` uses the
+  harness default's model, else the harness's own; it never borrows a lower
+  layer's.
 - **A missing harness is refused**, never replaced: `E_HARNESS_UNAVAILABLE`
   names the layer that chose it and the fix (install the harness, or override
   it here in `souls.launch`). `oats souls` still lists the soul, with the
@@ -274,5 +326,10 @@ oats spawn <soul> --preview    # the exact modules, teams and provider payloads
 oats doctor                    # this deployment's files and the lock
 ```
 
-Environment: `OATS_REMOTE_CACHE` relocates the fetch cache;
-`OATS_PACKAGE_CATALOG` names an alternative package catalog file.
+Environment: `OATS_REMOTE_CACHE` relocates the fetch cache (which also holds
+the bounded parsed-read cache and the observations `--max-age` reuses; all of
+it is safe to delete); `OATS_PACKAGE_CATALOG` names an alternative package
+catalog file. The read verbs (`status`, `workspace status`, `souls`,
+`capabilities`, `inspect`, and the read forms of `teams` and `soul teams`)
+take `--max-age <seconds>` to reuse a remote head observed that recently
+([Observation reuse](desktop-cli-api.md#observation-reuse-feature-observe-max-age-oats-0311)).