@awebai/oats 0.31.0 → 0.32.0

package/lib/remote.mjs

@@ -76,20 +76,69 @@
  *   is set, else "644" (Git stores only 100644/100755, so a local checkout under
  *   any umask digests identically to the fetched tree). Empty directories do not
  *   enter identity. Result: "sha256-<hex>". Empty tree → sha256 of the empty input.
+ *
+ * READ SESSION (one per CLI command; docs/implementation.md "The remote read path"):
+ * every in-process memo this module keeps lives in a session object carried as
+ * `options.session` (createReadSession). Without one, every call behaves exactly as
+ * it did before sessions existed: no memo, no batch process, no file under the cache
+ * root beyond the cache repos. A session holds
+ *   - one `ls-remote` per (cache root, url, ref args): a host that is also a member is
+ *     observed once, and every reader in the command sees the same commit; at most
+ *     OBSERVE_LIMIT observations run at once, each holding its slot for ALL its git work
+ *     (the ls-remote, and the fetch of the commit it names or of a reused record's);
+ *   - the member prefetch (prefetchObservation; lib/workspace.mjs discoverWorkspace): a
+ *     workspace discovery starts its members' observations with the host's, from the
+ *     member list at the host's last observed commit (lastObservedCommit + peekAtCommit,
+ *     no git process); a prefetched failure is adopted, never retried in the command;
+ *   - positive peels per (cache repo, oid) — a negative peel is never kept;
+ *   - one recursive tree index per (cache repo, commit): `git ls-tree -r -t -l -z` once,
+ *     answering entryAt / listRemoteTree / remoteTreeOids exactly as per-path listings
+ *     would; any index failure (the output budget, a timeout) falls back to per-path;
+ *   - one long-lived `git cat-file --batch` per cache repo (at most BATCH_LIMIT alive),
+ *     unref'd while idle and ended by session.close();
+ *   - `maxAge` (seconds): > 0 lets observeRemote reuse a recorded head observation
+ *     (the observation store below) no older than that;
+ *   - the head observations used, for the `observation` output block.
+ *
+ * PARSED CACHE (`memoAtCommit`, session only): a value derived only from the bytes at
+ * (repo key, commit) by a given kernel never changes, so it is kept on disk under
+ * `<cacheRoot>/.parsed/<kernel fingerprint>/<sha256(item key)>.json`, written
+ * atomically (temp file + rename), read back only when every recorded field matches,
+ * bounded (LRU by mtime, pruned at most once per session), and never holding a
+ * transient failure (any E_REMOTE_UNREADABLE) or a value whose JSON round trip would
+ * differ. A corrupt entry is a miss, never an error.
+ *
+ * OBSERVATION STORE (session only): `<cacheRoot>/.observed/<sha256(key NUL at-args NUL urlDigest)>.json`
+ * records each successful live head observation { v, key, args, urlDigest, commit, ref,
+ * observedAt } — never the url itself (it may carry userinfo); two spellings of one repo
+ * keep a record each. A record is reused only
+ * under `maxAge`, only when key, ref args and urlDigest all match, and never in place of
+ * a live observation that failed.
  */
-import { execFile, execFileSync } from "node:child_process";
-import { createHash } from "node:crypto";
+import { execFileSync, spawn } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { setMaxListeners } from "node:events";
 import {
   closeSync, existsSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmSync,
-  writeFileSync, writeSync, symlinkSync, readlinkSync } from "node:fs";
+  statSync, utimesSync, writeFileSync, writeSync, symlinkSync, readlinkSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { oatsError } from "./errors.mjs";
+import { killGroup } from "./process-group.mjs";
 
 export const FILE_BUDGET = 4 * 1024 * 1024;        // readRemoteFile: 4 MiB per file
 export const TREE_BUDGET = 64 * 1024 * 1024;       // fetchRemoteTree: 64 MiB per subtree
 export const GIT_TIMEOUT_MS = 30_000;
+/** A session's tree index: the output budget of one `ls-tree -r -t -l -z <commit>`. */
+export const TREE_INDEX_BUDGET = 64 * 1024 * 1024;
+/** `--max-age` bounds (seconds). */
+export const MAX_AGE_LIMIT = 86_400;
+/** At most this many head observations running at once per session (real and prefetched), each for all its
+ *  git work: ls-remote and the fetch of its commit, or a reused record's fetch. */
+export const OBSERVE_LIMIT = 8;
+/** At most this many `cat-file --batch` children alive per session (idle ones are closed first). */
+const BATCH_LIMIT = 12;
 const OID_RE = /^[0-9a-f]{40}$/;
 const SEGMENT_RE = /^[A-Za-z0-9_.-]+$/;
 /** A ref name we are willing to hand to `git ls-remote` as a pattern: never a leading
@@ -210,25 +259,64 @@ function gitEnv() {
 
 /** Default exec dependency: runs `git <args>`; resolves { stdout, stderr } (Buffers);
  * rejects with { code, signal, killed, stderr, stdout, timedOut, overflowed }.
- *   timedOut   — the `timeout` kill (Node reports killed=true + our killSignal, no error.code);
- *   overflowed — stdout/stderr exceeded `maxBuffer` (Node also kills the child, but sets
+ *   timedOut   — the `timeout` kill (killed=true, signal SIGKILL, no error.code);
+ *   overflowed — stdout or stderr exceeded `maxBuffer` (the child is killed too, and
  *                error.code = ERR_CHILD_PROCESS_STDIO_MAXBUFFER): NOT a timeout.
- * Injectable via options.exec. */
-export function runGit(args, { cwd, maxBuffer = 16 * 1024 * 1024, timeout = GIT_TIMEOUT_MS } = {}) {
+ * An abort of `signal` rejects with an AbortError (code ABORT_ERR). git runs detached,
+ * as its own process group: a timeout, an overflow or an abort kills the group, so
+ * git's ssh or remote helper dies with it (a kill of git alone left them running until
+ * their connection ended). Injectable via options.exec. */
+export function runGit(args, { cwd, maxBuffer = 16 * 1024 * 1024, timeout = GIT_TIMEOUT_MS, signal } = {}) {
   return new Promise((resolvePromise, reject) => {
-    execFile("git", args, { cwd, env: gitEnv(), timeout, maxBuffer, shell: false, encoding: "buffer", killSignal: "SIGKILL" },
-      (error, stdout, stderr) => {
-        if (error) {
-          error.stdout = stdout; error.stderr = stderr;
-          error.overflowed = error.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER"
-            || (Buffer.isBuffer(stdout) && stdout.length >= maxBuffer);
-          error.timedOut = !error.overflowed && (error.killed === true || error.signal === "SIGKILL");
-          reject(error);
-        } else resolvePromise({ stdout, stderr });
-      });
+    if (signal?.aborted) { reject(abortError(signal)); return; }
+    // stdin is a pipe that is never written, as execFile gave it.
+    const child = spawn("git", args, { cwd, env: gitEnv(), detached: true, stdio: ["pipe", "pipe", "pipe"] });
+    const out = [], err = [], size = { out: 0, err: 0 };
+    let done = false;
+    const output = () => ({ stdout: Buffer.concat(out), stderr: Buffer.concat(err) });
+    const settle = (error, value) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+      if (error) reject(error); else resolvePromise(value);
+    };
+    const stop = (error) => {
+      if (done) return;
+      killGroup(child);
+      child.stdin.destroy(); child.stdout.destroy(); child.stderr.destroy();
+      settle(Object.assign(error, output()));
+    };
+    const onAbort = () => stop(abortError(signal));
+    const timer = timeout > 0 ? setTimeout(() => stop(Object.assign(new Error(`Command failed: git ${args.join(" ")} (timed out after ${timeout} ms)`),
+      { code: null, killed: true, signal: "SIGKILL", timedOut: true, overflowed: false })), timeout) : null;
+    signal?.addEventListener("abort", onAbort, { once: true });
+    const collect = (chunks, key) => (chunk) => {
+      const room = maxBuffer - size[key];
+      if (chunk.length > room) {
+        chunks.push(chunk.subarray(0, Math.max(0, room))); size[key] = maxBuffer;
+        stop(Object.assign(new RangeError(`${key === "out" ? "stdout" : "stderr"} maxBuffer length exceeded`),
+          { code: "ERR_CHILD_PROCESS_STDIO_MAXBUFFER", killed: true, signal: "SIGKILL", overflowed: true, timedOut: false }));
+        return;
+      }
+      chunks.push(chunk); size[key] += chunk.length;
+    };
+    child.stdout.on("data", collect(out, "out"));
+    child.stderr.on("data", collect(err, "err"));
+    child.on("error", (error) => { killGroup(child); settle(Object.assign(error, output(), { overflowed: false, timedOut: false })); });
+    child.on("close", (code, exitSignal) => {
+      if (code === 0) { settle(null, output()); return; }
+      const { stdout, stderr } = output();
+      settle(Object.assign(new Error(`Command failed: git ${args.join(" ")}\n${stderr.toString("utf8")}`),
+        { code, signal: exitSignal, killed: false, stdout, stderr, overflowed: false, timedOut: exitSignal === "SIGKILL" }));
+    });
   });
 }
 
