@awebai/oats 0.32.0 → 0.34.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;
@@ -98,7 +117,15 @@
  *     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.
+ *   - the head observations used, for the `observation` output block;
+ *   - `deadline` (DEADLINE; the deployment reads `oats status` and `oats workspace status` only, READ_REMOTE_BUDGET_MS
+ *     after their session starts): every remote step gets what is left of it, not its own default — each git call's
+ *     timeout (ls-remote, fetch, ls-tree, the batch readers' answers, every cache plumbing call, the git version
+ *     probe), the cache write lock's wait, the half-initialised cache's wait and the lock-race backoff. A step the deadline ends is a
+ *     `timeout` (git's group killed as any timeout kills it; a step not started yet starts no git), so a member
+ *     not read by then degrades as any unreadable member does (a peel or version the deadline ended is a timeout,
+ *     never a missing commit or an older git). A wait the deadline cuts never changes what it judges: past it no
+ *     lock is taken or reclaimed, and a cache directory is not taken for a crash's leftover.
  *
  * 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
@@ -119,17 +146,28 @@ 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,
-  statSync, utimesSync, 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, relative, 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 } from "./process-group.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;
+/** The remote budget of a deployment read (`oats status`, `oats workspace status`): its session's `deadline` is
+ *  this long after the session starts, so the command answers inside a caller's own limit (the Desktop's 30 s). */
+export const READ_REMOTE_BUDGET_MS = 12_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). */
@@ -254,23 +292,50 @@ 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 (killed=true, signal SIGKILL, no error.code);
+ *   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.
  * An abort of `signal` rejects with an AbortError (code ABORT_ERR). git runs detached,
  * as its own process group: a timeout, an overflow or an abort kills the group, so
  * git's ssh or remote helper dies with it (a kill of git alone left them running until
- * their connection ended). Injectable via options.exec. */
-export function runGit(args, { cwd, maxBuffer = 16 * 1024 * 1024, timeout = GIT_TIMEOUT_MS, signal } = {}) {
+ * 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) => {
     if (signal?.aborted) { reject(abortError(signal)); return; }
-    // stdin is a pipe that is never written, as execFile gave it.
-    const child = spawn("git", args, { cwd, env: gitEnv(), detached: true, stdio: ["pipe", "pipe", "pipe"] });
+    // 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) });
@@ -283,20 +348,25 @@ export function runGit(args, { cwd, maxBuffer = 16 * 1024 * 1024, timeout = GIT_
     };
     const stop = (error) => {
       if (done) return;
-      killGroup(child);
-      child.stdin.destroy(); child.stdout.destroy(); child.stderr.destroy();
+      // 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: "SIGKILL", timedOut: true, overflowed: false })), timeout) : null;
+      { 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: "SIGKILL", overflowed: true, timedOut: false }));
+          { code: "ERR_CHILD_PROCESS_STDIO_MAXBUFFER", killed: true, signal: "SIGTERM", overflowed: true, timedOut: false }));
         return;
       }
       chunks.push(chunk); size[key] += chunk.length;
@@ -308,7 +378,7 @@ export function runGit(args, { cwd, maxBuffer = 16 * 1024 * 1024, timeout = GIT_
       if (code === 0) { settle(null, output()); return; }
       const { stdout, stderr } = output();
       settle(Object.assign(new Error(`Command failed: git ${args.join(" ")}\n${stderr.toString("utf8")}`),
-        { code, signal: exitSignal, killed: false, stdout, stderr, overflowed: false, timedOut: exitSignal === "SIGKILL" }));
+        { code, signal: exitSignal, killed: false, stdout, stderr, overflowed: false, timedOut: false }));
     });
   });
 }
@@ -317,17 +387,38 @@ function abortError(signal) {
   return Object.assign(new Error("The operation was aborted", { cause: signal?.reason }), { name: "AbortError", code: "ABORT_ERR", overflowed: false, timedOut: false });
 }
 
+/** A git call the session's deadline left no time for: shaped as runGit's own timeout (classified "timeout"). */
+function deadlineError(args) {
+  return Object.assign(new Error(`Command failed: git ${args.join(" ")} (the read budget ended before it ran)`),
+    { code: null, killed: false, signal: null, timedOut: true, overflowed: false, stdout: Buffer.alloc(0), stderr: Buffer.alloc(0) });
+}
+
+/** `exec(args, opts)` under the session's deadline: its timeout (opts.timeout, else GIT_TIMEOUT_MS) cut to what is
+ *  left, and no git started once nothing is. Without a deadline, exactly `exec(args, opts)`. */
+function sessionExec(exec, session, args, opts = {}) {
+  if (session?.deadline == null) return exec(args, opts);
+  const timeout = session.remaining(opts.timeout ?? GIT_TIMEOUT_MS);
+  if (timeout <= 0) return Promise.reject(deadlineError(args));
+  return exec(args, { ...opts, timeout });
+}
+
 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";
 }
 
