@awebai/oats 0.31.0 → 0.32.0

package/lib/core.mjs

@@ -33,6 +33,7 @@ import {
 } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { accessSync, constants as fsConstants } from "node:fs";
+import { recordLocalInput } from "./local-inputs.mjs";
 import { createHash, randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { initializeNativeHistory, prepareNativeStart } from "../packages/record/lib/native-history.mjs";
@@ -183,7 +184,13 @@ export function slug(s) {
   const r = String(s).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
   return r || "agent";
 }
-function which(bin) { return shTry(`command -v ${shq(bin)}`); }
+/** `command -v <bin>`, once per (bin, PATH) in this process: the answer only changes with PATH. */
+const whichMemo = new Map();
+function which(bin) {
+  const key = `${bin}\0${process.env.PATH ?? ""}`;
+  if (!whichMemo.has(key)) whichMemo.set(key, shTry(`command -v ${shq(bin)}`));
+  return whichMemo.get(key);
+}
 
 // ---------- yaml-ish ----------
 /** `__proto__` is never data in a plain-object mapping: assigning it REWRITES
@@ -525,7 +532,7 @@ export const LAYERS = ["knowledge", "messaging", "tasks"];
 // deployment's oats-local.yaml (lead decision 2: a spawn-time HOST choice,
 // never a soul field). Selected at spawn or session start/restart by name.
 export const LAUNCH_HARNESSES = ["pi", "claude", "codex"];
-export const LAUNCH_CONFIG_KEYS = new Set(["harness", "runtime", "executable", "args", "env", "model", "yolo"]);
+export const LAUNCH_CONFIG_KEYS = new Set(["harness", "runtime", "executable", "args", "env", "model", "yolo", "default"]);
 /** A launch configuration's harness: `harness`, or `runtime`, its pre-0.27 name (0.26.0
  *  deployments wrote it) — read either (lead call 6). */
 export const launchConfigHarness = (entry) => (Object.hasOwn(entry, "harness") ? entry.harness : entry.runtime);
@@ -541,7 +548,7 @@ export function validateLaunchConfig(name, entry, where) {
   if (typeof name !== "string" || !LAUNCH_CONFIG_NAME.test(name)) bad("has an invalid name (letters, digits, dot, underscore, dash; up to 64 characters)");
   if (name === "none") bad("cannot be named none: that word selects no configuration");
   if (!entry || typeof entry !== "object" || Array.isArray(entry)) bad("must be a map");
-  for (const key of Object.keys(entry)) if (!LAUNCH_CONFIG_KEYS.has(key)) bad(`has an unsupported key ${JSON.stringify(key)} (harness, executable, args, env, model, yolo)`);
+  for (const key of Object.keys(entry)) if (!LAUNCH_CONFIG_KEYS.has(key)) bad(`has an unsupported key ${JSON.stringify(key)} (harness, executable, args, env, model, yolo, default)`);
   if (Object.hasOwn(entry, "harness") && Object.hasOwn(entry, "runtime") && entry.harness !== entry.runtime) bad(`names harness ${JSON.stringify(entry.harness)} and runtime ${JSON.stringify(entry.runtime)}: \`runtime\` is the pre-0.27 name of \`harness\` — keep one`);
   if (!LAUNCH_HARNESSES.includes(launchConfigHarness(entry))) bad(`needs harness: one of ${LAUNCH_HARNESSES.join(", ")}`);
   const text = (v, what) => { if (typeof v !== "string" || !v.trim() || v.includes("\0")) bad(`${what} must be non-empty text`); };
@@ -562,12 +569,25 @@ export function validateLaunchConfig(name, entry, where) {
   }
   if (entry.model !== undefined) text(entry.model, "model");
   if (entry.yolo !== undefined && typeof entry.yolo !== "boolean") bad("yolo must be true or false");
+  if (entry.default !== undefined && typeof entry.default !== "boolean") bad("default must be true or false");
   return entry;
 }
+/** At most one `default: true` per harness (0.32, feature launch-config-default): the host's baseline for
+ *  that harness has one source. `map` is name → entry; entries are validated first. */
+export function validateLaunchConfigDefaults(map, where) {
+  const byHarness = new Map();
+  for (const [name, entry] of Object.entries(map || {})) {
+    if (entry?.default !== true) continue;
+    const harness = launchConfigHarness(entry);
+    if (byHarness.has(harness)) throw Object.assign(oatsError("E_LAUNCH_CONFIG_INVALID", `launch configurations ${JSON.stringify(byHarness.get(harness))} and ${JSON.stringify(name)}${where ? ` in ${where}` : ""} are both default: true for ${harness}; keep one default per harness`), { details: { harness, configurations: [byHarness.get(harness), name] } });
+    byHarness.set(harness, name);
+  }
+}
 function validateLaunchConfigs(map, file) {
   if (map === undefined) return;
   if (!map || typeof map !== "object" || Array.isArray(map)) throw oatsError("E_LAUNCH_CONFIG_INVALID", `launch-configs in ${file} must be a map of name to configuration`);
   for (const [name, entry] of Object.entries(map)) validateLaunchConfig(name, entry, file);
+  validateLaunchConfigDefaults(map, file);
 }
 /** The launch configurations effective at `dir`: the `launch-configs:` of the
  *  oats-local.yaml found walking up from it (the deployment), validated. None
@@ -585,7 +605,7 @@ export function launchConfigsAt(dir) {
   const source = dirname(found.path);
   for (const [name, entry] of Object.entries(map || {})) {
     if (!Object.hasOwn(entry, "harness")) noteRuntimeName(`launch-configs.${name}.runtime in ${found.path}`);
-    out[name] = { name, harness: launchConfigHarness(entry), ...(entry.executable !== undefined ? { executable: entry.executable } : {}), args: [...(entry.args || [])], env: { ...(entry.env || {}) }, ...(entry.model !== undefined ? { model: entry.model } : {}), ...(entry.yolo !== undefined ? { yolo: entry.yolo } : {}), source, shadows: [] };
+    out[name] = { name, harness: launchConfigHarness(entry), ...(entry.executable !== undefined ? { executable: entry.executable } : {}), args: [...(entry.args || [])], env: { ...(entry.env || {}) }, ...(entry.model !== undefined ? { model: entry.model } : {}), ...(entry.yolo !== undefined ? { yolo: entry.yolo } : {}), ...(entry.default === true ? { default: true } : {}), source, shadows: [] };
   }
   return out;
 }
@@ -858,9 +878,14 @@ export function officialPackageCatalog() {
 function readCatalogFile() {
   const file = officialCatalogFile();
   const empty = { packages: Object.create(null), capabilities: Object.create(null), file };
-  if (!existsSync(file)) return empty;
+  // An OATS_PACKAGE_CATALOG override is local configuration (observation.localRevision); the bundled
+  // catalog belongs to the kernel install.
+  const override = !!process.env.OATS_PACKAGE_CATALOG;
+  if (!existsSync(file)) { if (override) recordLocalInput(file, null); return empty; }
   let doc;
-  try { doc = JSON.parse(readFileSync(file, "utf8")); }
+  const text = readFileSync(file, "utf8");
+  if (override) recordLocalInput(file, text);
+  try { doc = JSON.parse(text); }
   catch (e) { throw oatsError("invalid-source", `broken package catalog ${file}: ${e.message}`); }
   if (!doc || typeof doc !== "object" || Array.isArray(doc)) throw oatsError("invalid-source", `broken package catalog ${file}: root must be a JSON object`);
   const out = { packages: Object.create(null), capabilities: Object.create(null), file };
@@ -1247,7 +1272,7 @@ export const HARNESS_PACKAGE_MANAGERS = {
      * different marketplaces into one identity. */
     identity: (spec) => String(spec || "").trim(),
     safeSpec: (spec) => typeof spec === "string" && /^[a-z0-9][\w.-]*@[a-z0-9][\w.-]*$/i.test(spec),
-    /** The executable is CONTEXT-SELECTED (oats-claude-config may name a wrapper
+    /** The executable is SELECTED by the launch (a configuration may name a wrapper
      * such as `claude-personal`). Probing and installing through the literal
      * `claude` would inspect a DIFFERENT account's plugins than the session
      * actually launches with — passing preflight while the real harness lacks
@@ -1848,20 +1873,21 @@ export function tmuxWindows(session = DEFAULT_TMUX_SESSION) {
  * Spawn an instance of `agent` (as returned by findAgent/listAgents).
  * o: { instance?, purpose?, name?, repo?, work?, harness?, model?, task?, taskFile?, branch?, launch?, tmuxSession? }
  */
-/** The claude binary for a context: closest `oats-claude-config` (a one-line file
- * naming the binary, e.g. "claude-personal") walking up from contextDir wins; no
- * file → "claude". Local-only by design — a personal machine preference (account
- * selection), never committed config; keep it out of version control. */
-export function resolveClaudeBinary(contextDir) {
+/** `oats-claude-config` (a one-line file naming the claude binary, found walking up from the context) is no
+ *  longer read (0.32): a host names its claude executable in a default launch configuration. A file still in
+ *  reach of a new claude launch refuses it, naming the file and the configuration to declare instead. */
+export function legacyClaudeConfigRefusal(contextDir) {
   let d = resolve(contextDir);
   while (true) {
     const f = join(d, "oats-claude-config");
     if (existsSync(f)) {
-      const name = readFileSync(f, "utf8").split("\n").map((l) => l.trim()).find((l) => l && !l.startsWith("#"));
-      if (name) return name;
+      let name = null;
+      try { name = readFileSync(f, "utf8").split("\n").map((l) => l.trim()).find((l) => l && !l.startsWith("#")) || null; } catch {}
+      const exe = name ? `executable: ${name}, ` : "";
+      return Object.assign(oatsError("E_CLAUDE_CONFIG_REMOVED", `${f} is no longer read (OATS 0.32): declare this machine's claude default in oats-local.yaml instead — launch-configs: { <name>: { harness: claude, ${exe}default: true } } (oats launch-config set <name> --file <json>) — then delete ${f}`), { details: { file: f, executable: name, fix: `declare a claude default launch configuration (${exe}default: true), then delete ${f}` } });
     }
     const parent = dirname(d);
-    if (parent === d) return "claude";
+    if (parent === d) return null;
     d = parent;
   }
 }
@@ -1961,11 +1987,10 @@ function verifyHarnessPackages(harness, resolved, contextDir, { bin, env } = {})
   const found = [];
   const problems = [];
   // The session launches with the SELECTED executable (a configuration's,
-  // or the context-selected one: oats-claude-config may name
-  // `claude-personal`), so probing another binary would inspect a different
+  // the host's harness default included), so probing another binary would inspect a different
   // account's packages than the instance will actually use. The probe is the
   // manager's controlled list subcommand; no launch argument is added to it.
-  const probeOpts = { context: contextDir, ...(bin ? { bin } : harness === "claude" ? { bin: resolveClaudeBinary(contextDir) } : {}) };
+  const probeOpts = { context: contextDir, ...(bin ? { bin } : {}) };
   for (const cap of resolved.capabilities || []) {
     for (const raw of cap.manifest?.requires || []) {
       if (!raw || typeof raw !== "object") continue;
@@ -2059,8 +2084,10 @@ const LAUNCH_PROMPT = { kind: "task-file", file: "TASK.md" };
 
 /** The executable a launch uses: a configuration's declared one (a bare name
  *  on PATH; a path against the deployment directory when relative) or the
- *  harness's default (claude through oats-claude-config). Never executed. */
+ *  harness's name on PATH. Never executed. A new claude launch with a legacy `oats-claude-config` in reach
+ *  of its context is refused (E_CLAUDE_CONFIG_REMOVED, 0.32), whatever it declares. */
 export function resolveLaunchExecutable({ harness, declared, declaringDir, contextDir }) {
+  if (harness === "claude" && contextDir) { const refused = legacyClaudeConfigRefusal(contextDir); if (refused) throw refused; }
   if (declared) {
     if (declared.includes("/")) {
       const path = isAbsolute(declared) ? declared : resolve(declaringDir || contextDir, declared);
@@ -2069,10 +2096,8 @@ export function resolveLaunchExecutable({ harness, declared, declaringDir, conte
     const found = which(declared);
     return { path: found || null, declared, resolvedFrom: "PATH", missing: found ? undefined : `${declared} binary not found on PATH` };
   }
-  const claudeBin = harness === "claude" ? resolveClaudeBinary(contextDir) : undefined;
-  const name = harness === "claude" ? claudeBin : harness;
-  const found = which(name);
-  return { path: found || null, declared: null, resolvedFrom: harness === "claude" && claudeBin !== "claude" ? "oats-claude-config" : "PATH", missing: found ? undefined : `${name} binary not found on PATH${claudeBin && claudeBin !== "claude" ? " (named by oats-claude-config)" : ""}` };
+  const found = which(harness);
+  return { path: found || null, declared: null, resolvedFrom: "PATH", missing: found ? undefined : `${harness} binary not found on PATH` };
 }
 /** null when `path` is a regular executable file; otherwise why not. */
 export function checkLaunchExecutable(path) {
@@ -2107,7 +2132,7 @@ export function resolveLaunchSelection({ launchConfigs = {}, agent, frozen, sele
     // applies the current definition.
     // Named or not: the recorded executable (a saved wrapper, say), args and
     // env are what runs; later edits of the scope never change it.
-    config = { name: frozen.launchConfig || null, harness: frozen.harness, ...(frozen.executableDeclared ? { executable: frozen.executableDeclared } : {}), executablePath: frozen.executable, args: [...(frozen.args || [])], env: { ...(frozen.env || {}) }, ...(frozen.model ? { model: frozen.model } : {}), ...(frozen.yolo !== undefined ? { yolo: frozen.yolo } : {}), source: frozen.launchConfigSource || null, frozen: true };
+    config = { name: frozen.launchConfig || null, harness: frozen.harness, ...(frozen.executableDeclared ? { executable: frozen.executableDeclared } : {}), executablePath: frozen.executable, args: [...(frozen.args || [])], env: { ...(frozen.env || {}) }, ...(frozen.model ? { model: frozen.model } : {}), ...(frozen.yolo !== undefined ? { yolo: frozen.yolo } : {}), source: frozen.launchConfigSource || null, ...(frozen.launchConfigDefault === true ? { harnessDefault: true } : {}), frozen: true };
     wanted = "none";
   }
   if (wanted === undefined) wanted = frozen ? "none" : (agent?.["launch-config"] || "none");
@@ -2120,6 +2145,9 @@ export function resolveLaunchSelection({ launchConfigs = {}, agent, frozen, sele
   // 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)`);
+  // 0.32 (feature launch-config-default): a launch that selected no configuration runs this host's default
+  // for its harness, if one is declared. An explicit `--launch-config none` asks for the bare harness.
+  const harnessDefault = !config && !(selection.launchConfig === "none" && !preference) ? harnessDefaultConfig(launchConfigs, harness) : null;
   let model, modelSource;
   // K6: an EXPLICIT "use the harness's native default" is distinct from an
   // omitted model (which inherits the configuration's or soul's preference).
@@ -2145,8 +2173,19 @@ export function resolveLaunchSelection({ launchConfigs = {}, agent, frozen, sele
     // is no proof it fits another one. Nothing is passed across.
     model = ""; modelSource = "native default (harness differs from the soul's)";
   } else { model = resolveModelPreference(agent?.model || "", harness); modelSource = model ? "soul default" : "native default"; }
+  // The harness default's model is the last fallback: below every layer that names one, above the harness's own.
+  if (harnessDefault?.model && !model && !nativeDefault) {
+    model = resolveModelPreference(harnessDefault.model, harness); modelSource = `launch-config ${harnessDefault.name}`;
+    if (!model) bad("E_MODEL_UNKNOWN", `launch configuration ${harnessDefault.name} (the ${harness} default) names model ${JSON.stringify(harnessDefault.model)}, which has no entry usable by harness ${harness}`);
+  }
+  if (harnessDefault) config = harnessDefault;
   return { config, harness, model, modelSource, configuredYolo: config?.yolo };
 }
+/** This host's default launch configuration for `harness` (`default: true`), marked `harnessDefault`, or null. */
+export function harnessDefaultConfig(launchConfigs, harness) {
+  const found = Object.values(launchConfigs || {}).find((c) => c?.default === true && c.harness === harness);
+  return found ? { ...found, harnessDefault: true } : null;
+}
 /** 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) {
@@ -2186,7 +2225,11 @@ export function launchReportFor({ layers, launchConfigs = {}, contextDir }) {
     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 });
+  // As a spawn: a layer naming "none" asks for the bare harness; otherwise no configuration is the harness default.
+  if (!config && !(choice.selection.launchConfig === "none" && !choice.preference)) { config = harnessDefaultConfig(launchConfigs, harness); if (config && !model) model = typeof config.model === "string" && config.model ? config.model : null; }
+  let exe;
+  try { exe = resolveLaunchExecutable({ harness, declared: config?.executable, declaringDir: config?.source, contextDir }); }
+  catch (e) { if (e?.code !== "E_CLAUDE_CONFIG_REMOVED") throw e; return report(harness, model, config?.name, { code: e.code, message: e.message, fix: `declare a claude default launch configuration (oats launch-config set), then delete ${e.details.file}` }); }
   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);
@@ -2364,7 +2407,10 @@ export function planLaunch({ home, instance, meta, contextDir, agentLike, select
     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));
+  // A recorded yolo that came from a harness default belongs to that default: it never carries into a launch
+  // the default no longer decides (a bare --launch-config none, another harness).
+  const frozenYolo = frozen && !(frozen.launchConfigDefault === true && !config?.frozen) ? frozen.yolo : undefined;
+  const yolo = resolveYolo(selection.yolo ?? chosen.configuredYolo ?? (frozen ? frozenYolo : 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 });
@@ -2432,7 +2478,7 @@ export function planLaunch({ home, instance, meta, contextDir, agentLike, select
     } else problems.push({ check: "harness-packages", ok: true, detail: "no harness package requirement declared for this harness; nothing probed" });
   }
   const recipe = {
-    version: LAUNCH_RECIPE_VERSION, harness, launchConfig: config?.name || null, launchConfigSource: config?.source || null,
+    version: LAUNCH_RECIPE_VERSION, harness, launchConfig: config?.name || null, launchConfigSource: config?.source || null, ...(config?.harnessDefault ? { launchConfigDefault: true } : {}),
     executable: executable.path || executable.declared || harness, executableDeclared: executable.declared ?? null, executableResolvedFrom: executable.resolvedFrom,
     args: [...(config?.args || [])], env: { ...configEnv }, model: model || null, ...(yolo !== undefined ? { yolo } : {}),
     hooks: frozen ? { launch: hooks.launch, env: hooks.env, contributions: hooks.contributions } : hooks, prompt: LAUNCH_PROMPT, kernelBin: kernelBin(),
@@ -2984,7 +3030,7 @@ function* spawnBody(root, agent, o = {}) {
       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,
+      harness, model: model || null, modelSource: launchSelection.modelSource ?? null, launchConfig: launchConfig?.name ?? null, launchConfigDefault: launchConfig?.harnessDefault === true, 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,
@@ -3523,7 +3569,7 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
     const shimTarget = writeKernelShim(home);
     const recipe = {
       version: LAUNCH_RECIPE_VERSION, harness,
-      launchConfig: launchConfig?.name || null, launchConfigSource: launchConfig?.source || null,
+      launchConfig: launchConfig?.name || null, launchConfigSource: launchConfig?.source || null, ...(launchConfig?.harnessDefault ? { launchConfigDefault: true } : {}),
       executable: bin, executableDeclared: executable.declared, executableResolvedFrom: executable.resolvedFrom,
       args: [...(launchConfig?.args || [])], env: { ...(launchConfig?.env || {}) },
       model: model || null, ...(yolo !== undefined ? { yolo } : {}),

package/lib/instance-inspect.mjs

@@ -265,7 +265,8 @@ export function inspectDocument(t, { kernel }) {
     // What a new tmux spawn here would open in: {tmuxSession} (0.31).
     session: t.session ?? null,
     knowledge: kcap ? { provider: kcap.id, version: kcap.version, operations: kcap.operations.map((o) => ({ name: o.name, kind: o.kind, available: o.available, reason: o.reason })) } : { provider: null, version: null, operations: [] },
-    instance: m ? { home: t.home, instance: m.instance, agent: m.agent, harness: m.harness || null, model: m.model ?? null, yolo: m.yolo ?? null, launched: !!m.launched, createdAt: m.createdAt || null,
+    instance: m ? { home: t.home, instance: m.instance, agent: m.agent, harness: m.harness || null, model: m.model ?? null, yolo: m.yolo ?? null,
+      launchConfig: m.launch?.launchConfig ?? null, launchConfigDefault: m.launch?.launchConfigDefault === true, launched: !!m.launched, createdAt: m.createdAt || null,
       resolution: m.workspace?.resolution ?? null, soulDir: t.soul.soulDir, instructions: { ...readTextCapped(join(t.home, "AGENTS.md")), sources: m.instructions || [] } } : null,
     ...(m ? { identity: servedIdentityOf(m) } : {}),
     problems: [...t.soul.problems, ...(t.soul.copyError ? [t.soul.copyError] : []), ...(t.discoveryError ? [t.discoveryError] : []),

package/lib/instance-resolution.mjs

@@ -30,7 +30,7 @@ import { mkdirSync, mkdtempSync, renameSync, rmSync, writeFileSync, symlinkSync,
 import { tmpdir } from "node:os";
 import { spawnSync } from "node:child_process";
 import { randomBytes } from "node:crypto";
-import { readLock, LOCK_FILE, SOUL_ALIAS_SYMLINK } from "./packages.mjs";
+import { readLock, readLockIfPresent, LOCK_FILE, SOUL_ALIAS_SYMLINK } from "./packages.mjs";
 import * as defaultRemote from "./remote.mjs";
 import { parseRepoRef } from "./remote.mjs";
 
@@ -438,7 +438,7 @@ export async function prepareInstance(contextDir, soulName, { spawn = {}, remote
   const found = localOverride ? { path: null, local: localOverride } : loadLocal(contextDir);
   const local = found.local;
   const deployment = found.path ? dirname(found.path) : resolvePath(contextDir);
-  const lock = existsSync(join(deployment, LOCK_FILE)) ? readLock(deployment) : null;
+  const lock = readLockIfPresent(deployment);
   const discovery = discoveryOverride ?? await discoverOrStandalone(local, { lock, remoteOptions, remote });
   const soulEntry = findSoulEntry(discovery, soulName);
   const disabled = disabledEntry(local, soulEntry);
@@ -458,7 +458,7 @@ const isAccessFailure = (e) => e?.code === "E_REMOTE_UNREADABLE" && ACCESS_REASO
 
 /** The deployment's lock, or null when it has none (an unreadable lock is E_LOCK_SCHEMA). */
 export function deploymentLock(deployment) {
-  return existsSync(join(deployment, LOCK_FILE)) ? readLock(deployment) : null;
+  return readLockIfPresent(deployment);
 }
 
 /** Decision 10: a standalone view is a MEMBER whose workspace cannot be read — the

package/lib/local-inputs.mjs

@@ -0,0 +1,46 @@
+/** lib/local-inputs.mjs — the local configuration a command read, for `observation.localRevision`
+ *  (spec Addendum 4; docs/desktop-cli-api.md "Observation reuse").
+ *
+ *  Every reader of local configuration on the read verbs' paths reports what it parsed:
+ *  `recordLocalInput(absPath, bytes)` for a file it read, `recordLocalInput(absPath, null)` for one it
+ *  looked for and found absent (a file appearing changes the answer as much as one changing). The inputs:
+ *  oats-local.yaml and every walk-up candidate loadLocal found absent (lib/workspace.mjs), oats-lock.json
+ *  (lib/packages.mjs readLock / readLockIfPresent), an OATS_PACKAGE_CATALOG override (lib/core.mjs; the
+ *  bundled catalog is the kernel's, not configuration), the automations snapshot (lib/automations.mjs).
+ *  NOT inputs: instance homes and runtime state (the answer reports them), the parsed and observation caches.
+ *
+ *  Recording is a no-op until the CLI activates it for this process (a command with --max-age), so
+ *  library callers and tests are unaffected unless they opt in. The first bytes recorded for a path win.
+ */
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+
+let inputs = null; // canonical path → sha256(bytes) | "absent", while active
+
+/** Start recording for this process (idempotent; clears nothing already recorded). */
+export function activateLocalInputs() { inputs ??= new Map(); }
+
+/** A file's canonical path: its realpath when it exists, else its directory's realpath plus its name
+ *  (else the resolved path), so a symlinked deployment gives one revision. */
+function canonical(absPath) {
+  const path = resolve(absPath);
+  try { return realpathSync(path); } catch { /* absent */ }
+  try { return join(realpathSync(dirname(path)), basename(path)); } catch { return path; }
+}
+
+/** Record one input: the bytes parsed (Buffer | string), or null for a file looked for and absent. */
+export function recordLocalInput(absPath, bytes) {
+  if (!inputs) return;
+  const key = canonical(absPath);
+  if (inputs.has(key)) return;
+  inputs.set(key, bytes === null || bytes === undefined ? "absent" : createHash("sha256").update(bytes).digest("hex"));
+}
+
+/** 24 lowercase hex: sha256 over the sorted `path NUL digest|absent` lines of every recorded input (the
+ *  empty set included). Never a path or content. null when recording is not active. */
+export function localRevision() {
+  if (!inputs) return null;
+  const lines = [...inputs].map(([path, digest]) => `${path}\0${digest}`).sort();
+  return createHash("sha256").update(lines.join("\n")).digest("hex").slice(0, 24);
+}

package/lib/materialize.mjs

@@ -59,6 +59,7 @@ import { oatsError } from "./errors.mjs";
 import * as defaultRemote from "./remote.mjs";
 import { renderInstructionText } from "./instruction-composition.mjs";
 import { DEFAULT_PACKAGE_PATH, validateLock } from "./packages.mjs";
+import { memberRowByKey } from "./workspace.mjs";
 
 export const MODULES_DIR = join(".oats", "modules");
 export const SKILLS_DIR = join(".agents", "skills");
@@ -572,7 +573,7 @@ export function driftOf(instanceJson, discovery, { lock } = {}) {
     }
     const repoKey = typeof from.repoKey === "string" ? from.repoKey : null;
     const recorded = { repoKey, commit };
-    const member = repoKey ? members.find((m) => m && m.key === repoKey) : null;
+    const member = repoKey ? memberRowByKey(members, repoKey) : null;
     if (!member || !member.confirmed || typeof member.commit !== "string") {
       rows.push({ module: name, from: clone(from), recorded, current: null, status: "missing", reason: member ? (member.reason || "unconfirmed") : "unconfirmed" });
       continue;
@@ -616,7 +617,7 @@ export function soulDriftOf(instanceJson, discovery) {
     return { ...base, current: { commit: now.commit, version: now.version }, status: now.commit === commit ? "current" : "moved" };
   }
   const members = Array.isArray(discovery?.members) ? discovery.members : [];
-  const member = members.find((m) => m && m.key === soul.repoKey) || null;
+  const member = memberRowByKey(members, soul.repoKey);
   const standaloneOwn = discovery?.standalone === true && member && member.key === discovery.key && typeof member.commit === "string";
   const base = { name, repoKey: soul.repoKey, commit };
   if (!member || (!member.confirmed && !standaloneOwn) || typeof member.commit !== "string") {

package/lib/packages.mjs

@@ -44,6 +44,7 @@
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync, lstatSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, posix, relative, resolve, sep } from "node:path";
+import { recordLocalInput } from "./local-inputs.mjs";
 import { oatsError as baseOatsError } from "./errors.mjs";
 import * as defaultRemote from "./remote.mjs";
 import { manifestContractProblems } from "./capability-contract.mjs";
@@ -165,14 +166,23 @@ export function validateLock(lock, { file } = {}) {
  * else is validated (E_LOCK_SCHEMA). Returns a fresh object every call. */
 export function readLock(dir) {
   const file = join(resolve(dir), LOCK_FILE);
-  if (!existsSync(file)) return emptyLock();
+  if (!existsSync(file)) { recordLocalInput(file, null); return emptyLock(); }
   let parsed;
-  try { parsed = JSON.parse(readFileSync(file, "utf8")); } catch (e) {
+  const text = readFileSync(file, "utf8");
+  recordLocalInput(file, text);
+  try { parsed = JSON.parse(text); } catch (e) {
     throw oatsError("E_LOCK_SCHEMA", `oats-lock.json is not valid JSON (${file}): ${e.message}`, { file, path: "/" });
   }
   return validateLock(parsed, { file });
 }
 
+/** `<dir>/oats-lock.json` read as readLock does, or null when there is none (recorded as absent). */
+export function readLockIfPresent(dir) {
+  const file = join(resolve(dir), LOCK_FILE);
+  if (!existsSync(file)) { recordLocalInput(file, null); return null; }
+  return readLock(dir);
+}
+
 /** Canonical lock text: sorted package ids, sorted capability names, 2-space indent, trailing newline. */
 export function canonicalLock(lock) {
   validateLock(lock);
@@ -309,8 +319,14 @@ async function readJson(remote, remoteRef, commit, path, what, details) {
 
 /** Read `oats-package.json` and every capability manifest it lists.
  * → { manifest, capabilities: [{ name, dir, manifest }] } (sorted by name, codepoint order).
- * Two capability dirs declaring the same name → E_PACKAGE_MANIFEST { duplicate }. */
+ * Two capability dirs declaring the same name → E_PACKAGE_MANIFEST { duplicate }.
+ * The answer is a pure function of the bytes at the commit: a remote with the parsed cache
+ * (lib/remote.mjs memoAtCommit) keeps it; a refusal is thrown and never kept. */
 export async function readPackageManifests(remote, remoteRef, commit, path, details = {}) {
+  const read = () => readPackageManifestsAt(remote, remoteRef, commit, path, details);
+  return typeof remote.memoAtCommit === "function" ? remote.memoAtCommit(remoteRef, commit, `package-manifests\0${path}`, read) : read();
+}
+async function readPackageManifestsAt(remote, remoteRef, commit, path, details) {
   const manifestPath = pjoin(path, PACKAGE_MANIFEST);
   const manifest = await readJson(remote, remoteRef, commit, manifestPath, "package manifest", details);
   if (!plainObject(manifest) || typeof manifest.package !== "string" || !Array.isArray(manifest.capabilities)) {
@@ -412,7 +428,6 @@ function assertDigest(what, value, details) {
   return value;
 }
 
-/** Bind `remoteOptions` (cacheDir, exec, …) into every call of a contract-§1 remote. */
 /** A remote whose reads at a commit are shared for one command (feature desktop-facts): the souls and
  *  capabilities listings resolve many souls over the same package manifests and skill listings, and a read at
  *  an immutable commit gives the same answer every time. A failed read is not kept (it is retried). */
@@ -430,13 +445,18 @@ export function memoizedRemote(remote) {
   return memo;
 }
 
+/** Bind `remoteOptions` (cacheDir, exec, the command's read `session`, …) into every call of a contract-§1
+ *  remote. Object references are kept (a spread, never a copy of the values), so one session is shared by
+ *  every call; `memoAtCommit` (the parsed cache, lib/remote.mjs) and the member prefetch's primitives
+ *  (`lastObservedCommit`, `peekAtCommit`, `prefetchObservation`) are optional and bound when present. */
 export function bindRemote(remote, remoteOptions) {
   if (!remoteOptions || Object.keys(remoteOptions).length === 0) return remote;
   const bound = { ...remote };
-  for (const name of ["observeRemote", "readRemoteFile", "listRemoteTree", "fetchRemoteTree"]) {
+  const arities = { observeRemote: 1, readRemoteFile: 3, listRemoteTree: 3, fetchRemoteTree: 4, memoAtCommit: 4, lastObservedCommit: 1, peekAtCommit: 3, prefetchObservation: 1, abandonPrefetches: 0 };
+  for (const name of Object.keys(arities)) {
     if (typeof remote[name] !== "function") continue;
     bound[name] = (...args) => {
-      const arity = { observeRemote: 1, readRemoteFile: 3, listRemoteTree: 3, fetchRemoteTree: 4 }[name];
+      const arity = arities[name];
       const opts = { ...(args[arity] || {}), ...remoteOptions };
       return remote[name](...args.slice(0, arity), opts);
     };