+function abortError(signal) {
+  return Object.assign(new Error("The operation was aborted", { cause: signal?.reason }), { name: "AbortError", code: "ABORT_ERR", overflowed: false, timedOut: false });
+}
+
 function stderrText(error) {
   const s = error?.stderr;
   return Buffer.isBuffer(s) ? s.toString("utf8") : typeof s === "string" ? s : String(error?.message ?? "");
@@ -280,10 +368,23 @@ async function withCacheLock(dir, fn) {
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 const isLockRace = (error) => /\.lock': File exists|Unable to create .*\.lock|another git process seems to be running/i.test(stderrText(error));
 
+const sha256 = (text) => createHash("sha256").update(text).digest("hex");
+const cacheRootOf = (options) => options.cacheDir ?? defaultCacheRoot();
+const cacheDirOf = (root, ref) => join(root, sha256(ref.key));
+
+/** A url without its userinfo (`ssh://user:secret@host/…` → `ssh://host/…`): what may be written to disk. */
+function redactUrl(url) {
+  return typeof url === "string" ? url.replace(/^([a-z][a-z0-9+.-]*:\/\/)[^@/]*@/i, "$1") : url;
+}
+
+function repoHandle(dir, exec, session) {
+  const local = (args, opts = {}) => exec(["-C", dir, "-c", "gc.auto=0", ...args], { cwd: dir, ...(session ? { signal: session.signal } : {}), ...opts });
+  return { dir, exec, local, session };
+}
+
 async function cacheRepo(ref, options) {
   const exec = options.exec ?? runGit;
-  const root = options.cacheDir ?? defaultCacheRoot();
-  const dir = join(root, createHash("sha256").update(ref.key).digest("hex"));
+  const dir = cacheDirOf(cacheRootOf(options), ref);
   if (!existsSync(join(dir, "HEAD"))) {
     mkdirSync(dir, { recursive: true, mode: 0o700 });
     try { await exec(["init", "-q", "--bare", dir]); }
@@ -291,14 +392,381 @@ async function cacheRepo(ref, options) {
       // Another process may have won the init race; a usable repo is all we need.
       if (!existsSync(join(dir, "HEAD"))) throw unreadable(ref, error, { cacheDir: dir, stage: "init" });
     }
-    try { writeFileSync(join(dir, "oats-remote.json"), JSON.stringify({ key: ref.key, url: ref.url }, null, 2) + "\n", { flag: "wx" }); } catch {}
+    try { writeFileSync(join(dir, "oats-remote.json"), JSON.stringify({ key: ref.key, url: redactUrl(ref.url) }, null, 2) + "\n", { flag: "wx" }); } catch {}
   }
-  const local = (args, opts = {}) => exec(["-C", dir, "-c", "gc.auto=0", ...args], { cwd: dir, ...opts });
-  return { dir, exec, local };
+  return repoHandle(dir, exec, sessionOf(options));
 }
 
 function pinRef(oid) { return `refs/oats/commits/${oid}`; }
 
+// ---------------------------------------------------------------------------
+// read session
+// ---------------------------------------------------------------------------
+
+class ReadSession {
+  constructor({ maxAge = 0, now = Date.now, fingerprint = null, treeIndexBudget = TREE_INDEX_BUDGET, parsedLimits = null, batchTimeoutMs = GIT_TIMEOUT_MS } = {}) {
+    if (!Number.isInteger(maxAge) || maxAge < 0 || maxAge > MAX_AGE_LIMIT) throw new TypeError(`maxAge must be an integer from 0 to ${MAX_AGE_LIMIT}`);
+    this.maxAge = maxAge;
+    this.now = now;
+    this.startedAt = new Date(now()).toISOString();
+    this.fingerprint = fingerprint;        // tests inject one; else the kernel's own (kernelFingerprint)
+    this.treeIndexBudget = treeIndexBudget;
+    this.batchTimeoutMs = batchTimeoutMs;  // tests shorten it; a batch answer is otherwise waited for as long as any git call
+    this.parsedLimits = parsedLimits;      // tests inject small prune bounds
+    this.observations = new Map();         // memo key → Promise<head observation>
+    this.used = new Map();                 // memo key → { observedAt, reused }: the heads this command used
+    this.peels = new Map();                // `${cacheRepo}\0${oid}` → peeled commit (positive answers only)
+    this.trees = new Map();                // `${cacheRepo}\0${commit}` → Promise<tree index | null>
+    this.batches = new Map();              // cacheRepo → batch reader, in least-recently-used order
+    this.retiring = new Set();             // evicted batch readers still ending
+    this.parsedDirs = new Set();           // fingerprint dirs touched (mtime bumped) this session
+    this.observeActive = 0;                // observations running now (at most OBSERVE_LIMIT) …
+    this.observeQueue = [];                // … and the ones waiting for a slot, in order: { resolve, reject }
+    this.prefetched = new Map();           // memo key → prefetch entry { promise, abandoned } no caller has adopted yet
+    this.aborter = new AbortController();  // close()/closeNow() kill every git child still running for this session
+    this.signal = this.aborter.signal;
+    setMaxListeners(0, this.signal);       // every running git child listens (up to 16 at once): no leak warning
+    this.pruned = false;
+    this.closed = false;
+  }
+  /** One of the session's OBSERVE_LIMIT observation slots, shared by real and prefetched observations and
+   *  held for all of an observation's git work (no unbounded fan-out over a large workspace). A released
+   *  slot passes straight to the next waiter. Nothing holding a slot ever waits for another one. */
+  observeSlot() {
+    if (this.closed) return Promise.reject(abandonedError());
+    if (this.observeActive < OBSERVE_LIMIT) { this.observeActive++; return Promise.resolve(); }
+    return new Promise((resolve, reject) => this.observeQueue.push({ resolve, reject }));
+  }
+  observeDone() {
+    const next = this.observeQueue.shift();
+    if (next) next.resolve(); else this.observeActive--;
+  }
+  /** Give up every prefetch no caller has adopted: a queued one never runs its git, and its memo entry is
+   *  dropped so a later caller observes afresh. One already running finishes, or is killed by close(). */
+  abandonPrefetches() {
+    for (const [key, entry] of this.prefetched) {
+      entry.abandoned = true;
+      if (this.observations.get(key) === entry.promise) this.observations.delete(key);
+    }
+    this.prefetched.clear();
+  }
+  /** The command is over: nothing queued runs, and every git child still running is killed. */
+  stop() {
+    this.closed = true;
+    this.abandonPrefetches();
+    for (const waiter of this.observeQueue.splice(0)) waiter.reject(abandonedError());
+    this.aborter.abort();
+  }
+  /** End the batch readers now (a long provider command is about to run) without ending the session:
+   *  a later read opens a new one. */
+  async closeBatches() {
+    const batches = [...this.batches.values(), ...this.retiring];
+    this.batches.clear();
+    await Promise.all(batches.map((b) => b.close()));
+    this.retiring.clear();
+  }
+  /** `{ observedAt, reused }`: the OLDEST head observation this command used (else the time the
+   *  session began), and whether any of them came from the observation store. */
+  observation() {
+    let oldest = null, reused = false;
+    for (const u of this.used.values()) {
+      if (u.reused) reused = true;
+      if (oldest === null || Date.parse(u.observedAt) < Date.parse(oldest)) oldest = u.observedAt;
+    }
+    return { observedAt: oldest ?? this.startedAt, reused };
+  }
+  /** End the session: nothing queued runs, every git child still running is killed, and every batch child
+   *  is ended (stdin closed, awaited (bounded), killed if it lingers). */
+  async close() {
+    this.stop();
+    await this.closeBatches();
+  }
+  /** Synchronous close for `process.on("exit")`: no waiting is possible there. */
+  closeNow() {
+    this.stop();
+    for (const b of [...this.batches.values(), ...this.retiring]) b.kill();
+    this.batches.clear();
+    this.retiring.clear();
+  }
+  /** A session rides remoteOptions, which callers may serialise (memo keys): never its innards. */
+  toJSON() { return "[oats read session]"; }
+}
+
+/** One command's read session (see the module header). `maxAge` seconds (0 = observe live). Test seams:
+ *  `now`, `fingerprint`, `treeIndexBudget`, `parsedLimits`, `batchTimeoutMs`. */
+export function createReadSession(options = {}) { return new ReadSession(options); }
+/** An observation the command no longer wants (its session closed, or its prefetch abandoned): never adopted
+ *  by a caller that is still reading, so its shape only has to be a typed remote failure. */
+function abandonedError() {
+  return fail("E_REMOTE_UNREADABLE", "observation abandoned: the command no longer needs it", { reason: "unknown", abandoned: true });
+}
+/** Give up this session's prefetches that no caller has adopted (lib/workspace.mjs discoverWorkspace, when the
+ *  host cannot be observed or once its members are read). Session only; never throws. */
+export function abandonPrefetches(options = {}) { sessionOf(options)?.abandonPrefetches(); }
+function sessionOf(options) { return options?.session instanceof ReadSession ? options.session : null; }
+
+// ---------------------------------------------------------------------------
+// the parsed cache: values derived from the bytes at (repo key, commit)
+// ---------------------------------------------------------------------------
+
+/** The prune bounds (count AND bytes, least recently used first; maintainer amendment 5). */
+export const PARSED_LIMITS = Object.freeze({
+  maxEntries: 8192, maxBytes: 128 * 1024 * 1024,          // prune when either is exceeded …
+  keepEntries: 6144, keepBytes: 96 * 1024 * 1024,          // … down to both of these
+  staleFingerprintMs: 7 * 24 * 3600 * 1000,                // another kernel's directory, unused this long
+  staleObservationMs: 30 * 24 * 3600 * 1000,               // an observation record this old
+  staleTempMs: 3600 * 1000,                                // a writer's temp file left by a crash
+});
+
+/** The kernel code fingerprint: sha256 over package.json's version, the resolved version of the
+ *  `yaml` parser, then every lib/**\/*.mjs and docs/*.schema.json (path NUL bytes NUL), in sorted
+ *  path order. A checkout whose parsing changed (its code, or a parser bumped without a kernel
+ *  version bump) never reads another build's entries. Computed once per process, lazily. */
+let fingerprintMemo = null;
+export function kernelFingerprint() {
+  if (fingerprintMemo) return fingerprintMemo;
+  const root = fileURLToPath(new URL("..", import.meta.url));
+  const files = [];
+  const walk = (dir) => {
+    for (const d of readdirSync(dir, { withFileTypes: true })) {
+      const p = join(dir, d.name);
+      if (d.isDirectory()) walk(p);
+      else if (d.isFile() && d.name.endsWith(".mjs")) files.push(p);
+    }
+  };
+  walk(join(root, "lib"));
+  for (const name of readdirSync(join(root, "docs"))) if (name.endsWith(".schema.json")) files.push(join(root, "docs", name));
+  const rels = files.map((f) => relative(root, f).split(sep).join("/")).sort();
+  const hash = createHash("sha256");
+  hash.update(String(JSON.parse(readFileSync(join(root, "package.json"), "utf8")).version)); hash.update("\0");
+  hash.update(`yaml@${resolvedVersion("yaml")}`); hash.update("\0");
+  for (const rel of rels) { hash.update(rel); hash.update("\0"); hash.update(readFileSync(join(root, rel))); hash.update("\0"); }
+  fingerprintMemo = hash.digest("hex");
+  return fingerprintMemo;
+}
+
+/** The version of the package `name` this kernel imports (the package.json above its resolved entry),
+ *  or "unresolved". */
+function resolvedVersion(name) {
+  try {
+    let dir = dirname(fileURLToPath(import.meta.resolve(name)));
+    for (;;) {
+      try {
+        const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+        if (pkg.name === name) return String(pkg.version);
+      } catch { /* no package.json here */ }
+      const up = dirname(dir);
+      if (up === dir) return "unresolved";
+      dir = up;
+    }
+  } catch { return "unresolved"; }
+}
+
+const TRANSIENT_REASONS = new Set(["timeout", "network", "auth", "unknown"]);
+/** A value the parsed cache may keep: JSON-safe (its round trip is deepStrictEqual — plain or
+ *  null-prototype objects, dense arrays, finite numbers other than -0, strings, booleans, null; no
+ *  undefined, no cycle) and free of transient failures (any E_REMOTE_UNREADABLE, or a remote
+ *  failure reason timeout/network/auth/unknown). → encoded { data, nullProto: [pointer] } | null */
+function encodeCacheable(value) {
+  const nullProto = [];
+  const ancestors = new Set();
+  const esc = (k) => k.replace(/~/g, "~0").replace(/\//g, "~1");
+  const ok = (v, ptr) => {
+    if (v === null || typeof v === "string" || typeof v === "boolean") return true;
+    if (typeof v === "number") return Number.isFinite(v) && !Object.is(v, -0);
+    if (typeof v !== "object" || ancestors.has(v)) return false;
+    if (Object.getOwnPropertySymbols(v).length) return false;
+    ancestors.add(v);
+    try {
+      const descriptors = Object.getOwnPropertyDescriptors(v);
+      if (Array.isArray(v)) {
+        if (Object.keys(descriptors).length !== v.length + 1) return false; // indices + length only
+        for (let i = 0; i < v.length; i++) { const d = descriptors[i]; if (!d || !("value" in d) || !d.enumerable || !ok(d.value, `${ptr}/${i}`)) return false; }
+        return true;
+      }
+      const proto = Object.getPrototypeOf(v);
+      if (proto !== Object.prototype && proto !== null) return false;
+      if (proto === null) nullProto.push(ptr);
+      if (v.code === "E_REMOTE_UNREADABLE" || (typeof v.code === "string" && v.code.startsWith("E_REMOTE_") && TRANSIENT_REASONS.has(v.reason))) return false;
+      for (const [k, d] of Object.entries(descriptors)) if (!("value" in d) || !d.enumerable || !ok(d.value, `${ptr}/${esc(k)}`)) return false;
+      return true;
+    } finally { ancestors.delete(v); }
+  };
+  return ok(value, "") ? { data: value, nullProto } : null;
+}
+/** A URL that may carry a secret: any userinfo on http(s) (a bare token), or a `user:password` userinfo on any
+ *  scheme. Repo content can hold one (a member ref written with credentials); such a value is never written
+ *  to the parsed cache. `ssh://git@host/…` (a user, no password) is not a secret. */
+const CREDENTIAL_URL_RE = /\bhttps?:\/\/[^\s"'\/@]+@|\b[a-z][a-z0-9+.-]*:\/\/[^\s"'\/@:]+:[^\s"'\/@]*@/i;
+function carriesCredential(text) { return CREDENTIAL_URL_RE.test(text); }
+function reviveCached(data, nullProto) {
+  if (!nullProto.length) return data;
+  const wanted = new Set(nullProto);
+  const esc = (k) => k.replace(/~/g, "~0").replace(/\//g, "~1");
+  const walk = (v, ptr) => {
+    if (Array.isArray(v)) { for (let i = 0; i < v.length; i++) v[i] = walk(v[i], `${ptr}/${i}`); return v; }
+    if (v === null || typeof v !== "object") return v;
+    const out = wanted.has(ptr) ? Object.create(null) : v;
+    for (const k of Object.keys(v)) {
+      const child = walk(v[k], `${ptr}/${esc(k)}`);
+      if (out === v && k !== "__proto__") v[k] = child; // an own "__proto__" key is data: never an assignment
+      else Object.defineProperty(out, k, { value: child, enumerable: true, writable: true, configurable: true });
+    }
+    return out;
+  };
+  return walk(data, "");
+}
+
+/** Write `text` to `file` atomically: a temp file in the same directory, then rename. Failures are ignored
+ *  (every store here is an optimisation, never an error). → whether it was written. */
+function writeAtomicQuiet(file, text) {
+  const dir = dirname(file);
+  const tmp = join(dir, `.${file.slice(dir.length + 1)}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`);
+  try {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    writeFileSync(tmp, text, { mode: 0o600 });
+    renameSync(tmp, file);
+    return true;
+  } catch {
+    try { rmSync(tmp, { force: true }); } catch { /* nothing */ }
+    return false;
+  }
+}
+/** Read and parse a JSON store file → value | undefined (absent, unreadable, corrupt: a corrupt or partial
+ *  file is removed when it can be). */
+function readStoreFile(file) {
+  let text;
+  try { text = readFileSync(file, "utf8"); } catch { return undefined; }
+  try { return JSON.parse(text); }
+  catch { try { rmSync(file, { force: true }); } catch { /* nothing */ } return undefined; }
+}
+
+function parsedDir(root, session) { return join(root, ".parsed", session.fingerprint ?? kernelFingerprint()); }
+
+/**
+ * The parsed cache (see the module header): `compute()`'s value for `item` at (refText's key, commit),
+ * from `<cacheRoot>/.parsed/<fingerprint>/` when an intact entry is there — no git process — else computed,
+ * kept when cacheable, and returned. Without a session (library callers), or for a commit that is not a
+ * full OID, it only computes. A thrown compute() is never kept.
+ */
+export async function memoAtCommit(refText, commit, item, compute, options = {}) {
+  const slot = parsedSlot(refText, commit, item, options);
+  if (!slot) return compute();
+  if (slot.hit) return slot.value;
+  const { session, key, root, dir, fingerprint, file } = slot;
+  const value = await compute();
+  const encoded = encodeCacheable(value);
+  const text = encoded ? JSON.stringify({ v: 1, fingerprint, key, commit, item, nullProto: encoded.nullProto, value: encoded.data }) : null;
+  if (text !== null && !carriesCredential(text) && writeAtomicQuiet(file, text)) {
+    session.parsedDirs.add(dir);
+    if (!session.pruned) { session.pruned = true; pruneStores(root, { fingerprint, limits: session.parsedLimits ?? PARSED_LIMITS, now: session.now() }); }
+  }
+  return value;
+}
+/** The parsed-cache slot of (refText's key, commit, item) in this session → null when there is no cache
+ *  (no session, not a full OID, an unparseable ref), else { …where, hit, value? } — a hit read and revived,
+ *  a corrupt or mismatched entry removed (a miss). */
+function parsedSlot(refText, commit, item, options) {
+  const session = sessionOf(options);
+  if (!session || typeof commit !== "string" || !OID_RE.test(commit) || typeof item !== "string") return null;
+  let key;
+  try { key = parseRepoRef(refText, options).key; } catch { return null; }
+  const root = cacheRootOf(options);
+  const dir = parsedDir(root, session);
+  const fingerprint = session.fingerprint ?? kernelFingerprint();
+  const file = join(dir, `${sha256(JSON.stringify([key, commit, item]))}.json`);
+  const slot = { session, key, root, dir, fingerprint, file, hit: false };
+  const entry = readStoreFile(file);
+  if (entry !== undefined) {
+    const intact = entry && typeof entry === "object" && entry.v === 1 && entry.fingerprint === fingerprint && entry.key === key
+      && entry.commit === commit && entry.item === item && Object.hasOwn(entry, "value") && Array.isArray(entry.nullProto);
+    if (intact) {
+      touchParsed(file, dir, session);
+      return { ...slot, hit: true, value: reviveCached(entry.value, entry.nullProto) };
+    }
+    try { rmSync(file, { force: true }); } catch { /* a miss either way */ }
+  }
+  return slot;
+}
+/** A parsed-cache entry, read only: its value when an intact entry is there, else undefined. Never computes,
+ *  never starts a git process (the member prefetch's source). */
+export function peekAtCommit(refText, commit, item, options = {}) {
+  const slot = parsedSlot(refText, commit, item, options);
+  return slot?.hit ? slot.value : undefined;
+}
+/** A hit bumps the entry's mtime (LRU) and, once per session, its fingerprint directory's (in use). */
+function touchParsed(file, dir, session) {
+  const now = new Date(session.now());
+  try { utimesSync(file, now, now); } catch { /* ignore */ }
+  if (!session.parsedDirs.has(dir)) { session.parsedDirs.add(dir); try { utimesSync(dir, now, now); } catch { /* ignore */ } }
+}
+
+/**
+ * Bound the stores under `root` (one scan): the current fingerprint's entries, least recently used first,
+ * down to keepEntries AND keepBytes once over maxEntries OR maxBytes; other fingerprint directories unused
+ * for staleFingerprintMs; observation records older than staleObservationMs; temp files a crashed writer
+ * left. Never throws. → { removed, entries, bytes } for the current fingerprint.
+ */
+export function pruneStores(root, { fingerprint = kernelFingerprint(), limits = PARSED_LIMITS, now = Date.now() } = {}) {
+  const L = { ...PARSED_LIMITS, ...limits };
+  const list = (dir) => { try { return readdirSync(dir); } catch { return []; } };
+  const stat = (p) => { try { return statSync(p); } catch { return null; } };
+  const remove = (p, opts = {}) => { try { rmSync(p, { force: true, ...opts }); return true; } catch { return false; } };
+  const parsed = join(root, ".parsed");
+  let removed = 0, entries = 0, bytes = 0;
+  for (const name of list(parsed)) {
+    const dir = join(parsed, name);
+    if (name === fingerprint) {
+      const files = [];
+      for (const f of list(dir)) {
+        const p = join(dir, f), st = stat(p);
+        if (!st) continue;
+        if (f.endsWith(".tmp")) { if (now - st.mtimeMs > L.staleTempMs && remove(p)) removed++; continue; }
+        files.push({ p, size: st.size, mtime: st.mtimeMs });
+      }
+      entries = files.length; bytes = files.reduce((n, f) => n + f.size, 0);
+      if (entries > L.maxEntries || bytes > L.maxBytes) {
+        files.sort((a, b) => a.mtime - b.mtime);
+        for (const f of files) {
+          if (entries <= L.keepEntries && bytes <= L.keepBytes) break;
+          if (remove(f.p)) { removed++; entries--; bytes -= f.size; }
+        }
+      }
+    } else {
+      const st = stat(dir);
+      if (st && now - st.mtimeMs > L.staleFingerprintMs && remove(dir, { recursive: true })) removed++;
+    }
+  }
+  const observed = join(root, ".observed");
+  for (const f of list(observed)) {
+    const p = join(observed, f), st = stat(p);
+    if (st && now - st.mtimeMs > (f.endsWith(".tmp") ? L.staleTempMs : L.staleObservationMs) && remove(p)) removed++;
+  }
+  return { removed, entries, bytes };
+}
+
+// ---------------------------------------------------------------------------
+// the observation store: successful live head observations, for --max-age
+// ---------------------------------------------------------------------------
+
+const observationFile = (root, ref, atArgs) => join(root, ".observed", `${sha256(`${ref.key}\0${atArgs.join("\0")}\0${sha256(ref.url)}`)}.json`);
+
+/** A recorded observation of (ref.key, atArgs) reusable now under session.maxAge, else null. With
+ *  `anyAge`, an intact record of any age (what the prefetch learns the last-read commit from). */
+function readObservation(root, ref, atArgs, session, { anyAge = false } = {}) {
+  const rec = readStoreFile(observationFile(root, ref, atArgs));
+  if (!rec || typeof rec !== "object" || rec.v !== 1 || rec.key !== ref.key || rec.urlDigest !== sha256(ref.url)) return null;
+  if (!Array.isArray(rec.args) || rec.args.length !== atArgs.length || rec.args.some((a, i) => a !== atArgs[i])) return null;
+  if (typeof rec.commit !== "string" || !OID_RE.test(rec.commit) || (rec.ref !== null && typeof rec.ref !== "string")) return null;
+  const at = typeof rec.observedAt === "string" ? Date.parse(rec.observedAt) : NaN;
+  const now = session.now();
+  if (!Number.isFinite(at) || (!anyAge && (at > now + 5000 || now - at > session.maxAge * 1000))) return null;
+  return { commit: rec.commit, ref: rec.ref, observedAt: rec.observedAt };
+}
+function writeObservation(root, ref, atArgs, obs) {
+  writeAtomicQuiet(observationFile(root, ref, atArgs), JSON.stringify({ v: 1, key: ref.key, args: atArgs, urlDigest: sha256(ref.url), commit: obs.commit, ref: obs.ref, observedAt: obs.observedAt }));
+}
+
 /** The COMMIT <oid> peels to, when <oid> is present in the cache and is a commit or an
  * annotated tag chain ending in one; null on a missing object, a pruned store, or a
  * tag/tree/blob that does not peel to a commit. (`rev-parse <oid>^{commit}` peels.) */
@@ -321,12 +789,17 @@ async function objectType(repo, oid) {
  * `refs/oats/tags/<oid>` pin so gc cannot break the chain either.
  */
 async function ensureCommit(ref, oid, options) {
-  const root = options.cacheDir ?? defaultCacheRoot();
-  const dir = join(root, createHash("sha256").update(ref.key).digest("hex"));
+  const dir = cacheDirOf(cacheRootOf(options), ref);
+  // A session keeps POSITIVE peels: a commit present in the cache stays present for the command
+  // (pinned, and nothing here runs gc). A negative answer is never kept.
+  const session = sessionOf(options);
+  const known = session?.peels.get(`${dir}\0${oid}`);
+  if (known) return { repo: repoHandle(dir, options.exec ?? runGit, session), commit: known };
+  const remember = (commit) => { if (session) { session.peels.set(`${dir}\0${oid}`, commit); session.peels.set(`${dir}\0${commit}`, commit); } return commit; };
   return withCacheLock(dir, async () => {
     const repo = await cacheRepo(ref, options);
     const cached = await peelCommit(repo, oid);
-    if (cached) return { repo, commit: cached }; // pinned AND present AND (peels to) a commit
+    if (cached) return { repo, commit: remember(cached) }; // pinned AND present AND (peels to) a commit
     let lastError;
     for (let attempt = 0; attempt < 3; attempt++) {
       try {
@@ -347,7 +820,7 @@ async function ensureCommit(ref, oid, options) {
     }
     await repo.local(["update-ref", pinRef(commit), commit]);
     if (commit !== oid) await repo.local(["update-ref", `refs/oats/tags/${oid}`, oid]);
-    return { repo, commit };
+    return { repo, commit: remember(commit) };
   });
 }
 
@@ -391,23 +864,120 @@ function resolveAt(parsed, at) {
  * at: undefined → remote default branch (ls-remote --symref HEAD); a full OID; or a tag/branch name.
  * → { key, url, commit, ref, observedAt } | throws E_REMOTE_UNREADABLE { url, reason }.
  * Never half-succeeds; never prompts. A full OID already in the cache costs no network call.
+ * With a session: one head observation per (cache root, url, ref) per command, and — under
+ * session.maxAge — a recorded observation no older than that is reused instead of `ls-remote`
+ * (the result then carries the RECORDED observedAt and `reused: true`). A full-OID `at` is not a
+ * head observation: never recorded, reused or counted.
  */
 export async function observeRemote(refText, { at, ...options } = {}) {
   const ref = parseRepoRef(refText, options);
-  const exec = options.exec ?? runGit;
   if (at !== undefined && at !== null && typeof at !== "string") throw fail("E_REPO_REF", "at must be a string (full OID, tag or branch name)", { at });
   if (typeof at === "string" && OID_RE.test(at)) {
     // A tag OID is accepted here; the commit recorded is the one it peels to (M4).
     const { commit } = await ensureCommit(ref, at, options);
     return { key: ref.key, url: ref.url, commit, ref: null, observedAt: new Date().toISOString() };
   }
+  const args = lsRemoteArgs(ref, at);
+  const session = sessionOf(options);
+  if (!session) return observeLive(ref, args, at, options);
+  const memoKey = JSON.stringify([cacheRootOf(options), args]);
+  const obs = await sessionObservation(ref, args, at, options, session, memoKey, false);
+  // Counted only here, by a caller that uses it: a prefetched head nobody asks for never is.
+  session.used.set(memoKey, { observedAt: obs.observedAt, reused: obs.reused === true });
+  return { ...obs, key: ref.key, url: ref.url };
+}
+
+/** The `ls-remote` argv of a head observation (`at`: HEAD, a tag or a branch; never a full OID). */
+function lsRemoteArgs(ref, at) {
   const wantHead = at === undefined || at === null || at === "" || at === "HEAD";
   if (!wantHead && AT_BAD_RE.test(at)) throw fail("E_REPO_REF", `at must be a full OID or a plain tag/branch name, got ${JSON.stringify(at)}`, { at });
   const args = ["ls-remote", "--symref", ref.url];
   if (wantHead) args.push("HEAD");
   else args.push(`refs/tags/${at}`, `refs/tags/${at}^{}`, `refs/heads/${at}`, at);
+  return args;
+}
+
+/**
+ * The session's one observation of (cache root, url, ref args): started by the first caller, adopted by
+ * every later one. A failure started by an ordinary caller is dropped from the memo, so a later caller
+ * retries. A failure started by a PREFETCH (prefetchObservation) is kept and adopted: it happened moments
+ * earlier in this same command, and a retry would double a 30 s timeout on an unreachable member
+ * (spec Addendum 3, item 4).
+ */
+function sessionObservation(ref, args, at, options, session, memoKey, prefetch) {
+  let pending = session.observations.get(memoKey);
+  if (!pending) {
+    const entry = prefetch ? { promise: null, abandoned: false } : null;
+    pending = observeInSession(ref, args, at, options, session, entry);
+    if (!prefetch) pending = pending.catch((error) => { session.observations.delete(memoKey); throw error; });
+    else { entry.promise = pending; session.prefetched.set(memoKey, entry); }
+    session.observations.set(memoKey, pending);
+  } else if (!prefetch) session.prefetched.delete(memoKey); // adopted: never abandoned from here on
+  return pending;
+}
+
+/**
+ * The commit this machine last observed `refText` at (`at` as observeRemote takes it), from its observation
+ * record — of any age: this is not reuse — or the full OID `at` itself. Session only; no git process.
+ * → full OID | null (no session, no intact record for this key, ref args and url digest).
+ */
+export function lastObservedCommit(refText, { at, ...options } = {}) {
+  const session = sessionOf(options);
+  if (!session) return null;
+  try {
+    if (typeof at === "string" && OID_RE.test(at)) return at;
+    const ref = parseRepoRef(refText, options);
+    const record = readObservation(cacheRootOf(options), ref, lsRemoteArgs(ref, at).slice(3), session, { anyAge: true });
+    return record ? record.commit : null;
+  } catch { return null; }
+}
+
+/**
+ * Start the session's head observation of `refText` now, without waiting for it (the member prefetch,
+ * spec Addendum 3): the same memoised observation a later observeRemote adopts — success or failure —
+ * under the same observation limit, reusing a record exactly as observeRemote would. Session only; an
+ * unparseable ref or a full-OID `at` is ignored. Never throws, never rejects unhandled.
+ */
+export function prefetchObservation(refText, { at, ...options } = {}) {
+  const session = sessionOf(options);
+  if (!session || (typeof at === "string" && OID_RE.test(at))) return;
+  try {
+    const ref = parseRepoRef(refText, options);
+    const args = lsRemoteArgs(ref, at);
+    sessionObservation(ref, args, at, options, session, JSON.stringify([cacheRootOf(options), args]), true).catch(() => { /* adopted by its caller */ });
+  } catch { /* not a ref: nothing to prefetch */ }
+}
+
+/** A head observation in a session: a reusable record (maxAge > 0) whose commit is pinned or can still be
+ *  fetched, else live — and every successful live observation is recorded. A problem with a record is
+ *  never an error (live instead); a failed live observation is exactly today's error. */
+async function observeInSession(ref, args, at, options, session, prefetch = null) {
+  const root = cacheRootOf(options);
+  const atArgs = args.slice(3);
+  await session.observeSlot(); // held for every git process below: the reuse path's fetch as much as ls-remote's
+  try {
+    // A prefetch given up while it queued (or a session closed meanwhile) runs no git at all.
+    if (session.closed || prefetch?.abandoned) throw abandonedError();
+    if (session.maxAge > 0) {
+      const record = readObservation(root, ref, atArgs, session);
+      if (record) {
+        const reused = { key: ref.key, url: ref.url, commit: record.commit, ref: record.ref, observedAt: record.observedAt, reused: true };
+        if (existsSync(join(cacheDirOf(root, ref), pinRef(record.commit)))) return reused;
+        try { return { ...reused, commit: (await ensureCommit(ref, record.commit, options)).commit }; }
+        catch { /* the recorded commit can no longer be fetched: observe live */ }
+      }
+    }
+    const obs = await observeLive(ref, args, at, options);
+    writeObservation(root, ref, atArgs, obs);
+    return obs;
+  } finally { session.observeDone(); }
+}
+
+async function observeLive(ref, args, at, options) {
+  const exec = options.exec ?? runGit;
+  const signal = sessionOf(options)?.signal;
   let out;
-  try { out = await exec(args, { timeout: GIT_TIMEOUT_MS }); }
+  try { out = await exec(args, { timeout: GIT_TIMEOUT_MS, ...(signal ? { signal } : {}) }); }
   catch (error) { throw unreadable(ref, error, { at: at ?? null }); }
   const parsed = parseLsRemote(out.stdout);
   const hit = resolveAt(parsed, at);
@@ -472,11 +1042,11 @@ function assertNoCollisions(entries, ref, commit, prefix) {
  * Any other failure is E_REMOTE_UNREADABLE (reason "timeout" for the timeout kill, else
  * "unknown") — never a raw Node/git error: enumerateRepo turns E_REMOTE_* into a problem
  * row and would otherwise abort the whole discovery on one unexplained listing (L4). */
-async function lsTree(repo, spec, { flags = [], path, ref, commit } = {}) {
+async function lsTree(repo, spec, { flags = [], path, ref, commit, maxBuffer = 64 * 1024 * 1024 } = {}) {
   try {
     const args = ["ls-tree", "-l", "-z", ...flags, spec];
     if (path !== undefined) args.push("--", ...[].concat(path));
-    const out = await repo.local(args, { maxBuffer: 64 * 1024 * 1024 });
+    const out = await repo.local(args, { maxBuffer });
     return parseLsTree(out.stdout);
   } catch (error) {
     if (typeof error?.code === "string" && error.code.startsWith("E_")) throw error; // already an oats error
@@ -488,13 +1058,177 @@ async function lsTree(repo, spec, { flags = [], path, ref, commit } = {}) {
   }
 }
 
+/** A session's recursive listing of <commit> (one `ls-tree -r -t -l -z` per cache repo and commit):
+ *  → Promise<{ list, pos } | null>, null without a session or when the listing failed (the output budget,
+ *  a timeout, anything) — every caller then falls back to today's per-path listing, so the index can
+ *  never raise an error per-path reading would not. `list` is in git's order: an entry, then (for a
+ *  tree) everything below it, contiguously. `pos` maps a path to its FIRST entry. */
+function treeIndex(repo, commit, ref) {
+  const session = repo.session;
+  if (!session) return null;
+  const k = `${repo.dir}\0${commit}`;
+  let index = session.trees.get(k);
+  if (!index) {
+    index = lsTree(repo, commit, { flags: ["-r", "-t"], ref, commit, maxBuffer: session.treeIndexBudget }).then((list) => {
+      if (!list) return null;
+      const pos = new Map();
+      list.forEach((e, i) => { if (!pos.has(e.path)) pos.set(e.path, i); });
+      return { list, pos };
+    }, () => null);
+    session.trees.set(k, index);
+  }
+  return index;
+}
+/** The index entries below the tree at `rel` ("" = the root), paths relative to it — what
+ *  `ls-tree -r -t <commit>:<rel>` lists, in the same order. */
+function indexDescendants(index, rel) {
+  if (!rel) return index.list;
+  const i = index.pos.get(rel);
+  if (i === undefined) return [];
+  const prefix = `${rel}/`, out = [];
+  for (let j = i + 1; j < index.list.length && index.list[j].path.startsWith(prefix); j++) out.push({ ...index.list[j], path: index.list[j].path.slice(prefix.length) });
+  return out;
+}
+
 /** Return the single ls-tree entry for <commit>:<path>, or null when absent. */
 async function entryAt(repo, commit, path, ref) {
+  const index = await treeIndex(repo, commit, ref);
+  if (index) { const i = index.pos.get(path); return i === undefined ? null : index.list[i]; }
   const entries = await lsTree(repo, commit, { path, ref, commit });
   if (!entries) return null;
   return entries.find((e) => e.path === path) ?? null;
 }
 
+/** Kill our own, still-running child (never a pid a failed spawn left at 0: lib/process-group.mjs). */
+function killChild(child) {
+  if (child.exitCode === null && child.signalCode === null) killGroup(child, "SIGKILL");
+}
+
+/**
+ * A session's `git cat-file --batch` for one cache repo: read(oid, budget) → Promise<Buffer>. Spawned
+ * like repo.local (same `-C <dir> -c gc.auto=0`, cwd, helper-free gitEnv()); unref'd while idle, so it
+ * never keeps the process alive. A header over `budget` rejects that request with `{ oversize }` and its
+ * body is skipped, never buffered; a non-blob answers as `cat-file blob` would ("bad file"). `missing`,
+ * the child dying (or never starting: ENOENT), or no answer within GIT_TIMEOUT_MS rejects EVERY pending
+ * request with a git-shaped error (classifyRemoteFailure reads it as today: timeout → "timeout") and
+ * ends the child; the next read starts a new one.
+ */
+function openBatch(dir, timeoutMs = GIT_TIMEOUT_MS) {
+  // Detached, as its own process group: killChild's group kill also ends what git started (a lazy fetch).
+  const child = spawn("git", ["-C", dir, "-c", "gc.auto=0", "cat-file", "--batch"], { cwd: dir, env: gitEnv(), detached: true, stdio: ["pipe", "pipe", "pipe"] });
+  const queue = [];                    // { resolve, reject, budget, size? }
+  let chunks = [], length = 0, skip = 0, stderr = "", timer = null, dead = null, exited = null;
+  const exitedPromise = new Promise((r) => { exited = r; });
+  const handles = [child, child.stdin, child.stdout, child.stderr];
+  const idle = () => { for (const h of handles) h?.unref?.(); };
+  const busy = () => { for (const h of handles) h?.ref?.(); };
+  const arm = () => {
+    clearTimeout(timer); timer = null;
+    if (!queue.length) { idle(); return; }
+    timer = setTimeout(() => die(Object.assign(new Error(`git cat-file --batch: no answer within ${timeoutMs} ms`), { killed: true, signal: "SIGKILL", timedOut: true, stderr: Buffer.from(stderr) })), timeoutMs);
+  };
+  const die = (error) => {
+    if (dead) return;
+    dead = error; reader.dead = true;
+    clearTimeout(timer); timer = null;
+    killChild(child);
+    while (queue.length) queue.shift().reject(error);
+    idle();
+  };
+  const take = (n) => {
+    const out = Buffer.allocUnsafe(n);
+    let off = 0;
+    while (off < n) {
+      const c = chunks[0], k = Math.min(c.length, n - off);
+      c.copy(out, off, 0, k); off += k;
+      if (k === c.length) chunks.shift(); else chunks[0] = c.subarray(k);
+    }
+    length -= n;
+    return out;
+  };
+  const drop = (n) => {
+    length -= n;
+    while (n > 0) { const c = chunks[0]; if (c.length <= n) { n -= c.length; chunks.shift(); } else { chunks[0] = c.subarray(n); n = 0; } }
+  };
+  const lineEnd = () => { let off = 0; for (const c of chunks) { const i = c.indexOf(10); if (i >= 0) return off + i; off += c.length; } return -1; };
+  const pump = () => {
+    for (;;) {
+      if (skip > 0) { const n = Math.min(skip, length); drop(n); skip -= n; if (skip > 0) return; }
+      if (!length) return;
+      const head = queue[0];
+      if (!head) { die(Object.assign(new Error("git cat-file --batch: unexpected output"), { stderr: Buffer.from(stderr) })); return; }
+      if (head.size === undefined) {
+        const nl = lineEnd();
+        if (nl < 0) { if (length > 4096) die(Object.assign(new Error("git cat-file --batch: malformed header"), { stderr: Buffer.from(stderr) })); return; }
+        const line = take(nl + 1).toString("utf8").slice(0, -1);
+        const [name, type, sizeText, ...rest] = line.split(" ");
+        if (type === "missing" || type === undefined) { die(Object.assign(new Error(line), { code: 128, stderr: Buffer.from(`fatal: Not a valid object name ${name}\n`) })); return; }
+        const size = Number(sizeText);
+        if (rest.length || !Number.isSafeInteger(size) || size < 0) { die(Object.assign(new Error(`git cat-file --batch: malformed header ${JSON.stringify(line)}`), { stderr: Buffer.from(stderr) })); return; }
+        if (type !== "blob") { queue.shift().reject(Object.assign(new Error(`${name} is a ${type}`), { code: 128, stderr: Buffer.from(`fatal: git cat-file ${name}: bad file\n`) })); skip = size + 1; arm(); continue; }
+        if (size > head.budget) { queue.shift().reject(Object.assign(new Error(`${name} is ${size} bytes`), { oversize: size })); skip = size + 1; arm(); continue; }
+        head.size = size;
+      }
+      if (length < head.size + 1) return;
+      const body = take(head.size);
+      drop(1); // the LF after every body
+      queue.shift().resolve(body);
+      arm();
+    }
+  };
+  child.stdout.on("data", (chunk) => { chunks.push(chunk); length += chunk.length; pump(); });
+  child.stderr.on("data", (chunk) => { if (stderr.length < 65536) stderr += chunk.toString("utf8"); });
+  child.stdin.on("error", () => { /* EPIPE after the child died: 'close' reports it */ });
+  child.on("error", (error) => { die(error); exited(); });            // ENOENT and friends: never a hang
+  child.on("close", (code, signal) => { die(Object.assign(new Error(`git cat-file --batch exited (${signal ?? code})`), { code, signal, stderr: Buffer.from(stderr) })); exited(); });
+  idle();
+  const reader = {
+    dead: false,
+    read(oid, budget) {
+      if (dead) return Promise.reject(dead);
+      return new Promise((resolvePromise, reject) => {
+        queue.push({ resolve: resolvePromise, reject, budget });
+        busy();
+        if (queue.length === 1) arm();
+        child.stdin.write(`${oid}\n`);
+      });
+    },
+    /** End stdin; wait (bounded) for the child to go; kill it if it lingers. */
+    async close() {
+      reader.dead = true; // never handed out again; git still answers what it was already asked
+      if (!dead) { try { child.stdin.end(); } catch { /* already closed */ } }
+      if (child.exitCode !== null || child.signalCode !== null || child.pid === undefined) return;
+      const t = setTimeout(() => killChild(child), 2000);
+      await exitedPromise;
+      clearTimeout(t);
+    },
+    /** End it now (process exit, eviction): dead at once, so nothing is ever queued on it again. */
+    kill() { try { child.stdin.destroy(); } catch { /* nothing */ } die(Object.assign(new Error("git cat-file --batch was ended"), { stderr: Buffer.from(stderr) })); },
+  };
+  return reader;
+}
+
+/** The session's batch reader for this cache repo (least recently used idle ones closed beyond BATCH_LIMIT);
+ *  null without a session, after close(), or with an injected exec (tests keep per-blob reads). */
+function catFileBatch(repo) {
+  const session = repo.session;
+  if (!session || session.closed || repo.exec !== runGit) return null;
+  let reader = session.batches.get(repo.dir);
+  if (reader && !reader.dead) { session.batches.delete(repo.dir); session.batches.set(repo.dir, reader); return reader; }
+  reader = openBatch(repo.dir, session.batchTimeoutMs);
+  session.batches.set(repo.dir, reader);
+  if (session.batches.size > BATCH_LIMIT) {
+    for (const [dir, other] of session.batches) {
+      if (session.batches.size <= BATCH_LIMIT) break;
+      if (other === reader) continue;
+      session.batches.delete(dir);
+      session.retiring.add(other); // git answers what it was already asked, then ends on EOF
+      other.close().finally(() => session.retiring.delete(other));
+    }
+  }
+  return reader;
+}
+
 /**
  * → { bytes, size } | E_REMOTE_UNREADABLE | E_REMOTE_PATH_MISSING { path } | E_REMOTE_FILE_OVERSIZE { path, size, budget }
  * A symlink at <path> is refused (E_REMOTE_TREE_UNSAFE { path, why: "symlink" }); a directory → E_REMOTE_PATH_MISSING.
@@ -507,7 +1241,18 @@ export async function readRemoteFile(refText, commitArg, path, options = {}) {
   const entry = await entryAt(repo, commit, rel, ref);
   if (!entry || entry.type !== "blob") throw fail("E_REMOTE_PATH_MISSING", `${rel} is not a file in ${ref.key}@${commit.slice(0, 12)}`, { path: rel, key: ref.key, commit });
   if (entry.mode === "120000") throw fail("E_REMOTE_TREE_UNSAFE", `${rel} is a symlink`, { path: rel, why: "symlink", key: ref.key, commit });
-  if (entry.size > FILE_BUDGET) throw fail("E_REMOTE_FILE_OVERSIZE", `${rel} is ${entry.size} bytes (budget ${FILE_BUDGET})`, { path: rel, size: entry.size, budget: FILE_BUDGET, key: ref.key, commit });
+  const oversize = (size) => fail("E_REMOTE_FILE_OVERSIZE", `${rel} is ${size} bytes (budget ${FILE_BUDGET})`, { path: rel, size, budget: FILE_BUDGET, key: ref.key, commit });
+  if (entry.size > FILE_BUDGET) throw oversize(entry.size);
+  const batch = catFileBatch(repo);
+  if (batch) {
+    let bytes;
+    try { bytes = await batch.read(entry.oid, FILE_BUDGET); }
+    catch (error) {
+      if (error?.oversize !== undefined) throw oversize(error.oversize);
+      throw unreadable(ref, error, { commit, path: rel });
+    }
+    return { bytes, size: bytes.length };
+  }
   let out;
   try { out = await repo.local(["cat-file", "blob", entry.oid], { maxBuffer: FILE_BUDGET + 1024 }); }
   catch (error) { throw unreadable(ref, error, { commit, path: rel }); }
@@ -521,9 +1266,19 @@ export async function remoteTreeOids(refText, commitArg, dirs, options = {}) {
   const ref = parseRepoRef(refText, options);
   requireCommit(commitArg);
   const rels = dirs.map((dir) => normalizeTreePath(dir, { allowRoot: false }));
-  const { repo, commit } = await ensureCommit(ref, commitArg, options);
-  const entries = rels.length ? (await lsTree(repo, commit, { path: rels, ref, commit })) ?? [] : [];
-  return new Map(dirs.map((dir, i) => [dir, entries.find((e) => e.path === rels[i] && e.type === "tree")?.oid ?? null]));
+  // Pure at the commit: a session keeps the answer in the parsed cache (as [dir, oid] pairs).
+  const pairs = await memoAtCommit(ref, commitArg, `tree-oids\0${rels.join("\0")}`, async () => {
+    const { repo, commit } = await ensureCommit(ref, commitArg, options);
+    // One listing of nested paths (`a` beside `a/b`) recurses into `a` and never shows it: only the
+    // per-path listing reproduces that, so nested requests keep it.
+    const requested = new Set(rels);
+    const nested = rels.some((rel) => rel.split("/").slice(0, -1).some((_, i, parts) => requested.has(parts.slice(0, i + 1).join("/"))));
+    const index = rels.length && !nested ? await treeIndex(repo, commit, ref) : null;
+    if (index) return rels.map((rel) => { const i = index.pos.get(rel); return i !== undefined && index.list[i].type === "tree" ? index.list[i].oid : null; });
+    const entries = rels.length ? (await lsTree(repo, commit, { path: rels, ref, commit })) ?? [] : [];
+    return rels.map((rel) => entries.find((e) => e.path === rel && e.type === "tree")?.oid ?? null);
+  }, options);
+  return new Map(dirs.map((dir, i) => [dir, pairs[i]]));
 }
 
 /** A browsable URL of a repo at a commit (feature desktop-facts): the file's page with `path`, else the tree.
@@ -549,7 +1304,8 @@ export async function listRemoteTree(refText, commitArg, dir, { depth = 2, ...op
     const entry = await entryAt(repo, commit, rel, ref);
     if (!entry || entry.type !== "tree") return [];
   }
-  const entries = await lsTree(repo, spec, { flags: ["-r", "-t"], ref, commit });
+  const index = await treeIndex(repo, commit, ref);
+  const entries = index ? indexDescendants(index, rel) : await lsTree(repo, spec, { flags: ["-r", "-t"], ref, commit });
   if (!entries) return [];
   const result = [];
   for (const e of entries) {