@awebai/oats 0.33.0 → 0.34.1

package/lib/remote.mjs

@@ -4,7 +4,11 @@
  * APPROACH (one approach, used for every remote kind — local bare repos and
  * https/ssh remotes alike):
  *   1. `observeRemote` resolves `at` with `git ls-remote --symref <url> …` —
- *      never a fetch when the caller already gave a full OID.
+ *      never a fetch when the caller already gave a full OID. A HEAD observation
+ *      speaks protocol v0 unless the operator pinned `protocol.version` (one round
+ *      trip instead of v2's two; what is kept of the advertisement is bounded, and a
+ *      remote over budget, or one that timed out under v0, is observed under v2:
+ *      observeLive).
  *   2. Every read (`readRemoteFile`, `listRemoteTree`, `fetchRemoteTree`) needs the
  *      commit locally. `ensureCommit` does a shallow, partial
  *      `git fetch --depth 1 --no-tags --filter=blob:limit=64k origin <oid>` into a
@@ -117,7 +121,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
@@ -157,6 +169,13 @@ 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;
+/** What OATS keeps of a v0 ref advertisement (git's stdout, `maxBuffer`). It bounds memory, not the wire: git
+ *  reads the whole advertisement before printing it, so one over budget is transferred once, then git is killed
+ *  and the remote observed under v2, its server-side filter, from then on (observeLive). */
+export const V0_ADVERTISEMENT_BUDGET = 4 * 1024 * 1024;
 /** 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). */
@@ -376,6 +395,21 @@ 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 ?? "");
@@ -475,15 +509,17 @@ const isLockRace = (error) => /\.lock': File exists|Unable to create .*\.lock|an
  *  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) {
+ *  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;
-      await sleep(Math.min(500, 50 * 2 ** attempt) * (0.5 + Math.random()));
+      const backoff = Math.min(500, 50 * 2 ** attempt) * (0.5 + Math.random());
+      await sleep(session ? session.remaining(backoff) : backoff);
     }
   }
 }
@@ -541,8 +577,18 @@ async function withCacheWriteLock(ref, dir, stage, session, fn) {
   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 });
