@awebai/oats 0.30.3 → 0.32.0

package/lib/errors.mjs

@@ -5,3 +5,20 @@ export function oatsError(code, message, provenance) {
   if (provenance) e.provenance = provenance;
   return e;
 }
+
+/** Herdr was removed in 0.31.0: every place that meets it refuses with E_HERDR_REMOVED, this stem
+ *  and what to do. */
+export const HERDR_REMOVED = "Herdr is no longer supported by OATS (removed in 0.31.0); tmux is the only session backend.";
+/** A flag or configuration value that selects Herdr: `what` names the flag (`--backend herdr was
+ *  given`), or the file and key (`<file> sets spawn.backend: herdr`). */
+export function herdrSettingRemoved(what) {
+  return oatsError("E_HERDR_REMOVED", `${HERDR_REMOVED} ${what}. Remove it (or use tmux).`);
+}
+/** A session operation on an instance OATS opened in Herdr. */
+export function herdrInstanceRemoved(name) {
+  return oatsError("E_HERDR_REMOVED", `${HERDR_REMOVED} ${name} was opened in Herdr. Retire it (\`oats retire ${name}\`) and spawn a new instance; it opens in tmux.`);
+}
+/** Retiring an instance OATS opened in Herdr while processes still work in its home. */
+export function herdrInstanceBusy(name, pids) {
+  return oatsError("E_HERDR_REMOVED", `${HERDR_REMOVED} ${name} was opened in Herdr. A process still works in this home (pid ${pids.join(", ")}); stop its Herdr pane (for example \`herdr --session oats server stop\`), then retire.`);
+}

package/lib/instance-inspect.mjs

@@ -14,7 +14,7 @@ import { spawnSync } from "node:child_process";
 import { accessSync, constants as fsConstants, existsSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { capabilityManifests, homeLaunchLayers, instanceSoulDir, launchConfigsAt, launchReportFor, manifestOperations, parseYamlNested, servedIdentityOf, teamEnv, upgradeHomeMeta, withConfigFile } from "./core.mjs";
+import { capabilityManifests, sessionDefaults, homeLaunchLayers, instanceSoulDir, launchConfigsAt, launchReportFor, manifestOperations, parseYamlNested, servedIdentityOf, teamEnv, upgradeHomeMeta, withConfigFile } from "./core.mjs";
 import { agentDirOf, discoverOrStandalone, ensureWorkspaceSoul, findSoulEntry, liveTeams, prepareInstance } from "./instance-resolution.mjs";
 import { declaredSettings } from "./capability-contract.mjs";
 import { kernelCompatibility } from "./resolve.mjs";
@@ -127,7 +127,7 @@ export async function homeTarget(home, meta, { remoteOptions, discover = true, l
   try { launchCurrent = launchReportFor({ layers: homeLaunchLayers(realHome, meta), launchConfigs: launchConfigsAt(deployment), contextDir: deployment }); }
   catch { launchCurrent = null; }
   return {
-    kind: "instance", home: realHome, meta, deployment, agentsRoot, teams: live.teams, defaultTeam: live.defaultTeam ?? null, teamsSource: live.source, launch, launchCurrent,
+    kind: "instance", home: realHome, meta, deployment, agentsRoot, teams: live.teams, defaultTeam: live.defaultTeam ?? null, teamsSource: live.source, launch, launchCurrent, session: newSessionDefaults(deployment),
     recordedDefaultTeam: recordedTeams(meta).defaultTeam, teamModel: model, teamKey,
     subject: { kind: "instance", instance: meta.instance, home, soul: meta.agent },
     soul: { name: meta.agent, repoKey: ws.soul?.repoKey ?? null, commit: ws.soul?.commit ?? null, external, path: null, soulDir, definition, problems: [...problems, ...loadProblems] },
@@ -183,7 +183,7 @@ export async function soulTarget(contextDir, soul, { remoteOptions } = {}) {
   try { launchConfigs = launchConfigsAt(deployment); } catch { launchConfigs = {}; }
   const launch = launchReportFor({ layers: prepared?.launch ?? launchLayers({ definition: soulEntry.definition, entry: soulEntry, key: teamKey, local: found.local }), launchConfigs, contextDir: deployment });
   return {
-    kind: "soul", home: null, meta: null, deployment, agentsRoot: join(deployment, "agents"), teams, defaultTeam, teamsSource: "live", teamModel: model, teamKey, launch,
+    kind: "soul", home: null, meta: null, deployment, agentsRoot: join(deployment, "agents"), teams, defaultTeam, teamsSource: "live", teamModel: model, teamKey, launch, session: newSessionDefaults(deployment),
     subject: { kind: "soul", soul: soulEntry.name, repoKey: soulEntry.repoKey ?? null, commit: soulEntry.commit ?? null },
     soul: { name: soulEntry.name, repoKey: soulEntry.repoKey ?? null, commit: soulEntry.commit ?? null, external: soulEntry.external === true, path: soulEntry.path ?? null,
       soulDir, definition: soulEntry.definition ?? null, problems: [], ...(soulCopyError ? { copyError: soulCopyError } : {}) },
@@ -195,6 +195,12 @@ export async function soulTarget(contextDir, soul, { remoteOptions } = {}) {
   };
 }
 
+/** The tmux session a NEW tmux spawn here would open in ({tmuxSession}, 0.31); null when the
+ *  deployment's oats-local.yaml cannot be read. */
+function newSessionDefaults(deployment) {
+  try { return sessionDefaults(deployment); } catch { return null; }
+}
+
 /** Is `dir` a v2 context (an oats-local.yaml in reach)? Only a MISSING file means
  *  "not a workspace"; an unreadable or invalid one is the caller's error to report,
  *  never a silent fallback to the classic chain. */
@@ -256,8 +262,11 @@ export function inspectDocument(t, { kernel }) {
     // Feature launch-preference: a soul's launch here; a home's recorded launch and launchCurrent.
     launch: t.launch ?? null,
     ...(t.home ? { launchCurrent: t.launchCurrent ?? null } : {}),
+    // 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);
     };