@awebai/oats 0.31.0 → 0.33.0

package/lib/remote.mjs

@@ -6,30 +6,41 @@
  *   1. `observeRemote` resolves `at` with `git ls-remote --symref <url> …` —
  *      never a fetch when the caller already gave a full OID.
  *   2. Every read (`readRemoteFile`, `listRemoteTree`, `fetchRemoteTree`) needs the
- *      commit's objects locally. `ensureCommit` does a shallow
- *      `git fetch --depth 1 --no-tags <url> <oid>` into a content-addressed BARE
- *      cache repo under `<cacheRoot>/<sha256(key)>/` and then pins the commit with
- *      `refs/oats/commits/<oid>` so `gc` cannot prune it. The pin doubles as the
- *      "already fetched" marker: a pinned commit is never fetched again.
+ *      commit locally. `ensureCommit` does a shallow, partial
+ *      `git fetch --depth 1 --no-tags --filter=blob:limit=64k origin <oid>` into a
+ *      content-addressed BARE cache repo under `<cacheRoot>/<sha256(key)>/` and then
+ *      pins the commit with `refs/oats/commits/<oid>` so `gc` cannot prune it (the
+ *      pins are also what a later fetch advertises as `have`, so it is incremental).
+ *      The commit arrives with ALL its trees (every listing is complete) and the blobs
+ *      up to SMALL_BLOB_LIMIT: every file discovery reads, in one round trip.
  *   3. Reads are then local plumbing: `git ls-tree -r -t -l -z` for listing and
- *      `git cat-file blob` for bytes. `git archive --remote` is NOT used: GitHub and
- *      most https hosts refuse it, and per-entry plumbing lets us inspect every
- *      mode (symlink / submodule / oversize) BEFORE anything touches the disk.
+ *      `git cat-file blob` for bytes. A read that needs a larger blob fetches it first
+ *      (`ensureBlobs`: one fetch by blob id per request, a whole subtree for
+ *      `fetchRemoteTree`); git never fetches one on its own (GIT_NO_LAZY_FETCH=1, and
+ *      the cache stores no url to fetch from). `git archive --remote` is NOT used:
+ *      GitHub and most https hosts refuse it, and per-entry plumbing lets us inspect
+ *      every mode (symlink / submodule / oversize) BEFORE anything touches the disk.
  *
- * DEVIATION FROM THE CONTRACT (named on purpose, not silently resolved): the
- * contract says "shallow git fetch --depth 1 --filter=blob:none". A blob-less
- * partial fetch would make every later `cat-file` a lazy per-blob network
- * round-trip through the promisor machinery, and topping a filtered commit up
- * to a full one afterwards requires `--refetch` semantics that vary by server.
- * We fetch depth-1 WITHOUT a blob filter: one round-trip per commit, blobs
- * present, correct on every server that allows fetching an advertised OID.
+ * PARTIAL CACHES (awebai/oats#384): the cache is a partial clone of the remote
+ * "origin" whose url is never written (it may carry credentials): every fetch passes
+ * it as `-c remote.origin.url=<url>`. `ls-tree -l` prints "BAD" for the size of a blob
+ * the cache lacks, so an unknown size is null until ensureBlobs fetches the blob, and
+ * every budget is applied to real sizes. A server that cannot serve partial fetches
+ * (no filter support; or blob wants refused, so the commit is fetched again with
+ * `--refetch`) gets whole trees from then on: the cache records `oats.fetch = full`,
+ * and the session's `notices` say so once. So does a git older than PARTIAL_FETCH_GIT
+ * (2.45, which brought GIT_NO_LAZY_FETCH): an older git would fetch a missing blob on
+ * its own or die, so every cache it touches fetches whole trees, and a partial cache it
+ * finds is deleted and fetched again whole (rebuildWhole). A lost `.lock` race on the
+ * cache repo's config or objects (another process starting the same cache) is retried.
  *
  * The cache is invisible plumbing: it may be wiped at any time (a wiped cache
  * simply re-fetches), and nothing outside this module references it.
  *
  * Nothing here ever prompts: GIT_TERMINAL_PROMPT=0, GIT_ASKPASS=/usr/bin/false,
  * ssh ALWAYS in BatchMode — `-o BatchMode=yes` is appended to the operator's own
- * GIT_SSH_COMMAND / core.sshCommand (or to plain `ssh`). Timeout 30 s per call.
+ * GIT_SSH_COMMAND / core.sshCommand (or to plain `ssh`). Timeout 30 s per call;
+ * 10 minutes for the fetch of a commit (GIT_FETCH_TIMEOUT_MS).
  *
  * KEY vs URL (post-0.25.0 fix M2): the canonical KEY (`<host>/<path>`, lowercase
  * host, no scheme, no `.git`) is the identity everywhere — the same repo written
@@ -59,9 +70,17 @@
  * collide on a case-/normalization-insensitive filesystem (README.md vs
  * readme.md, NFC vs NFD) are E_REMOTE_TREE_UNSAFE { why: "collision" }.
  *
- * CONCURRENCY: per-key operations on one cache repo are serialized in-process
- * (two observes of the same remote never race `git init` or `fetch`), and a
- * fetch that loses an on-disk `.lock` race to another process is retried.
+ * CONCURRENCY (awebai/oats#386): per-key operations on one cache repo are serialized
+ * in-process (withCacheLock), and every WRITE to a cache repo (init, config, fetch, pin)
+ * holds its cross-process write lock `<cacheRoot>/.locks/<repo>.lock` (withCacheWriteLock):
+ * a live holder is waited for (bounded by a whole fetch) and never stolen from, a dead
+ * one is reclaimed; reads take no lock. A cache repo is created whole (init into a private
+ * directory, then rename). A git `.lock` met under the write lock belongs to an older
+ * kernel's live write (retried briefly) or to a git that was killed: one older than the
+ * longest fetch, inside the cache and a regular file, is removed (a session notice says
+ * so) and the write made once more; any other is E_REMOTE_UNREADABLE { reason: "cache" }
+ * naming it. git is ended with SIGTERM first (it removes its own locks), SIGKILL after a
+ * grace unless its group is seen empty first (process-group.mjs terminateGroup, watchGroup).
  *
  * CACHE PIN vs OBJECTS: the pin ref is the fast-path marker, but a wiped or
  * pruned object store is detected (`rev-parse <oid>^{commit}`) and refetched;
@@ -76,20 +95,77 @@
  *   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";
+  closeSync, existsSync, linkSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync,
+  statSync, unlinkSync, utimesSync, writeFileSync, writeSync, symlinkSync, readlinkSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { oatsError } from "./errors.mjs";
+import { killGroup, signalGroup, terminateGroup, watchGroup } 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
+/** A commit is fetched with its trees and the blobs up to this size; a read fetches any larger blob it needs. */
+export const SMALL_BLOB_LIMIT = 64 * 1024;
+/** The oldest git that keeps a partial cache honest: GIT_NO_LAZY_FETCH arrived in 2.45; an older git fetches a
+ *  missing blob on its own, or dies trying. With an older git every cache fetches whole trees. */
+export const PARTIAL_FETCH_GIT = [2, 45];
 export const GIT_TIMEOUT_MS = 30_000;
+/** The fetch of a commit into the cache: the first one transfers the commit's whole tree, which for a
+ *  large workspace host takes far longer than GIT_TIMEOUT_MS (awebai/oats#362). */
+export const GIT_FETCH_TIMEOUT_MS = 600_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
@@ -205,41 +281,118 @@ function gitEnv() {
     GIT_ASKPASS: "/usr/bin/false",
     GIT_SSH_COMMAND: sshCommand(),
     GIT_LITERAL_PATHSPECS: "1",
+    // A cache holds a commit's trees and its small blobs (SMALL_BLOB_LIMIT); a read fetches what else it needs
+    // first (ensureBlobs). git must never fetch a missing blob on its own, one round trip at a time.
+    GIT_NO_LAZY_FETCH: "1",
   };
 }
 
+/** Every git child this module started that has not exited yet (runGit's and the batch readers'): what
+ *  reapOnExit still has to end when the process exits. */
+const liveChildren = new Set();
+/** The exit path (`process.on("exit")`, ReadSession.closeNow) cannot wait for a timer, so the graceful kill
+ *  is done synchronously and bounded: every live git group gets SIGTERM, the process blocks for at most
+ *  EXIT_GRACE_MS (git removes its lock files on SIGTERM in far less), then SIGKILL ends what is left. A
+ *  child's pid cannot be reused meanwhile: Node has not reaped it. */
+const EXIT_GRACE_MS = 200;
+function reapOnExit() {
+  // A child stays tracked until its stdio closes: a leader that exited while a descendant still holds its pipes
+  // is still here, and its group still gets both signals.
+  const children = [...liveChildren];
+  if (!children.length) return;
+  for (const child of children) signalGroup(child, "SIGTERM");
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, EXIT_GRACE_MS);
+  for (const child of children) signalGroup(child, "SIGKILL");
+  liveChildren.clear();
+}
+
 /** 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 SIGTERM, no error.code); set by
+ *                our own timer only: a git that some other process killed (an OOM kill)
+ *                exits with its signal and timedOut false;
+ *   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). `input` is written to git's stdin, which is then closed. Injectable via options.exec. */
+export function runGit(args, { cwd, maxBuffer = 16 * 1024 * 1024, timeout = GIT_TIMEOUT_MS, input, 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: written with `input` and closed, else never written, as execFile gave it.
+    const child = watchGroup(spawn("git", args, { cwd, env: gitEnv(), detached: true, stdio: ["pipe", "pipe", "pipe"] }));
+    liveChildren.add(child);
+    child.once("close", () => liveChildren.delete(child));
+    if (input !== undefined) { child.stdin.on("error", () => { /* EPIPE after the child died: 'close' reports it */ }); child.stdin.end(input); }
+    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;
+      // SIGTERM first (git removes its lock files), SIGKILL after the grace. The error says which kill this
+      // is (`timedOut` for our own timer), never the signal that finally ended git.
+      terminateGroup(child);
+      // stdout and stderr are drained, never destroyed: 'close' must still wait for a descendant holding them, so
+      // terminateGroup's SIGKILL reaches it (and only it). Unref'd, they never keep the command alive.
+      child.stdin.destroy();
+      for (const s of [child.stdout, child.stderr]) { s.removeAllListeners("data"); s.resume(); s.unref?.(); }
+      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: "SIGTERM", 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: "SIGTERM", 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: false }));
+    });
   });
 }
 