@@ -550,7 +596,7 @@ async function withCacheWriteLock(ref, dir, stage, session, fn) {
     } 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)) {
+    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`,
@@ -561,8 +607,10 @@ async function withCacheWriteLock(ref, dir, stage, session, fn) {
       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;
-    await sleep(Math.min(250, 25 * 2 ** attempt) * (0.5 + Math.random()));
+    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 {
@@ -627,7 +675,7 @@ function reclaimGitLock(repo, lockFile) {
  *  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); }
+  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;
@@ -646,15 +694,16 @@ 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"))) await initCacheRepo(ref, dir, exec);
-  return repoHandle(dir, exec, sessionOf(options));
+  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
@@ -669,12 +718,12 @@ const HALF_INIT_WAIT_MS = 2_000;
  * 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) {
+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 exec(["init", "-q", "--bare", tmp]); } 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 (;;) {
@@ -683,7 +732,13 @@ async function initCacheRepo(ref, dir, exec) {
         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; }
+      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")}`;
@@ -705,8 +760,9 @@ 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,
-    cacheWriteWaitMs = CACHE_WRITE_WAIT_MS, fetchTimeoutMs = GIT_FETCH_TIMEOUT_MS } = {}) {
+    cacheWriteWaitMs = CACHE_WRITE_WAIT_MS, fetchTimeoutMs = GIT_FETCH_TIMEOUT_MS, deadline = null, v0AdvertisementBudget = V0_ADVERTISEMENT_BUDGET } = {}) {
     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();
@@ -715,6 +771,9 @@ class ReadSession {
     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.v0AdvertisementBudget = v0AdvertisementBudget; // tests lower it: the largest v0 ref advertisement read
+    this.protocolPins = new WeakMap();     // exec → Promise<whether protocol.version is pinned> (observeLive)
     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
@@ -793,12 +852,19 @@ class ReadSession {
     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`, `cacheWriteWaitMs`, `fetchTimeoutMs`. */
+/** 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`,
+ *  `v0AdvertisementBudget`. */
 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. */
@@ -1106,7 +1172,7 @@ async function ensureCommit(ref, oid, options) {
     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;
+      if (!keepsPartialCache(await readVersion(repo, ref)) && await fetchMode(repo) === "partial") return null;
       peeled = true;
       return peelCommit(repo, oid);
     };
@@ -1116,7 +1182,7 @@ async function ensureCommit(ref, oid, options) {
     // 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);
+    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);
@@ -1129,6 +1195,8 @@ async function ensureCommit(ref, oid, options) {
     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 });
     }
@@ -1186,19 +1254,41 @@ async function recordFullFetches(repo, ref, notice = `${redactUrl(ref.url)} does
 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. */
+/** `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) {
+export function gitVersion(exec = runGit, opts = undefined) {
   let version = gitVersions.get(exec);
   if (!version) {
-    version = Promise.resolve().then(() => exec(["--version"])).then((out) => {
+    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;
-    }, () => 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;
@@ -1311,7 +1401,7 @@ function parseLsRemote(stdout) {
 }
 
 function resolveAt(parsed, at) {
-  if (at === undefined || at === null || at === "" || at === "HEAD") {
+  if (isHeadAt(at)) {
     const oid = parsed.oids.get("HEAD");
     return oid ? { commit: oid, ref: parsed.symrefs.get("HEAD") ?? null } : null;
   }
@@ -1355,7 +1445,7 @@ export async function observeRemote(refText, { at, ...options } = {}) {
 
 /** 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";
+  const wantHead = isHeadAt(at);
   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");
@@ -1439,19 +1529,115 @@ async function observeInSession(ref, args, at, options, session, prefetch = null
   } finally { session.observeDone(); }
 }
 
+/** Whether `at` asks for the remote's default branch (a HEAD observation). */
+const isHeadAt = (at) => at === undefined || at === null || at === "" || at === "HEAD";
+
+/** Whether the operator pinned `protocol.version` (env, global, system or the working directory's repo config:
+ *  `git config --get`, in the observation's own environment): asked once per command (its session) and exec, or
+ *  once per exec without a session. Unset (exit 1) → false; any value, or a read that fails otherwise (an abort
+ *  included) → true: today's argv, never an error. */
+const protocolPins = new WeakMap();
+function protocolPinned(exec, session) {
+  const memo = session?.protocolPins ?? protocolPins;
+  let pinned = memo.get(exec);
+  if (!pinned) {
+    pinned = Promise.resolve().then(() => sessionExec(exec, session, ["config", "--get", "protocol.version"], { timeout: GIT_TIMEOUT_MS, ...(session ? { signal: session.signal } : {}) }))
+      .then(() => true, (error) => error?.code !== 1);
+    memo.set(exec, pinned);
+  }
+  return pinned;
+}
+
+/** The records that a remote is observed under protocol v2 only: `<cacheRoot>/.ls-remote/<sha256(key)>.<reason>.json`,
+ *  beside the cache repos and their `.locks/` (written when no cache repo exists yet, and gone with a wiped cache
+ *  root), each { protocol: "v2", reason, recordedAt }. `overflow` (its v0 advertisement is over budget) holds for
+ *  good; `timeout` (a v0 observation timed out, which load alone can cause) for LS_REMOTE_TIMEOUT_RECORD_MS. One
+ *  file per reason, so a timeout recorded by a command already in flight never replaces a permanent overflow.
+ *  Written atomically (temp + rename) with no lock: concurrent writers of one file write the same fact. A record
+ *  that cannot be read, is corrupt or has expired is no record: v0 is tried, never an error. */
+const LS_REMOTE_TIMEOUT_RECORD_MS = 7 * 24 * 3600 * 1000;
+const lsRemoteRecordFile = (root, ref, reason) => join(root, ".ls-remote", `${sha256(ref.key)}.${reason}.json`);
+function lsRemoteV2Recorded(root, ref, now) {
+  const record = (reason) => {
+    const rec = readStoreFile(lsRemoteRecordFile(root, ref, reason));
+    return rec && typeof rec === "object" && rec.protocol === "v2" && rec.reason === reason ? rec : null;
+  };
+  if (record("overflow")) return true;
+  const rec = record("timeout");
+  const at = typeof rec?.recordedAt === "string" ? Date.parse(rec.recordedAt) : NaN;
+  return Number.isFinite(at) && at <= now + 5000 && now - at < LS_REMOTE_TIMEOUT_RECORD_MS;
+}
+function recordLsRemoteV2(root, ref, reason, now) {
+  writeAtomicQuiet(lsRemoteRecordFile(root, ref, reason), JSON.stringify({ protocol: "v2", reason, recordedAt: new Date(now).toISOString() }) + "\n");
+}
+
+/** A v0 HEAD observation's failure that is final, exactly as under v2: the remote is slow, refuses us or has no
+ *  such repository, our cache failed, or the command gave the read up. Anything else is retried under v2. */
+const V0_FINAL_REASONS = new Set(["timeout", "auth", "not-found", "cache"]);
+
+/**
+ * `ls-remote` the remote and resolve `at`. A HEAD observation (`at` HEAD or unset) speaks protocol v0 when the
+ * operator has not pinned `protocol.version` and the remote has no v2 record: one round trip, the whole ref
+ * advertisement (`-c protocol.version=0 ls-remote --symref <url>`, no pattern), resolved to exactly what v2's
+ * filtered answer gives, HEAD's symref included (v0's symref capability).
+ *   - V0_ADVERTISEMENT_BUDGET bounds what is kept (`maxBuffer`), not what crosses the wire: git reads the whole
+ *     advertisement before it prints a ref. Over budget, git is killed, the remote is observed again under v2,
+ *     recorded for good (`overflow`) and said once: an over-budget remote costs its advertisement once.
+ *   - A v0 timeout is today's error (no retry, never a second timeout), recorded for a week (`timeout`) and said.
+ *   - Any other failure in V0_FINAL_REASONS (or an abort) is today's error; any other is retried once under v2
+ *     and said once if the retry succeeds.
+ * `args` (lsRemoteArgs) stays the observation's identity everywhere (records, memo keys) and is the v2 argv; tags
+ * and branches always use it.
+ */
 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 } : {}) }); }
-  catch (error) { throw unreadable(ref, error, { at: at ?? null }); }
+  const session = sessionOf(options);
+  const signal = session?.signal;
+  // Every git call takes what is left of the session's deadline, if it has one (sessionExec).
+  const run = (argv, extra = {}) => sessionExec(exec, session, argv, { timeout: GIT_TIMEOUT_MS, ...(signal ? { signal } : {}), ...extra });
+  const root = cacheRootOf(options);
+  const now = () => (session ? session.now() : Date.now());
+  const url = redactUrl(ref.url);
+  const say = (notice) => { if (session && !session.notices.includes(notice)) session.notices.push(notice); };
+  let out = null, retried = null;
+  const v0 = isHeadAt(at) && !lsRemoteV2Recorded(root, ref, now()) && !(await protocolPinned(exec, session));
+  // A command given up while its protocol was asked starts no ls-remote.
+  if (signal?.aborted) throw unreadable(ref, abortError(signal), { at: at ?? null });
+  if (v0) {
+    const budget = session?.v0AdvertisementBudget ?? V0_ADVERTISEMENT_BUDGET;
+    // A read whose timeout the command's deadline cuts (status, workspace status) may time out for that alone,
+    // which says nothing about the remote: its timeout is not recorded.
+    const cut = session ? session.remaining(GIT_TIMEOUT_MS) < GIT_TIMEOUT_MS : false;
+    try { out = await run(["-c", "protocol.version=0", "ls-remote", "--symref", ref.url], { maxBuffer: budget }); }
+    catch (error) {
+      if (error?.overflowed === true || error?.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER") {
+        recordLsRemoteV2(root, ref, "overflow", now());
+        say(`${url} sends a ref advertisement over ${formatBytes(budget)}; OATS observes it with protocol v2`);
+      } else {
+        const reason = classifyRemoteFailure(error);
+        const aborted = error?.code === "ABORT_ERR" || signal?.aborted;
+        if (!aborted && reason === "timeout" && !cut) {
+          recordLsRemoteV2(root, ref, "timeout", now());
+          say(`${url} timed out under protocol v0; OATS observes it with protocol v2 for 7 days`);
+        }
+        if (aborted || V0_FINAL_REASONS.has(reason)) throw unreadable(ref, error, { at: at ?? null });
+        retried = reason;
+      }
+    }
+  }
+  if (!out) {
+    try { out = await run(args); }
+    catch (error) { throw unreadable(ref, error, { at: at ?? null }); }
+  }
   const parsed = parseLsRemote(out.stdout);
   const hit = resolveAt(parsed, at);
   if (!hit) throw fail("E_REMOTE_UNREADABLE", `remote ${ref.url} has no ref matching ${at ?? "HEAD"}`, { url: ref.url, key: ref.key, reason: "not-found", at: at ?? null });
   if (!OID_RE.test(hit.commit)) throw fail("E_REMOTE_UNREADABLE", `remote ${ref.url} returned a non-OID for ${at ?? "HEAD"}`, { url: ref.url, key: ref.key, reason: "not-found", at: at ?? null });
   const { commit } = await ensureCommit(ref, hit.commit, options);
+  if (retried) say(`${url} failed under protocol v0 (${retried}); observed with protocol v2`);
   return { key: ref.key, url: ref.url, commit, ref: hit.ref, observedAt: new Date().toISOString() };
 }
+const formatBytes = (n) => (n % (1024 * 1024) === 0 ? `${n / (1024 * 1024)} MiB` : `${n} bytes`);
 
 // ---------------------------------------------------------------------------
 // tree reading
@@ -1578,11 +1764,11 @@ 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) {
+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);
@@ -1596,7 +1782,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;
@@ -1686,7 +1873,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) {
@@ -1795,6 +1983,42 @@ export async function listRemoteTree(refText, commitArg, dir, { depth = 2, ...op
   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
 // ---------------------------------------------------------------------------

package/lib/resolve.mjs

@@ -474,12 +474,29 @@ export function packageRef(id, entry, catalog, remote) {
 const SAFE_REL = (rel) => typeof rel === "string" && rel && !posix.isAbsolute(rel) && !/^[\\/]/.test(rel) && !/\0/.test(rel) && !rel.split(/[\\/]/).some((p) => p === "..");
 
 /** Normalize a manifest-declared relative path ("./skills/x/" → "skills/x"); null when unsafe. */
-function declaredPath(rel) {
+export function declaredPath(rel) {
   if (!SAFE_REL(rel)) return null;
   const n = posix.normalize(rel).replace(/\/+$/, "");
   return n === "." || n === "" || n.startsWith("../") ? null : n;
 }
 
+/** A relative path no listing of a checkout can hold: absolute, empty, a `.`/`..`/`.git` (any case) or empty
+ *  component, a trailing slash, a backslash or a NUL. */
+export function unsafeRelPath(path) {
+  if (typeof path !== "string" || path === "" || path.startsWith("/") || path.endsWith("/") || /[\\\0]/.test(path)) return true;
+  return path.split("/").some((c) => c === "" || c === "." || c === ".." || c.toLowerCase() === ".git");
+}
+
+/** A manifest-declared path as the module install reads it (lib/materialize.mjs modulePath: a backslash is a
+ *  separator, `./` and trailing slashes dropped), and only when the result is a safe POSIX path (unsafeRelPath);
+ *  else null. What `oats capabilities show` reports for an inject or a skill. */
+export function manifestFilePath(rel) {
+  const declared = declaredPath(rel);
+  if (!declared) return null;
+  const n = posix.normalize(declared.replace(/\\/g, "/")).replace(/^(?:\.\/)+/, "").replace(/\/+$/, "");
+  return unsafeRelPath(n) ? null : n;
+}
+
 /**
  * Skills declared by a manifest: each `skills[]` entry is a directory under the capability that either
  * IS a skill (holds SKILL.md) or holds skill directories (<entry>/<skill>/SKILL.md) — the same reading
@@ -525,14 +542,31 @@ async function enumerateSkills({ remote, ref, commit, dir, manifest, listing, mo
  *  would), commands and hooks. `skills` is null when its declared skills cannot be listed (a spawn of it
  *  would refuse; the listing does not). */
 export async function capabilityProvides({ ref, commit, dir, manifest, remote: injected, remoteOptions }) {
-  const remote = remoteOf({ remote: injected, remoteOptions });
   const keys = (o) => (isObject(o) ? Object.keys(o).sort(byCodepoint) : []);
-  let skills;
+  const { skills } = await capabilitySkills({ ref, commit, dir, manifest, remote: injected, remoteOptions });
+  return { skills: skills && skills.map((s) => s.name), commands: keys(manifest.commands), hooks: keys(manifest.hooks) };
+}
+
+/** A capability's skills as a spawn enumerates them (enumerateSkills), sorted by name in codepoint order:
+ *  → { skills: [{ name, path }] (path relative to the capability directory), problem: null }, or
+ *  { skills: null, problem } when the declared skills cannot be enumerated — `problem` the oats error a spawn
+ *  would meet (`missingCode`: E_CAPABILITY_MISSING for a member, E_PACKAGE_MANIFEST for a package), or a skill
+ *  path that is not safe (manifestFilePath). Paths are as the install reads them. The one reading of
+ *  `manifest.skills` behind `oats capabilities` (capabilityProvides) and `oats capabilities show`. */
+export async function capabilitySkills({ ref, commit, dir, manifest, remote: injected, remoteOptions, missingCode = "E_CAPABILITY_MISSING" }) {
+  const remote = remoteOf({ remote: injected, remoteOptions });
+  const missing = (raw, why, text) => fail(missingCode, `${manifest.capability} ${text}`, { capability: manifest.capability, skill: raw, why });
   try {
-    const missing = (raw, why, text) => fail("E_CAPABILITY_MISSING", text, { skill: raw, why });
-    skills = (await enumerateSkills({ remote, ref, commit, dir, manifest, moduleName: manifest.capability, missing })).map((x) => x.name).sort(byCodepoint);
-  } catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_")) skills = null; else throw e; }
-  return { skills, commands: keys(manifest.commands), hooks: keys(manifest.hooks) };
+    const skills = [];
+    for (const { name, path } of await enumerateSkills({ remote, ref, commit, dir, manifest, moduleName: manifest.capability, missing })) {
+      // A skill path is reported as the install reads it, and only when it is a safe POSIX path (a `.git`
+      // directory the remote serves is one a spawn's fetch refuses).
+      const safe = manifestFilePath(path);
+      if (!safe) throw missing(path, "unsafe", `declares skill ${show(name)} at ${show(path)}, which is not a safe path inside the capability`);
+      skills.push({ name, path: safe });
+    }
+    return { skills: skills.sort((a, b) => byCodepoint(a.name, b.name)), problem: null };
+  } catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_")) return { skills: null, problem: e }; throw e; }
 }
 
 /** The capability manifests of a locked package, read at its locked commit (feature desktop-facts). */
@@ -543,6 +577,20 @@ export async function lockedPackageCapabilities(id, entry, { catalog = null, rem
   return { ref, capabilities };
 }
 
+/** The lock must describe the tree it names: the capability list a package's manifests declare at the locked
+ *  commit (`capabilities`, readPackageManifests) must equal the lock entry's, and must hold `name`, else
+ *  E_PACKAGE_INTEGRITY. → that capability { name, dir, manifest }. Spawn's check (resolveSoul), shared with
+ *  `oats capabilities show`. */
+export function lockedCapability(name, id, entry, capabilities, details = { capability: name, id, version: entry.version, commit: entry.commit, path: entry.path }) {
+  const listed = capabilities.map((c) => c.name).sort(), locked = [...entry.capabilities].sort(); // validateLock guarantees the array
+  if (listed.length !== locked.length || listed.some((c, i) => c !== locked[i])) {
+    throw fail("E_PACKAGE_INTEGRITY", `${name}: the lock says package ${id} v${entry.version} provides [${locked.join(", ")}], but ${entry.path}/oats-package.json at ${short(entry.commit)} declares [${listed.join(", ")}]`, { ...details, why: "capabilities", listed, locked });
+  }
+  const cap = capabilities.find((c) => c.name === name);
+  if (!cap) throw fail("E_PACKAGE_INTEGRITY", `${name}: the lock says package ${id} v${entry.version} provides it, but ${entry.path}/oats-package.json at ${short(entry.commit)} does not`, { ...details, listed: capabilities.map((c) => c.name) });
+  return cap;
+}
+
 /* ───────────────────────────── resolveSoul ────────────────────────────── */
 
 /**
@@ -601,13 +649,7 @@ export async function resolveSoul(discovery, soulEntry, { local = null, lock = n
       const ref = packageRef(id, entry, catalog, remote);
       const details = { capability: name, id, version: entry.version, commit: entry.commit, path: entry.path };
       const { capabilities } = await readPackageManifests(remote, ref, entry.commit, entry.path, details);
-      // The lock must describe the tree it names: its capability list is what the package declares there.
-      const listed = capabilities.map((c) => c.name).sort(), locked = [...entry.capabilities].sort(); // validateLock guarantees the array
-      if (listed.length !== locked.length || listed.some((c, i) => c !== locked[i])) {
-        throw fail("E_PACKAGE_INTEGRITY", `${name}: the lock says package ${id} v${entry.version} provides [${locked.join(", ")}], but ${entry.path}/oats-package.json at ${short(entry.commit)} declares [${listed.join(", ")}]`, { ...details, why: "capabilities", listed, locked });
-      }
-      const cap = capabilities.find((c) => c.name === name);
-      if (!cap) throw fail("E_PACKAGE_INTEGRITY", `${name}: the lock says package ${id} v${entry.version} provides it, but ${entry.path}/oats-package.json at ${short(entry.commit)} does not`, { ...details, listed: capabilities.map((c) => c.name) });
+      const cap = lockedCapability(name, id, entry, capabilities, details);
       const layer = layerOf(cap.manifest);
       if (layer && emptied.has(layer) && via !== "soul") { turnedOff.push({ name, reason: "slot-none", slot: layer, overrides: fromOfVia(via) }); continue; }
       module = {

package/package-catalog.json

@@ -28,7 +28,7 @@
     },
     "oats.engineering": {
       "url": "https://github.com/awebai/oats-engineering.git",
-      "ref": "v1.4.0",
+      "ref": "v1.5.0",
       "path": "oats-package"
     },
     "oats.framework": {