@@ -341,8 +432,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 });
 }
 
 // ---------------------------------------------------------------------------
@@ -366,7 +493,188 @@ 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.
+ *  A session's deadline cuts the backoff: the next call then ends as its timeout (sessionExec). */
+async function retryLockRace(fn, session = null) {
+  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;
+      const backoff = Math.min(500, 50 * 2 ** attempt) * (0.5 + Math.random());
+      await sleep(session ? session.remaining(backoff) : backoff);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 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;
+  // The session's deadline ends the wait before anything is taken or reclaimed: the read is a timeout, and the
+  // lock (live, stale or unreadable) stays exactly as it is.
+  const budgetEnded = () => {
+    let now = held;
+    try { now = readCacheWriteLock(lock); } catch { /* as last seen */ }
+    const holder = now?.owner ? `oats process ${now.owner.pid}` : "another process";
+    return fail("E_REMOTE_UNREADABLE", `cannot write the cache of ${url} at ${dir} (timeout, ${stage}): the read budget ended ${now ? `while ${holder} held its write lock ${lock}` : `before it took its write lock ${lock}`}`,
+      { url: ref.url, key: ref.key, reason: "timeout", stage, cacheDir: dir, lock, ...(now?.owner ? { holderPid: now.owner.pid } : {}) });
+  };
+  for (let attempt = 0; ; attempt++) {
+    if (signal?.aborted) throw unreadable(ref, abortError(signal), { cacheDir: dir, stage });
+    if (session?.expired()) throw budgetEnded();
+    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) && !session?.expired()) {
+      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 } : {});
+    }
+    if (session?.expired()) throw budgetEnded();
+    waited = true;
+    const backoff = Math.min(250, 25 * 2 ** attempt) * (0.5 + Math.random());
+    await sleep(session ? Math.max(1, session.remaining(backoff)) : backoff);
+  }
+  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, repo.session); }
+  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();
@@ -378,23 +686,62 @@ function redactUrl(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 });
+  const local = (args, opts = {}) => sessionExec(exec, session, ["-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 dir = cacheDirOf(cacheRootOf(options), ref);
-  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 session = sessionOf(options);
+  if (!existsSync(join(dir, "HEAD"))) await initCacheRepo(ref, dir, exec, session);
+  return repoHandle(dir, exec, session);
+}
+
+/** 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, session = null) {
+  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 sessionExec(exec, session, ["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) {
+        // The session's deadline never shortens the judgment: a directory waited for less than the whole wait is
+        // never taken for a leftover. The read ends as a timeout instead.
+        if (session?.expired()) throw failInit(deadlineError(["init", "-q", "--bare", dir]));
+        await sleep(Math.max(1, Math.min(50, session ? session.remaining(50) : 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: redactUrl(ref.url) }, null, 2) + "\n", { flag: "wx" }); } catch {}
+  } finally {
+    rmSync(tmp, { recursive: true, force: true }); // gone already after a successful rename
   }
-  return repoHandle(dir, exec, sessionOf(options));
 }
 
 function pinRef(oid) { return `refs/oats/commits/${oid}`; }
@@ -404,14 +751,19 @@ function pinRef(oid) { return `refs/oats/commits/${oid}`; }
 // ---------------------------------------------------------------------------
 
 class ReadSession {
-  constructor({ maxAge = 0, now = Date.now, fingerprint = null, treeIndexBudget = TREE_INDEX_BUDGET, parsedLimits = null, batchTimeoutMs = GIT_TIMEOUT_MS } = {}) {
+  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, deadline = null } = {}) {
     if (!Number.isInteger(maxAge) || maxAge < 0 || maxAge > MAX_AGE_LIMIT) throw new TypeError(`maxAge must be an integer from 0 to ${MAX_AGE_LIMIT}`);
+    if (deadline !== null && !Number.isFinite(deadline)) throw new TypeError("deadline must be null or a time in Date.now() milliseconds");
     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.deadline = deadline;              // null, or when every remote step of the command must be over (remaining())
     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
@@ -426,6 +778,7 @@ class ReadSession {
     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;
   }
@@ -487,13 +840,20 @@ class ReadSession {
     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
   }
+  /** What a wait or a git call of `ms` may take: `ms`, cut to what is left before the deadline (never below 0).
+   *  Without a deadline, `ms` itself. */
+  remaining(ms) { return this.deadline === null ? ms : Math.max(0, Math.min(ms, this.deadline - Date.now())); }
+  /** Whether the deadline has passed: every remote step not over by then ends as a `timeout`. */
+  expired() { return this.remaining(Infinity) === 0; }
   /** 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`. */
+/** One command's read session (see the module header). `maxAge` seconds (0 = observe live). `deadline` (Date.now()
+ *  milliseconds, or null): every remote step ends by then (the module header's DEADLINE). 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. */
@@ -562,7 +922,7 @@ function resolvedVersion(name) {
   } catch { return "unresolved"; }
 }
 