+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 ?? "");
 }
 
-/** Classify a failed network git call into the contract's four reasons. A `maxBuffer`
+/** Classify a failed network git call into the contract's reasons. A `maxBuffer`
  * overflow is never a timeout (the child is killed in both cases; only the timeout kill
- * counts) — it falls through to the stderr text, else "network". */
+ * counts) — it falls through to the stderr text, else "network". A timeout is our own
+ * timer's kill (`timedOut`), whatever signal it sent. A git lock still held by another
+ * process (a lost race that outlived retryLockRace, or a dead process's stale lock) is
+ * "cache": a local cache write failed, nothing about the remote. Any other signal exit is
+ * "killed" (the system killed git, e.g. out of memory). */
 export function classifyRemoteFailure(error) {
   if (error?.overflowed === true || error?.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER") return classifyText(error) ?? "network";
-  if (error?.timedOut || error?.signal === "SIGKILL" || error?.signal === "SIGTERM") return "timeout";
+  if (error?.timedOut) return "timeout";
+  if (isLockRace(error) || isLocalWriteFailure(error)) return "cache";
+  if (typeof error?.signal === "string" && error.signal) return "killed";
   return classifyText(error) ?? "network";
 }
 
@@ -253,8 +406,44 @@ function classifyText(error) {
 }
 
 function unreadable(ref, error, extra = {}) {
-  const reason = classifyRemoteFailure(error);
-  return fail("E_REMOTE_UNREADABLE", `cannot read remote ${ref.url} (${reason})`, { url: ref.url, key: ref.key, reason, ...extra });
+  const reason = classifyRemoteFailure(error), killed = reason === "killed";
+  if (reason === "cache") return cacheFailure(ref, error, extra);
+  return fail("E_REMOTE_UNREADABLE", `cannot read remote ${ref.url} (${reason})${killed ? `: git was killed (signal ${error.signal})` : ""}`,
+    { url: ref.url, key: ref.key, reason, ...(killed ? { signal: error.signal } : {}), ...extra });
+}
+
+/** The lock file a git lock error names (`Unable to create '<path>.lock'`, `could not lock config file <path>`),
+ *  else null. */
+function lockFileOf(error, cwd = null) {
+  const text = stderrText(error);
+  const m = /Unable to create '([^']+\.lock)'/.exec(text) ?? /could not lock config file ([^:\s]+)/.exec(text);
+  if (!m) return null;
+  const file = m[1].endsWith(".lock") ? m[1] : `${m[1]}.lock`;
+  // git names a lock relative to its cwd (`could not lock config file config`), or as `<dir>/./refs/…`.
+  return isAbsolute(file) ? resolve(file) : cwd ? resolve(cwd, file) : file;
+}
+
+/** git could not write a file of the local cache repo (a FETCH_HEAD, a pack, an object it cannot open or
+ *  create: permissions, a directory in the way, a read-only or full disk): a fact about this machine, never
+ *  about the remote. Only local file wording counts: "Permission denied (publickey)" stays auth. */
+const isLocalWriteFailure = (error) => /cannot open '[^']+': |unable to create temporary file|insufficient permission for adding an object|no space left on device|read-only file system|unable to write (?:file|new|loose|sha1|index)|could not write (?:to|file|index)/i.test(stderrText(error));
+
+/** A write to the local cache repo failed — reason "cache" (a timeout stays "timeout"), never "network" — with a
+ *  message that says what to do: a lock still held names its file, safe to remove once no oats process runs;
+ *  any other failure carries git's own words. `extra.stage` says which write (init, pin, config, fetch). */
+function cacheFailure(ref, error, extra = {}) {
+  const url = redactUrl(ref.url);
+  if (error?.timedOut) return fail("E_REMOTE_UNREADABLE", `cannot write the cache of ${url} (timeout)`, { url: ref.url, key: ref.key, reason: "timeout", ...extra });
+  const where = extra.cacheDir ? ` at ${extra.cacheDir}` : "";
+  const lock = isLockRace(error) ? lockFileOf(error, extra.cacheDir) : null;
+  if (isLockRace(error)) {
+    const held = lock ? `${lock} is still held` : "a git lock in it is still held";
+    return fail("E_REMOTE_UNREADABLE", `cannot write the cache of ${url}${where} (cache${extra.stage ? `, ${extra.stage}` : ""}): ${held} by another git process, or left by one that died; it is safe to remove once no oats or git process is running`,
+      { url: ref.url, key: ref.key, reason: "cache", ...extra, ...(lock ? { lock } : {}) });
+  }
+  const why = stderrText(error).trim().split("\n").filter(Boolean).join(" ") || error?.message || error?.code || "git failed";
+  const check = isLocalWriteFailure(error) ? `; check that ${extra.cacheDir ?? "the cache"} is writable by this user and its disk has room` : "";
+  return fail("E_REMOTE_UNREADABLE", `cannot write the cache of ${url}${where} (cache${extra.stage ? `, ${extra.stage}` : ""}): ${why}${check}`, { url: ref.url, key: ref.key, reason: "cache", ...extra });
 }
 
 // ---------------------------------------------------------------------------
