@awebai/oats 0.31.0 → 0.33.0

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);
     };

package/lib/process-group.mjs

@@ -10,3 +10,57 @@ export function killGroup(child, signal = "SIGKILL") {
   try { process.kill(pid, signal); } catch { /* already gone */ }
   return true;
 }
+
+/** How long a group asked to end with SIGTERM gets before SIGKILL. */
+export const TERM_GRACE_MS = 2_000;
+
+/** Children whose 'close' has fired (watchGroup): the leader exited and was reaped, its stdio pipes shut. */
+const closedGroups = new WeakSet();
+
+/** Record a detached child's 'close': call it right after spawning a child that terminateGroup may end. → the child. */
+export function watchGroup(child) {
+  child.once("close", () => closedGroups.add(child));
+  return child;
+}
+
+/** How often terminateGroup checks, after the leader's 'close', whether its group is empty yet. */
+export const GROUP_PROBE_MS = 50;
+
+/** Whether a detached child's process group still has a member we may signal (ESRCH: empty; EPERM: not ours). */
+function groupAlive(child) {
+  try { process.kill(-child.pid, 0); return true; } catch { return false; }
+}
+
+/** End a detached child's whole process group gracefully: SIGTERM now, SIGKILL to the group after `graceMs`.
+ *  git removes its own lock files (`shallow.lock`, `config.lock`, a ref's `.lock`) on SIGTERM, never on SIGKILL:
+ *  a git killed outright leaves a lock that blocks every later write. The timers are unref'd, so they never keep
+ *  the process alive. A group seen empty is never signalled again: its id may then lead an unrelated group.
+ *  Returns whether anything was signalled. */
+export function terminateGroup(child, graceMs = TERM_GRACE_MS) {
+  // A child already closed may have left an empty group, whose id is free: send nothing.
+  if (closedGroups.has(child)) return false;
+  if (!signalGroup(child, "SIGTERM")) return false;
+  // Until 'close', the group holds a pipe-holding member (git, or its ssh or remote helper), so its id is ours and
+  // the SIGKILL may come. After 'close' the leader is gone but a member that ignores SIGTERM and holds no pipe may
+  // remain: no pid is allocated while it is a live group's id, so a group seen non-empty is still ours. It is probed
+  // until the grace ends: empty → no SIGKILL, ever; still there → SIGKILL. What remains is a group that empties and is
+  // reused within one GROUP_PROBE_MS.
+  let probe = null;
+  const done = () => { clearTimeout(timer); clearInterval(probe); };
+  const timer = setTimeout(() => { clearInterval(probe); signalGroup(child, "SIGKILL"); }, graceMs);
+  timer.unref?.();
+  child.once?.("close", () => {
+    if (!groupAlive(child)) { done(); return; }
+    probe = setInterval(() => { if (!groupAlive(child)) done(); }, GROUP_PROBE_MS);
+    probe.unref?.();
+  });
+  return true;
+}
+
+/** Signal a detached child's process group only (see killGroup for the pid-0 guard). → whether it was a real child. */
+export function signalGroup(child, signal) {
+  const pid = child?.pid;
+  if (!Number.isSafeInteger(pid) || pid <= 0) return false;
+  try { process.kill(-pid, signal); } catch { /* the group is gone */ }
+  return true;
+}