-const TRANSIENT_REASONS = new Set(["timeout", "network", "auth", "unknown"]);
+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
@@ -782,11 +1142,11 @@ 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 dir = cacheDirOf(cacheRootOf(options), ref);
@@ -797,30 +1157,215 @@ async function ensureCommit(ref, oid, options) {
   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);
+    // 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 readVersion(repo, ref)) && 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 readVersion(repo, ref);
+    // 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
-    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 });
+    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) {
+      // A peel the session's deadline ended is the read's timeout, never a missing commit.
+      if (session?.expired()) throw unreadable(ref, deadlineError(["rev-parse", `${oid}^{commit}`]), { commit: oid, cacheDir: repo.dir, stage: "fetch" });
       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]);
+    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.
+ *  `opts` (a timeout, a signal) go to the call that asks. A call that timed out says nothing about this git:
+ *  it answers null to its waiters and is asked again next time. */
+const gitVersions = new WeakMap();
+export function gitVersion(exec = runGit, opts = undefined) {
+  let version = gitVersions.get(exec);
+  if (!version) {
+    version = Promise.resolve().then(() => exec(["--version"], ...(opts ? [opts] : []))).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;
+    }, (error) => {
+      if (error?.timedOut && gitVersions.get(exec) === version) gitVersions.delete(exec);
+      return null;
+    });
+    gitVersions.set(exec, version);
+  }
+  return version;
+}
+/** gitVersion for a read of `ref` in `repo`'s session. Under a deadline the probe gets what is left of it, and
+ *  is waited for no longer (another caller may own the probe): a version the deadline left unknown is the
+ *  read's timeout, never taken for an older git (which would rebuild a partial cache). */
+async function readVersion(repo, ref) {
+  const session = repo.session;
+  if (session?.deadline == null) return gitVersion(repo.exec);
+  const ended = () => unreadable(ref, deadlineError(["--version"]), { cacheDir: repo.dir, stage: "fetch" });
+  const left = session.remaining(GIT_TIMEOUT_MS);
+  if (left <= 0) throw ended();
+  let timer;
+  const late = new Promise((resolvePromise) => { timer = setTimeout(() => resolvePromise(ended), left); });
+  try {
+    const version = await Promise.race([gitVersion(repo.exec, { timeout: left, signal: session.signal }), late]);
+    if (version === ended || (version === null && session.expired())) throw ended();
+    return version;
+  } finally { clearTimeout(timer); }
+}
+/** 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);
   });
 }
 
@@ -977,7 +1522,7 @@ 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, ...(signal ? { signal } : {}) }); }
+  try { out = await sessionExec(exec, sessionOf(options), 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);
@@ -1003,7 +1548,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")) {
@@ -1011,7 +1557,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;
 }
@@ -1039,8 +1585,8 @@ 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, maxBuffer = 64 * 1024 * 1024 } = {}) {
   try {
@@ -1052,9 +1598,10 @@ async function lsTree(repo, spec, { flags = [], path, ref, commit, maxBuffer = 6
     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 } : {}) });
   }
 }
 
@@ -1099,9 +1646,10 @@ async function entryAt(repo, commit, path, ref) {
   return entries.find((e) => e.path === path) ?? null;
 }
 
-/** Kill our own, still-running child (never a pid a failed spawn left at 0: lib/process-group.mjs). */
+/** 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) killGroup(child, "SIGKILL");
+  if (child.exitCode === null && child.signalCode === null) terminateGroup(child);
 }
 
 /**
@@ -1109,13 +1657,15 @@ function killChild(child) {
  * 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.
+ * the child dying (or never starting: ENOENT), or no answer within GIT_TIMEOUT_MS (cut to what is left of
+ * `session`'s deadline) rejects EVERY pending request with a git-shaped error (classifyRemoteFailure reads it
+ * as today: timeout → "timeout") and ends the child; the next read starts a new one.
  */