@@ -278,27 +467,611 @@ 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));
+/** A write another process won (a git lock it holds, or the cache's `shallow` file it rewrote mid-fetch): a race
+ *  on the local cache, retried, and never a fact about the remote. */
+const isLockRace = (error) => /\.lock': File exists|Unable to create .*\.lock|another git process seems to be running|could not lock config file|shallow file has changed since we read it/i.test(stderrText(error));
+/** How long a git lock is waited for before it is judged. Every oats writer of this kernel holds the cache's
+ *  write lock (withCacheWriteLock), so a git lock met under it belongs to an older kernel's live write, or to a
+ *  git that was killed: the wait covers the first, short writes; a fetch's lock is judged by its age. */
+const LOCK_WAIT_MS = 3_000;
+/** Run `fn` (one git call that writes the cache repo), again after a lost on-disk `.lock` race, until
+ *  LOCK_WAIT_MS has passed (backoff up to 500 ms, jittered); a timeout or any other failure is never retried. */
+async function retryLockRace(fn) {
+  const deadline = Date.now() + LOCK_WAIT_MS;
+  for (let attempt = 0; ; attempt++) {
+    try { return await fn(); }
+    catch (error) {
+      if (!isLockRace(error) || error.timedOut) throw error;
+      if (Date.now() >= deadline) throw error;
+      await sleep(Math.min(500, 50 * 2 ** attempt) * (0.5 + Math.random()));
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// the cache write lock (cross-process)
+// ---------------------------------------------------------------------------
+
+/** How long a write waits for another live oats process writing the same cache: a whole fetch, and a margin. */
+const CACHE_WRITE_WAIT_MS = GIT_FETCH_TIMEOUT_MS + 60_000;
+/** A write lock with no readable owner (made by hand, or by a filesystem fault: ours is linked into place
+ *  whole) is judged by its age instead. */
+const UNREADABLE_LOCK_STALE_MS = 30_000;
+/** How old a git `*.lock` must be before a write holding the cache write lock may remove it: older than the
+ *  longest fetch any oats allows, so an older kernel's live fetch (it takes no write lock) is never broken. */
+const GIT_LOCK_STALE_MS = GIT_FETCH_TIMEOUT_MS + 60_000;
+
+function pidAlive(pid) { try { process.kill(pid, 0); return true; } catch (e) { return e.code === "EPERM"; } }
+
+/** The write lock of the cache repo `dir`: `<cacheRoot>/.locks/<repo>.lock`, outside git's own namespace. */
+const cacheWriteLockOf = (dir) => join(dirname(dir), ".locks", `${basename(dir)}.lock`);
+
+/** The write lock as { owner, ino, mtimeMs } (owner null when it holds no readable { pid, token }), or null
+ *  when it is gone. A symlink or anything but a regular file is an unreadable lock; a lock that cannot be read
+ *  at all (a directory in its place, EACCES) is thrown: retrying cannot clear it. */
+function readCacheWriteLock(path) {
+  let st;
+  try { st = lstatSync(path); } catch (error) { if (error.code === "ENOENT") return null; throw error; }
+  let owner = null;
+  if (st.isFile()) {
+    try { const o = JSON.parse(readFileSync(path, "utf8")); if (Number.isSafeInteger(o?.pid) && typeof o?.token === "string") owner = o; }
+    catch (error) { if (error.code === "ENOENT") return null; if (error.code && error.code !== "ENOENT" && !(error instanceof SyntaxError)) throw error; }
+  }
+  return { owner, ino: st.ino, mtimeMs: st.mtimeMs };
+}
+
+/**
+ * Run `fn` holding the cache repo's cross-process write lock (docs: oats-kernel-expert decision
+ * record-lock-liveness-tradeoff): every oats write to a cache repo — init, config, fetch, pin — happens under
+ * it, so two processes never write one cache at once; reads take no lock. The lock is an exclusive-create file
+ * holding { pid, token, startedAt }, linked into place whole. A live holder is waited for, never stolen from,
+ * whatever its age; a dead holder's lock (or an unreadable one past UNREADABLE_LOCK_STALE_MS) is removed after
+ * checking it is still the same file. Every pass that does not acquire falls through one deadline check and
+ * one sleep. At the deadline: E_REMOTE_UNREADABLE { reason: "cache", stage, cacheDir, lock, holderPid }; at once
+ * when a reclaimer died holding the reclaim guard (reclaimCacheWriteLock), with details.guard.
+ * `fn({ waited })`: whether another process held the lock first (what it wrote is worth checking again).
+ */
+async function withCacheWriteLock(ref, dir, stage, session, fn) {
+  const signal = session?.signal;
+  const lock = cacheWriteLockOf(dir);
+  const owner = { pid: process.pid, token: randomBytes(12).toString("hex"), startedAt: new Date().toISOString() };
+  const url = redactUrl(ref.url);
+  const refuse = (message, extra = {}) => fail("E_REMOTE_UNREADABLE", `cannot write the cache of ${url} at ${dir} (cache, ${stage}): ${message}`,
+    { url: ref.url, key: ref.key, reason: "cache", stage, cacheDir: dir, lock, ...extra });
+  try { mkdirSync(dirname(lock), { recursive: true, mode: 0o700 }); } catch (error) { throw refuse(`cannot create ${dirname(lock)} (${error.code ?? error.message})`); }
+  const deadline = Date.now() + (session?.cacheWriteWaitMs ?? CACHE_WRITE_WAIT_MS);
+  let held = null, waited = false;
+  for (let attempt = 0; ; attempt++) {
+    if (signal?.aborted) throw unreadable(ref, abortError(signal), { cacheDir: dir, stage });
+    const tmp = `${lock}.${owner.pid}.${owner.token}`;
+    try {
+      writeFileSync(tmp, JSON.stringify(owner) + "\n", { mode: 0o600 });
+      try { linkSync(tmp, lock); break; } catch (error) { if (error.code !== "EEXIST") throw error; }
+    } catch (error) { throw refuse(`cannot take its write lock ${lock} (${error.code ?? error.message})`); }
+    finally { try { unlinkSync(tmp); } catch { /* never written */ } }
+    try { held = readCacheWriteLock(lock); } catch (error) { throw refuse(`cannot read its write lock ${lock} (${error.code ?? error.message}); remove it if no oats process is running`); }
+    if (held && isStaleLock(held)) {
+      const abandoned = reclaimCacheWriteLock(lock, held, owner);
+      if (abandoned) {
+        throw refuse(`${abandoned.guard} was left by ${abandoned.pid ? `oats process ${abandoned.pid}, which died` : "an oats process that died"} while reclaiming the write lock ${lock}; it is safe to remove once no oats process is running`,
+          { guard: abandoned.guard, ...(held.owner ? { holderPid: held.owner.pid } : {}) });
+      }
+    }
+    if (Date.now() >= deadline) {
+      throw refuse(held?.owner ? `oats process ${held.owner.pid} has been writing it since ${held.owner.startedAt} (lock ${lock}); try again once it finishes`
+        : `its write lock ${lock} is held; it is safe to remove once no oats process is running`, held?.owner ? { holderPid: held.owner.pid } : {});
+    }
+    waited = true;
+    await sleep(Math.min(250, 25 * 2 ** attempt) * (0.5 + Math.random()));
+  }
+  try { return await fn({ waited }); }
+  finally {
+    // Release only our own lock: one reclaimed from us meanwhile belongs to its new holder.
+    try { if (readCacheWriteLock(lock)?.owner?.token === owner.token) unlinkSync(lock); } catch { /* gone */ }
+  }
+}
+
+/** Whether a lock record (readCacheWriteLock) is provably abandoned: its owner's pid is gone, or it has no
+ *  readable owner and is older than UNREADABLE_LOCK_STALE_MS. A live owner is never stale, whatever its age. */
+const isStaleLock = (held) => (held.owner ? !pidAlive(held.owner.pid) : Date.now() - held.mtimeMs > UNREADABLE_LOCK_STALE_MS);
+/** The same record still at `path`: the same owner token, or (no readable owner) the same file. */
+const sameLock = (now, held) => (held.owner ? now?.owner?.token === held.owner.token : now && !now.owner && now.ino === held.ino && now.mtimeMs === held.mtimeMs);
+
+/**
+ * Remove the write lock `held`, proven stale — serialized among reclaimers by the guard `<lock>.reclaim`
+ * (exclusive create, holding { pid, token }). Under the guard the lock is read again and removed only if it is
+ * still that stale record. Only a reclaimer ever removes another process's lock, and reclaimers hold the guard,
+ * so the lock cannot change between that check and the unlink: a reclaimer that paused cannot delete the lock a
+ * live process took meanwhile. A live guard is waited for (the caller's next pass). A guard whose holder died
+ * (or unreadable and old) is never removed: removing it would race exactly as removing the lock does, with no
+ * guard left to serialize that, so two reclaimers could each delete the other's live guard, then lock. It is
+ * returned instead, { guard, pid }, and the caller refuses naming it: a reclaimer dying inside its guard is a
+ * microseconds window, and a human removing the file once no oats process runs is the safe recovery. Any other
+ * failure leaves the lock to the caller's next pass and its deadline. → null, or the abandoned guard.
+ */
+function reclaimCacheWriteLock(lock, held, me) {
+  const guard = `${lock}.reclaim`;
+  try { writeFileSync(guard, JSON.stringify({ pid: me.pid, token: me.token }) + "\n", { flag: "wx", mode: 0o600 }); }
+  catch (error) {
+    if (error?.code !== "EEXIST") return null;
+    try { const g = readCacheWriteLock(guard); if (g && isStaleLock(g)) return { guard, pid: g.owner?.pid ?? null }; } catch { /* next pass */ }
+    return null;
+  }
+  try {
+    const now = readCacheWriteLock(lock);
+    if (now && sameLock(now, held) && isStaleLock(now)) unlinkSync(lock);
+  } catch { /* next pass */ }
+  finally { try { if (readCacheWriteLock(guard)?.owner?.token === me.token) unlinkSync(guard); } catch { /* gone */ } }
+  return null;
+}
+
+/** Remove the git lock file `lockFile` that a cache write met, if — and only if — it provably belongs to no live
+ *  writer: it is inside this cache repo, ends in `.lock`, is a regular file (never a symlink), and is older than
+ *  GIT_LOCK_STALE_MS. Called only while holding the cache write lock (no oats writer of this kernel can hold it).
+ *  → whether it was removed. */
+function reclaimGitLock(repo, lockFile) {
+  if (typeof lockFile !== "string" || !lockFile.endsWith(".lock") || !isAbsolute(lockFile)) return false;
+  let root, parent;
+  try { root = realpathSync(repo.dir); parent = realpathSync(dirname(lockFile)); } catch { return false; }
+  if (parent !== root && !parent.startsWith(root + sep)) return false;
+  const file = join(parent, basename(lockFile));
+  let st;
+  try { st = lstatSync(file); } catch { return false; }
+  if (!st.isFile() || Date.now() - st.mtimeMs <= GIT_LOCK_STALE_MS) return false;
+  try { unlinkSync(file); return true; } catch { return false; }
+}
+
+/** One git call that writes the cache repo (config, fetch, update-ref), made while holding its write lock:
+ *  a lost lock race (an older kernel's write) is retried briefly; a git lock that outlives that and is
+ *  provably stale (reclaimGitLock: a git killed mid-write) is removed — said once as a session notice — and
+ *  the call made once more. Anything else is thrown as git raised it. */
+async function cacheGit(repo, args, opts = {}) {
+  const run = () => repo.local(args, opts);
+  try { return await retryLockRace(run); }
+  catch (error) {
+    const lockFile = isLockRace(error) ? lockFileOf(error, repo.dir) : null;
+    if (!lockFile || !reclaimGitLock(repo, lockFile)) throw error;
+    repo.session?.notices.push(`removed a stale git lock ${lockFile} (left by a git process that was killed mid-write)`);
+    return await run();
+  }
+}
+
+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"));
-  if (!existsSync(join(dir, "HEAD"))) {
-    mkdirSync(dir, { recursive: true, mode: 0o700 });
-    try { await exec(["init", "-q", "--bare", dir]); }
-    catch (error) {
-      // 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" });
+  const dir = cacheDirOf(cacheRootOf(options), ref);
+  if (!existsSync(join(dir, "HEAD"))) await initCacheRepo(ref, dir, exec);
+  return repoHandle(dir, exec, sessionOf(options));
+}
+
+/** How long a cache directory without HEAD is waited for (an older kernel initialising it in place) before it
+ *  is taken for a crash's leftover and replaced. */
+const HALF_INIT_WAIT_MS = 2_000;
+
+/**
+ * Create the cache repo at `dir` in one atomic step: `git init --bare` into a private sibling directory, then
+ * rename it into place, so `dir` never exists half-initialised. Processes racing to create one cache all
+ * succeed: a loser's rename finds the winner's complete repo and drops its own copy. A directory at `dir`
+ * without HEAD (a crash's leftover, or an older kernel initialising in place) is waited for (bounded), then
+ * moved aside and replaced; the cache is disposable. Any other failure is E_REMOTE_UNREADABLE
+ * { reason: "cache", stage: "init", cacheDir }.
+ */
+async function initCacheRepo(ref, dir, exec) {
+  const failInit = (error) => cacheFailure(ref, error, { cacheDir: dir, stage: "init" });
+  const tmp = `${dir}.init-${process.pid}-${randomBytes(4).toString("hex")}`;
+  try {
+    try { mkdirSync(tmp, { recursive: true, mode: 0o700 }); } catch (error) { throw failInit(error); }
+    try { await exec(["init", "-q", "--bare", tmp]); } catch (error) { throw failInit(error); }
+    try { writeFileSync(join(tmp, "oats-remote.json"), JSON.stringify({ key: ref.key, url: redactUrl(ref.url) }, null, 2) + "\n"); } catch {}
+    const deadline = Date.now() + HALF_INIT_WAIT_MS;
+    for (;;) {
+      try { renameSync(tmp, dir); return; } // replaces nothing, or an EMPTY directory
+      catch (error) {
+        if (error?.code !== "ENOTEMPTY" && error?.code !== "EEXIST") throw failInit(error);
+      }
+      if (existsSync(join(dir, "HEAD"))) return; // another process created it first
+      if (Date.now() < deadline) { await sleep(50); continue; }
+      // No HEAD after the wait: a leftover. Move it aside (atomic; a process racing to do the same loses
+      // with ENOENT, which is fine) and take its place.
+      const aside = `${dir}.stale-${process.pid}-${randomBytes(4).toString("hex")}`;
+      try { renameSync(dir, aside); } catch (error) { if (error?.code !== "ENOENT") throw failInit(error); }
+      // A repo another process renamed in between the check and the move is complete: put it back.
+      if (existsSync(join(aside, "HEAD"))) { try { renameSync(aside, dir); continue; } catch { /* taken again meanwhile */ } }
+      rmSync(aside, { recursive: true, force: true });
     }
-    try { writeFileSync(join(dir, "oats-remote.json"), JSON.stringify({ key: ref.key, url: ref.url }, null, 2) + "\n", { flag: "wx" }); } catch {}
+  } finally {
+    rmSync(tmp, { recursive: true, force: true }); // gone already after a successful rename
   }
-  const local = (args, opts = {}) => exec(["-C", dir, "-c", "gc.auto=0", ...args], { cwd: dir, ...opts });
-  return { dir, exec, local };
 }
 
 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,
+    cacheWriteWaitMs = CACHE_WRITE_WAIT_MS, fetchTimeoutMs = GIT_FETCH_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.cacheWriteWaitMs = cacheWriteWaitMs; // tests shorten it: how long a write waits for another live writer of its cache
+    this.fetchTimeoutMs = fetchTimeoutMs;  // tests shorten it: a fetch's own timeout
+    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.notices = [];                     // what the command should tell the operator once it ends (the CLI prints them)
+    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();
+    reapOnExit(); // no timer runs on the exit path: SIGTERM, a bounded synchronous grace, then SIGKILL
+  }
+  /** 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`, `cacheWriteWaitMs`, `fetchTimeoutMs`. */
+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", "cache"]);
+/** 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.) */
@@ -314,40 +1087,206 @@ async function objectType(repo, oid) {
 }
 
 /**
- * Ensure <oid> (a full OID of a COMMIT, or of an annotated TAG that peels to one) and all
- * its trees/blobs are present in the cache. → { repo, commit } where `commit` is the PEELED
- * commit: a tag OID given as `at` is accepted, but the commit recorded everywhere is the
- * commit it points to (fix M4). The pin is on the peeled commit; a tag object gets its own
- * `refs/oats/tags/<oid>` pin so gc cannot break the chain either.
+ * Ensure <oid> (a full OID of a COMMIT, or of an annotated TAG that peels to one), its trees and its
+ * small blobs are present in the cache (larger blobs: ensureBlobs, when a read needs them). → { repo,
+ * commit } where `commit` is the PEELED commit: a tag OID given as `at` is accepted, but the commit
+ * recorded everywhere is the commit it points to (fix M4). The pin is on the peeled commit; a tag
+ * object gets its own `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
-    let lastError;
-    for (let attempt = 0; attempt < 3; attempt++) {
-      try {
-        await repo.local(["fetch", "-q", "--depth", "1", "--no-tags", "--no-recurse-submodules", ref.url, oid]);
-        lastError = null;
-        break;
-      } catch (error) {
-        lastError = error;
-        if (!isLockRace(error) || error.timedOut) break;
-        await sleep(100 * (attempt + 1) ** 2);
-      }
-    }
-    if (lastError) throw unreadable(ref, lastError, { commit: oid });
+    // Already present (the common case): a read, so no write lock.
+    let peeled = false; // the object store was asked already, and said no
+    const usable = async (repo) => {
+      if (!existsSync(join(dir, "HEAD"))) return null;
+      if (!keepsPartialCache(await gitVersion(repo.exec)) && await fetchMode(repo) === "partial") return null;
+      peeled = true;
+      return peelCommit(repo, oid);
+    };
+    const present = await usable(repoHandle(dir, options.exec ?? runGit, session));
+    if (present) return { repo: repoHandle(dir, options.exec ?? runGit, session), commit: remember(present) };
+    // Every write below (init, config, fetch, pin) holds the cache's cross-process write lock; a process that
+    // waited for it finds what the holder fetched.
+    return withCacheWriteLock(ref, dir, "fetch", session, async ({ waited }) => {
+    let repo = await cacheRepo(ref, options);
+    const version = await gitVersion(repo.exec);
+    // A partial cache is only safe where git cannot fetch a missing blob on its own: an older git rebuilds it whole.
+    if (!keepsPartialCache(version) && await fetchMode(repo) === "partial") repo = await rebuildWhole(repo, ref, options, version);
+    const cached = peeled && !waited ? null : await peelCommit(repo, oid);
+    if (cached) return { repo, commit: remember(cached) }; // pinned AND present AND (peels to) a commit
+    const mode = await fetchMode(repo)
+      ?? (keepsPartialCache(version) ? await startPartialFetches(repo, ref) : await recordFullFetches(repo, ref, olderGitNotice(version, ref)));
+    const filter = mode === "partial" ? [`--filter=${PARTIAL_FILTER}`] : ["--no-filter"];
+    const { stderr } = await fetchInto(repo, ref, ["fetch", "-q", "--depth", "1", "--no-tags", "--no-recurse-submodules", ...filter, "origin", oid], { what: oid, commit: oid });
+    // A server without filters says so and sends the whole tree: nothing is lost, the cache remembers.
+    if (mode === "partial" && /filtering not recognized by server/i.test(stderr.toString("utf8"))) await recordFullFetches(repo, ref);
     const commit = await peelCommit(repo, oid);
     if (!commit) {
       const type = await objectType(repo, oid);
       throw fail("E_REMOTE_UNREADABLE", `${oid} in ${ref.url} is ${type ? `a ${type}` : "missing"}, not a commit`, { url: ref.url, key: ref.key, reason: "not-found", commit: oid, type });
     }
-    await repo.local(["update-ref", pinRef(commit), commit]);
-    if (commit !== oid) await repo.local(["update-ref", `refs/oats/tags/${oid}`, oid]);
-    return { repo, commit };
+    await writePin(repo, ref, pinRef(commit), commit, commit);
+    if (commit !== oid) await writePin(repo, ref, `refs/oats/tags/${oid}`, oid, commit);
+    return { repo, commit: remember(commit) };
+    });
+  });
+}
+
+/** Pin `name` to `oid` in the cache repo. Two processes pinning one commit write the same value: a lost lock
+ *  race is retried, and a ref that already holds `oid` (another process's write) counts as written. */
+async function writePin(repo, ref, name, oid, commit) {
+  try { await cacheGit(repo, ["update-ref", name, oid]); }
+  catch (error) {
+    let current = null;
+    try { current = (await repo.local(["rev-parse", "--verify", "-q", name])).stdout.toString("utf8").trim(); } catch {}
+    if (current === oid) return;
+    throw cacheFailure(ref, error, { cacheDir: repo.dir, stage: "pin", commit });
+  }
+}
+
+/** The filter a partial fetch asks for: every blob up to SMALL_BLOB_LIMIT comes with the commit. */
+const PARTIAL_FILTER = `blob:limit=${SMALL_BLOB_LIMIT / 1024}k`;
+
+/** How this cache fetches (its own `oats.fetch` config): "partial", "full" (its server cannot serve
+ *  partial fetches), or null before its first fetch. */
+async function fetchMode(repo) {
+  try { return (await repo.local(["config", "--get", "oats.fetch"])).stdout.toString("utf8").trim() || null; } catch { return null; }
+}
+
+/** Make the cache a partial clone of the remote "origin". Its url is never written (it may carry
+ *  credentials): every fetch passes it with `-c remote.origin.url=` (fetchInto). */
+async function startPartialFetches(repo, ref) {
+  for (const [key, value] of [["core.repositoryformatversion", "1"], ["extensions.partialclone", "origin"], ["remote.origin.promisor", "true"],
+    ["remote.origin.partialclonefilter", PARTIAL_FILTER], ["oats.fetch", "partial"]]) await writeConfig(repo, ref, key, value);
+  return "partial";
+}
+
+/** One `git config <key> <value>` in the cache repo. Two processes starting one cache write the same values,
+ *  so a lost lock race is simply retried. */
+async function writeConfig(repo, ref, key, value) {
+  try { await cacheGit(repo, ["config", key, value]); }
+  catch (error) { throw unreadable(ref, error, { cacheDir: repo.dir, stage: "config" }); }
+}
+
+/** This cache fetches whole trees from now on (its server cannot serve partial fetches, or this git cannot keep
+ *  a partial cache): recorded, and said once (the session's notices; the CLI prints them when the command ends). */
+async function recordFullFetches(repo, ref, notice = `${redactUrl(ref.url)} does not serve partial fetches; OATS fetches whole trees from it`) {
+  await writeConfig(repo, ref, "oats.fetch", "full");
+  repo.session?.notices.push(notice);
+  return "full";
+}
+
+const olderGitNotice = (version, ref) =>
+  `git ${version?.text ?? "(unknown version)"} cannot keep a partial cache (it needs ${PARTIAL_FETCH_GIT.join(".")}); OATS fetches whole trees from ${redactUrl(ref.url)}`;
+
+/** `git --version` of the git `exec` runs, asked once per exec: → { text: "2.54.0", major, minor } | null. */
+const gitVersions = new WeakMap();
+export function gitVersion(exec = runGit) {
+  let version = gitVersions.get(exec);
+  if (!version) {
+    version = Promise.resolve().then(() => exec(["--version"])).then((out) => {
+      const m = /git version ((\d+)\.(\d+)[^\s]*)/.exec(out.stdout.toString("utf8"));
+      return m ? { text: m[1], major: Number(m[2]), minor: Number(m[3]) } : null;
+    }, () => null);
+    gitVersions.set(exec, version);
+  }
+  return version;
+}
+/** Whether this git keeps a partial cache honest (GIT_NO_LAZY_FETCH): an unknown version does not. */
+export function keepsPartialCache(version) {
+  const [major, minor] = PARTIAL_FETCH_GIT;
+  return version != null && (version.major > major || (version.major === major && version.minor >= minor));
+}
+
+/** Delete a partial cache an older git cannot read (it would fetch a missing blob on its own, or die), and start
+ *  it again recording whole-tree fetches. The cache is disposable: everything in it is fetched again. */
+async function rebuildWhole(repo, ref, options, version) {
+  const session = repo.session;
+  if (session) {
+    session.batches.get(repo.dir)?.kill();
+    session.batches.delete(repo.dir);
+    for (const map of [session.peels, session.trees]) for (const k of [...map.keys()]) if (k.startsWith(`${repo.dir}\0`)) map.delete(k);
+  }
+  rmSync(repo.dir, { recursive: true, force: true });
+  const fresh = await cacheRepo(ref, options);
+  await recordFullFetches(fresh, ref, olderGitNotice(version, ref));
+  return fresh;
+}
+
+/** `git fetch` from the remote into the cache (args start at the subcommand and name the remote "origin"):
+ *  a lost on-disk `.lock` race is retried, a timeout names the fetch (`what`) and how long it ran, any other
+ *  failure is E_REMOTE_UNREADABLE (`raw`: the git error itself, for a caller that reads its stderr). → { stdout, stderr } */
+async function fetchInto(repo, ref, args, { what, commit, input, raw = false } = {}) {
+  const started = Date.now();
+  let lastError;
+  try { return await cacheGit(repo, ["-c", `remote.origin.url=${ref.url}`, ...args], { timeout: repo.session?.fetchTimeoutMs ?? GIT_FETCH_TIMEOUT_MS, ...(input !== undefined ? { input } : {}) }); }
+  catch (error) { lastError = error; }
+  if (lastError?.timedOut) {
+    const elapsedMs = Date.now() - started;
+    throw fail("E_REMOTE_UNREADABLE", `cannot read remote ${ref.url} (timeout): git fetch of ${what} timed out after ${Math.round(elapsedMs / 1000)} s`,
+      { url: ref.url, key: ref.key, reason: "timeout", commit, operation: "fetch", elapsedMs });
+  }
+  throw raw ? lastError : unreadable(ref, lastError, { commit, ...(classifyRemoteFailure(lastError) === "cache" ? { cacheDir: repo.dir, stage: "fetch" } : {}) });
+}
+
+/** The sizes of `oids` in the cache, one `cat-file --batch-check`: → Map oid → size, null when the cache lacks it. */
+async function blobSizes(repo, oids) {
+  const out = (await repo.local(["cat-file", "--batch-check"], { input: oids.map((o) => `${o}\n`).join("") })).stdout.toString("utf8");
+  const sizes = new Map(oids.map((o) => [o, null]));
+  for (const line of out.split("\n")) {
+    const [oid, type, size] = line.split(" ");
+    if (sizes.has(oid) && type !== "missing" && /^[0-9]+$/.test(size ?? "")) sizes.set(oid, Number(size));
+  }
+  return sizes;
+}
+
+const isRefusedWant = (error) => /unadvertised object|not our ref|does not allow request|allow-(tip|reachable|any)-sha1-in-want/i.test(stderrText(error));
+
+/**
+ * Make the blobs of `entries` (ls-tree entries of `commit`) present before anything reads them: those
+ * whose size is unknown (null: the cache lacks them) are fetched in ONE fetch, by id, and every entry's
+ * `size` is then the blob's real size. A server that refuses wants of blobs by id gets the commit fetched
+ * again whole (`--refetch`), and the cache records it (recordFullFetches).
+ */
+async function ensureBlobs(repo, ref, commit, entries) {
+  const unknown = entries.filter((e) => e.size === null);
+  if (!unknown.length) return;
+  const oids = [...new Set(unknown.map((e) => e.oid))];
+  await withCacheLock(repo.dir, async () => {
+    let sizes = await blobSizes(repo, oids); // another read may have fetched them meanwhile
+    let wanted = oids.filter((o) => sizes.get(o) === null);
+    if (wanted.length) await withCacheWriteLock(ref, repo.dir, "fetch", repo.session, async ({ waited }) => {
+      if (waited) { // another process may have fetched them while this one waited
+        sizes = await blobSizes(repo, oids);
+        wanted = oids.filter((o) => sizes.get(o) === null);
+        if (!wanted.length) return;
+      }
+      const what = `${wanted.length} blob${wanted.length === 1 ? "" : "s"} at ${commit}`;
+      const refetch = () => fetchInto(repo, ref, ["fetch", "-q", "--refetch", "--no-filter", "--depth", "1", "--no-tags", "--no-recurse-submodules", "origin", commit], { what: commit, commit });
+      if (await fetchMode(repo) === "full") await refetch(); // a commit fetched partially before its server was found out
+      else {
+        try {
+          await fetchInto(repo, ref, ["-c", "fetch.negotiationAlgorithm=noop", "fetch", "-q", "--no-tags", "--no-write-fetch-head", "--stdin", "origin"],
+            { what, commit, input: wanted.map((o) => `${o}\n`).join(""), raw: true });
+        } catch (error) {
+          if (typeof error?.code === "string" && error.code.startsWith("E_")) throw error;
+          if (!isRefusedWant(error)) throw unreadable(ref, error, { commit, ...(classifyRemoteFailure(error) === "cache" ? { cacheDir: repo.dir, stage: "fetch" } : {}) });
+          await refetch();
+          await recordFullFetches(repo, ref);
+        }
+      }
+      sizes = await blobSizes(repo, oids);
+      const still = oids.find((o) => sizes.get(o) === null);
+      if (still) throw fail("E_REMOTE_UNREADABLE", `cannot read remote ${ref.url} (not-found): blob ${still} at ${commit} was not fetched`, { url: ref.url, key: ref.key, reason: "not-found", commit, oid: still });
+    });
+    for (const e of unknown) e.size = sizes.get(e.oid);
   });
 }
 
@@ -391,23 +1330,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);
@@ -433,7 +1469,8 @@ function normalizeTreePath(path, { allowRoot }) {
   return parts.join("/");
 }
 
-/** Parse `git ls-tree -l -z` output → [{ mode, type, oid, size, path }]. */
+/** Parse `git ls-tree -l -z` output → [{ mode, type, oid, size, path }]. `size` is null for a tree, and for a
+ *  blob the cache does not hold (git prints "BAD" for it and still succeeds): ensureBlobs learns it. */
 function parseLsTree(stdout) {
   const entries = [];
   for (const record of stdout.toString("utf8").split("\0")) {
@@ -441,7 +1478,7 @@ function parseLsTree(stdout) {
     const tab = record.indexOf("\t");
     const meta = record.slice(0, tab).trim().split(/\s+/), path = record.slice(tab + 1);
     const [mode, type, oid, size] = meta;
-    entries.push({ mode, type, oid, size: size === "-" ? null : Number(size), path });
+    entries.push({ mode, type, oid, size: /^[0-9]+$/.test(size) ? Number(size) : null, path });
   }
   return entries;
 }
@@ -469,32 +1506,200 @@ function assertNoCollisions(entries, ref, commit, prefix) {
 }
 
 /** `git ls-tree -l -z [flags] <spec> [-- <path>]`; null when <spec> names no tree.
- * 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
+ * Any other failure is E_REMOTE_UNREADABLE (reason "timeout" for the timeout kill, "killed"
+ * for any other signal exit, 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
     const text = stderrText(error).toLowerCase();
     if (/not a tree object|not a valid object name|does not exist|bad object|fatal: not a tree|path .* does not exist|exists on disk, but not in/.test(text)) return null;
-    const reason = error?.timedOut ? "timeout" : "unknown";
-    const why = error?.overflowed ? "listing exceeded the output budget" : (text.trim().split("\n")[0] || error?.code || error?.message || "git ls-tree failed");
-    throw fail("E_REMOTE_UNREADABLE", `cannot list ${spec}${path !== undefined ? ` -- ${path}` : ""} in ${ref?.key ?? repo.dir} (${reason}: ${why})`, { url: ref?.url ?? null, key: ref?.key ?? null, reason, commit: commit ?? null, spec, path: path ?? null, cause: error?.code ?? null, overflowed: error?.overflowed === true });
+    const killed = !error?.timedOut && !error?.overflowed && typeof error?.signal === "string" && error.signal !== "";
+    const reason = error?.timedOut ? "timeout" : killed ? "killed" : "unknown";
+    const why = error?.overflowed ? "listing exceeded the output budget" : killed ? `git was killed (signal ${error.signal})` : (text.trim().split("\n")[0] || error?.code || error?.message || "git ls-tree failed");
+    throw fail("E_REMOTE_UNREADABLE", `cannot list ${spec}${path !== undefined ? ` -- ${path}` : ""} in ${ref?.key ?? repo.dir} (${reason}: ${why})`, { url: ref?.url ?? null, key: ref?.key ?? null, reason, commit: commit ?? null, spec, path: path ?? null, cause: error?.code ?? null, overflowed: error?.overflowed === true, ...(killed ? { signal: error.signal } : {}) });
   }
 }
 
+/** 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;
 }
 
+/** End our own, still-running child gracefully (SIGTERM, then SIGKILL after the grace; never a pid a failed
+ *  spawn left at 0: lib/process-group.mjs). */
+function killChild(child) {
+  if (child.exitCode === null && child.signalCode === null) terminateGroup(child);
+}
+
+/**
+ * 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 anything git started.
+  const child = watchGroup(spawn("git", ["-C", dir, "-c", "gc.auto=0", "cat-file", "--batch"], { cwd: dir, env: gitEnv(), detached: true, stdio: ["pipe", "pipe", "pipe"] }));
+  liveChildren.add(child);
+  child.once("close", () => liveChildren.delete(child));
+  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`), missing: type === "missing" })); 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 +1712,19 @@ 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 });
+  await ensureBlobs(repo, ref, commit, [entry]);
+  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 +1738,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.
@@ -535,7 +1762,8 @@ export function browseUrl(key, commit, path = null) {
 }
 
 /**
- * → [{ path, type: "blob"|"tree", size? }] relative to <dir>, depth-bounded (depth 1 = direct children).
+ * → [{ path, type: "blob"|"tree"|"symlink" }] relative to <dir>, depth-bounded (depth 1 = direct children).
+ * A listing never needs a blob, so it never fetches one (and so carries no sizes).
  * Missing dir → []. Symlinks are reported as type "symlink" so callers can skip them.
  */
 export async function listRemoteTree(refText, commitArg, dir, { depth = 2, ...options } = {}) {
@@ -549,7 +1777,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) {
@@ -560,9 +1789,7 @@ export async function listRemoteTree(refText, commitArg, dir, { depth = 2, ...op
     assertSafeEntryPath(e.path, ref, commit, rel ? `${rel}/${e.path}` : e.path);
     if (e.type === "commit") continue; // submodule gitlinks are not part of the observable tree
     const type = e.mode === "120000" ? "symlink" : e.type;
-    const row = { path: e.path, type };
-    if (e.type === "blob") row.size = e.size;
-    result.push(row);
+    result.push({ path: e.path, type });
   }
   result.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
   return result;
@@ -665,8 +1892,8 @@ export async function fetchRemoteTree(refText, commitArg, dir, destDir, options
   }
   const entries = await lsTree(repo, spec, { flags: ["-r", "-t"], ref, commit });
   if (!entries) throw fail("E_REMOTE_PATH_MISSING", `${rel || "."} is missing in ${ref.key}@${commit.slice(0, 12)}`, { path: rel, key: ref.key, commit });
-  // Inspect everything BEFORE writing anything: names, modes, types, sizes, collisions.
-  let total = 0;
+  // Inspect everything BEFORE writing anything: names, modes, types, collisions, then (once the blobs
+  // are present) sizes.
   const blobs = [], trees = [], links = [];
   // `allowSymlinks(relPath)` (opt-in, narrow): a symlink whose TARGET is relative
   // and stays inside the fetched subtree may be materialized as a symlink — the
@@ -683,12 +1910,17 @@ export async function fetchRemoteTree(refText, commitArg, dir, destDir, options
     if (e.type === "commit") throw fail("E_REMOTE_TREE_UNSAFE", `${shown} is a submodule`, { path: shown, why: "device", key: ref.key, commit });
     if (e.type === "tree") { trees.push(e); continue; }
     if (e.type !== "blob" || !/^100(644|755)$/.test(e.mode)) throw fail("E_REMOTE_TREE_UNSAFE", `${shown} has unsupported mode ${e.mode}`, { path: shown, why: "device", key: ref.key, commit });
-    total += e.size;
-    if (total > TREE_BUDGET) throw fail("E_REMOTE_TREE_UNSAFE", `${rel || "."} exceeds ${TREE_BUDGET} bytes`, { path: rel || ".", why: "oversize", size: total, budget: TREE_BUDGET, key: ref.key, commit });
     blobs.push(e);
   }
-  blobs.sort(byPath);
   assertNoCollisions(entries, ref, commit, rel);
+  // Every blob of the subtree (files and link targets) in ONE fetch, then the budget on their real sizes.
+  await ensureBlobs(repo, ref, commit, [...blobs, ...links]);
+  let total = 0;
+  for (const b of blobs) {
+    total += b.size;
+    if (total > TREE_BUDGET) throw fail("E_REMOTE_TREE_UNSAFE", `${rel || "."} exceeds ${TREE_BUDGET} bytes`, { path: rel || ".", why: "oversize", size: total, budget: TREE_BUDGET, key: ref.key, commit });
+  }
+  blobs.sort(byPath);
   mkdirSync(dirname(dest), { recursive: true });
   const staging = join(dirname(dest), `.${dest.split(sep).pop()}.oats-staging-${process.pid}-${Date.now().toString(36)}`);
   try {
@@ -699,25 +1931,41 @@ export async function fetchRemoteTree(refText, commitArg, dir, destDir, options
     // the git tree listed first.
     const items = [...blobs.map((b) => ({ kind: "blob", e: b })), ...links.map((l) => ({ kind: "link", e: l }))].sort((a, b) => byPath(a.e, b.e));
     const d = createDigest();
+    // Blob bytes (all present now: ensureBlobs above): through the session's `cat-file --batch` reader when
+    // there is one (no process per blob), else one `cat-file blob` each. A reader opened before ensureBlobs
+    // fetched a blob still finds it (git re-reads its packs on a miss); one still missing answers `missing`
+    // (GIT_NO_LAZY_FETCH), never a fetch. A batch read may take what is left of TREE_BUDGET, never
+    // FILE_BUDGET (a single blob over 4 MiB still copies); a symlink target keeps its 64 KiB cap. A blob the
+    // reader answers `missing`, or over its budget, is read once more alone: that read's error is this path's
+    // error without a session, classified as it always was (the reader's own words are not git's). Any other
+    // failure, the reader dying or its session closing included, is E_REMOTE_UNREADABLE, as a per-blob read's is.
+    const LINK_BUDGET = 64 * 1024;
+    let read = 0;
+    const readBlob = async (oid, path, budget, maxBuffer) => {
+      const batch = catFileBatch(repo);
+      try {
+        if (batch) {
+          try { return await batch.read(oid, budget); }
+          catch (error) { if (error?.oversize === undefined && error?.missing !== true) throw error; }
+        }
+        return (await repo.local(["cat-file", "blob", oid], { maxBuffer })).stdout;
+      } catch (error) { throw unreadable(ref, error, { commit, path }); }
+    };
     for (const { kind, e } of items) {
       if (kind === "blob") {
         const b = e;
-        let out;
-        try { out = await repo.local(["cat-file", "blob", b.oid], { maxBuffer: TREE_BUDGET + 1024 }); }
-        catch (error) { throw unreadable(ref, error, { commit, path: b.path }); }
+        const bytes = await readBlob(b.oid, b.path, TREE_BUDGET - read, TREE_BUDGET + 1024);
+        read += bytes.length;
         const mode = b.mode === "100755" ? 0o755 : 0o644;
         const target = join(staging, ...b.path.split("/"));
         mkdirSync(dirname(target), { recursive: true, mode: 0o755 });
         const fd = openSync(target, "wx", mode);
-        try { writeSync(fd, out.stdout); } finally { closeSync(fd); }
-        d.add(b.path, mode, out.stdout);
+        try { writeSync(fd, bytes); } finally { closeSync(fd); }
+        d.add(b.path, mode, bytes);
         continue;
       }
       const l = e;
-      let out;
-      try { out = await repo.local(["cat-file", "blob", l.oid], { maxBuffer: 64 * 1024 }); }
-      catch (error) { throw unreadable(ref, error, { commit, path: l.path }); }
-      const linkTarget = out.stdout.toString("utf8").trim();
+      const linkTarget = (await readBlob(l.oid, l.path, LINK_BUDGET, LINK_BUDGET)).toString("utf8").trim();
       const from = dirname(l.path === "" ? "x" : l.path);
       const resolvedRel = posixNormalize(from === "." ? linkTarget : `${from}/${linkTarget}`);
       if (isAbsolute(linkTarget) || linkTarget.includes("\0") || resolvedRel.startsWith("../") || resolvedRel === "..") {