-function openBatch(dir, timeoutMs = GIT_TIMEOUT_MS) {
-  // Detached, as its own process group: killChild's group kill also ends what git started (a lazy fetch).
-  const child = spawn("git", ["-C", dir, "-c", "gc.auto=0", "cat-file", "--batch"], { cwd: dir, env: gitEnv(), detached: true, stdio: ["pipe", "pipe", "pipe"] });
+function openBatch(dir, timeoutMs = GIT_TIMEOUT_MS, session = null) {
+  // 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; });
@@ -1125,7 +1675,8 @@ function openBatch(dir, timeoutMs = GIT_TIMEOUT_MS) {
   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 ms = session ? session.remaining(timeoutMs) : timeoutMs;
+    timer = setTimeout(() => die(Object.assign(new Error(`git cat-file --batch: no answer within ${ms} ms`), { killed: true, signal: "SIGKILL", timedOut: true, stderr: Buffer.from(stderr) })), ms);
   };
   const die = (error) => {
     if (dead) return;
@@ -1162,7 +1713,7 @@ function openBatch(dir, timeoutMs = GIT_TIMEOUT_MS) {
         if (nl < 0) { if (length > 4096) die(Object.assign(new Error("git cat-file --batch: malformed header"), { stderr: Buffer.from(stderr) })); return; }
         const line = take(nl + 1).toString("utf8").slice(0, -1);
         const [name, type, sizeText, ...rest] = line.split(" ");
-        if (type === "missing" || type === undefined) { die(Object.assign(new Error(line), { code: 128, stderr: Buffer.from(`fatal: Not a valid object name ${name}\n`) })); return; }
+        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; }
@@ -1215,7 +1766,8 @@ function catFileBatch(repo) {
   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);
+  if (session.expired()) return null; // a per-blob read, which ends as the deadline's timeout (sessionExec)
+  reader = openBatch(repo.dir, session.batchTimeoutMs, session);
   session.batches.set(repo.dir, reader);
   if (session.batches.size > BATCH_LIMIT) {
     for (const [dir, other] of session.batches) {
@@ -1242,6 +1794,7 @@ export async function readRemoteFile(refText, commitArg, path, options = {}) {
   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 });
   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) {
@@ -1290,7 +1843,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 } = {}) {
@@ -1316,14 +1870,48 @@ 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;
 }
 
+/**
+ * → { files: [{ path, size }], total } for the regular files (blobs) under <dir> at <commit>, recursively,
+ * relative to <dir>, sorted by path in codepoint order (feature capability-show): `total` of them in all, and
+ * `files` the first `limit` (every one without a limit). Symlinks and gitlinks are omitted; a name that could
+ * escape a checkout ANYWHERE below <dir> is refused (E_REMOTE_TREE_UNSAFE, as listRemoteTree), past the limit
+ * too. One listing (the session's tree index when it has one); the sizes a partial cache lacks are learned with
+ * ONE ensureBlobs call over the listed files only, so nothing past the limit is fetched. A missing dir, or one
+ * that is not a directory → { files: [], total: 0 }. Memoized at the commit (memoAtCommit), per limit.
+ */
+export async function listRemoteFiles(refText, commitArg, dir, { limit, ...options } = {}) {
+  const ref = parseRepoRef(refText, options);
+  requireCommit(commitArg);
+  if (limit !== undefined && (!Number.isInteger(limit) || limit < 0)) throw fail("E_REPO_REF", "limit must be a non-negative integer", { limit });
+  const rel = normalizeTreePath(dir, { allowRoot: true });
+  const none = { files: [], total: 0 };
+  return memoAtCommit(ref, commitArg, `files\0${rel}\0${limit ?? "all"}`, async () => {
+    const { repo, commit } = await ensureCommit(ref, commitArg, options);
+    if (rel) {
+      const entry = await entryAt(repo, commit, rel, ref);
+      if (!entry || entry.type !== "tree") return none;
+    }
+    const index = await treeIndex(repo, commit, ref);
+    const entries = index ? indexDescendants(index, rel) : await lsTree(repo, rel ? `${commit}:${rel}` : commit, { flags: ["-r"], ref, commit });
+    if (!entries) return none;
+    const blobs = [];
+    for (const e of entries) {
+      assertSafeEntryPath(e.path, ref, commit, rel ? `${rel}/${e.path}` : e.path);
+      if (e.type === "blob" && e.mode !== "120000") blobs.push({ ...e });
+    }
+    blobs.sort(byPath);
+    const listed = limit === undefined ? blobs : blobs.slice(0, limit);
+    await ensureBlobs(repo, ref, commit, listed);
+    return { files: listed.map((e) => ({ path: e.path, size: e.size })), total: blobs.length };
+  }, options);
+}
+
 // ---------------------------------------------------------------------------
 // digest
 // ---------------------------------------------------------------------------
@@ -1421,8 +2009,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
@@ -1439,12 +2027,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 {
@@ -1455,25 +2048,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 === "..") {