filegrc 0.12.2 → 0.12.4

package/src/git.js

@@ -1,5 +1,6 @@
 import { execFileSync, spawn } from "node:child_process";
-import { randomUUID } from "node:crypto";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createHash, randomUUID } from "node:crypto";
 import { closeSync, constants, existsSync, fstatSync, fsyncSync, lstatSync, openSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { rm } from "node:fs/promises";
 import { devNull } from "node:os";
@@ -15,20 +16,47 @@ import { loadWorkspace } from "./workspace.js";
 const lastSuccessfulSynchronizations = new Map();
 const workspaceHistoryCache = new Map();
 const dataRecordHistoryIndexCache = new Map();
+let dataRecordHistoryIndexCacheBytes = 0;
 const historicalFileCache = new Map();
-const reachableDataAncestryCache = new Map();
 const dataHistoryContextCache = new WeakMap();
 const backgroundSynchronizations = new Map();
 const browserRemotePrefetches = new Map();
 const browserRemotePrefetchPromises = new Map();
 const repositorySnapshotPromises = new Map();
+const gitCommandCaches = new AsyncLocalStorage();
+const gitCommandDeadlines = new AsyncLocalStorage();
+const gitCommandCacheBytes = new WeakMap();
 let gitCommandInterceptor = null;
+let gitSubprocessObserver = null;
+let historicalBatchInterceptor = null;
+let historicalRevisionReadObserver = null;
 const BROWSER_REMOTE_PREFETCH_MAX_AGE_MS = 30_000;
 const GIT_DEFAULT_TIMEOUT_MS = 10_000;
 const GIT_REMOTE_TIMEOUT_MS = 30_000;
 const GIT_MAX_OUTPUT_BYTES = 20_000_000;
+const DATA_HISTORY_MAX_SOURCE_BYTES = 16 * 1024 * 1024;
+const DATA_HISTORY_MAX_SOURCE_REQUESTS = 20_000;
+const DATA_HISTORY_MAX_COMMITS = 5_000;
+const DATA_HISTORY_MAX_CHANGES = 20_000;
+const DATA_HISTORY_MAX_ANCESTRY_COMMITS = 20_000;
+const DATA_HISTORY_CACHE_MAX_BYTES = 64 * 1024 * 1024;
+const DATA_HISTORY_BUILD_TIMEOUT_MS = 10_000;
+const DATA_HISTORY_FAILURE_CACHE_MS = 2_000;
+const GIT_COMMAND_CACHE_MAX_ENTRIES = 128;
+const GIT_COMMAND_CACHE_MAX_BYTES = 4 * 1024 * 1024;
+const GIT_COMMAND_CACHE_MAX_ENTRY_BYTES = 512 * 1024;
 export const BROWSER_VALIDATION = Symbol("filegrc.browserValidation");
 
+export function withGitCommandCache(cache, callback) {
+  if (!(cache instanceof Map)) throw new TypeError("The Git command cache must be a Map.");
+  return gitCommandCaches.run(cache, callback);
+}
+
+export function withGitCommandDeadline(deadlineAt, callback) {
+  if (!Number.isFinite(deadlineAt)) throw new TypeError("The Git command deadline must be finite.");
+  return gitCommandDeadlines.run(deadlineAt, callback);
+}
+
 function gitEnvironment(overrides = {}) {
   return {
     ...Object.fromEntries(
@@ -102,6 +130,7 @@ export function getGitSummary(input = process.cwd()) {
       lastCommit: last
     };
   } catch (error) {
+    if (error?.code === "FILEGRC_GIT_DEADLINE") throw error;
     return {
       available: false,
       clean: null,
@@ -114,6 +143,8 @@ export function getGitSummary(input = process.cwd()) {
 export function getFileHistory(input, relativePath, limit = 50) {
   const root = resolveWorkspaceRoot(input);
   if (!isSafeDataGitPath(relativePath)) return null;
+  const indexed = indexedPathHistory(dataRecordHistoryIndexCache.get(root), relativePath);
+  if (indexed) return limitedHistory(indexed, limit);
   try {
     const countArgs = Number(limit) >= Number.MAX_SAFE_INTEGER
       ? []
@@ -128,7 +159,8 @@ export function getFileHistory(input, relativePath, limit = 50) {
     ]);
     if (!output) return [];
     return output.split("\n").map(parseLogLine);
-  } catch {
+  } catch (error) {
+    rethrowGitDeadline(error);
     return null;
   }
 }
@@ -136,6 +168,8 @@ export function getFileHistory(input, relativePath, limit = 50) {
 export function getFileHistoryWithPaths(input, relativePath, limit = 50) {
   const root = resolveWorkspaceRoot(input);
   if (!isSafeDataGitPath(relativePath)) return null;
+  const indexed = indexedPathHistory(dataRecordHistoryIndexCache.get(root), relativePath);
+  if (indexed) return limitedHistory(indexed, limit);
   try {
     const countArgs = Number(limit) >= Number.MAX_SAFE_INTEGER
       ? []
@@ -177,7 +211,8 @@ export function getFileHistoryWithPaths(input, relativePath, limit = 50) {
       }
     }
     return history;
-  } catch {
+  } catch (error) {
+    rethrowGitDeadline(error);
     return null;
   }
 }
@@ -185,6 +220,11 @@ export function getFileHistoryWithPaths(input, relativePath, limit = 50) {
 export function getFilePathAtRevision(input, relativePath, revision) {
   const root = resolveWorkspaceRoot(input);
   if (!isSafeDataGitPath(relativePath) || !/^[a-f0-9]{40}$/i.test(String(revision || ""))) return null;
+  const index = dataRecordHistoryIndexCache.get(root);
+  const indexed = indexedPathHistory(index, relativePath);
+  if (indexed) {
+    return indexed.find(({ commit }) => indexedAncestor(index, commit, revision))?.path || null;
+  }
   const history = getFileHistoryWithPaths(root, relativePath, Number.MAX_SAFE_INTEGER) || [];
   const summary = history.find(({ commit }) => commit === revision)
     || history.find(({ commit }) => isDataHistoryAncestor(root, commit, revision));
@@ -195,7 +235,8 @@ export function getDataCommitHistory(input) {
   const root = resolveWorkspaceRoot(input);
   try {
     return lines(git(root, ["log", "--reverse", "--format=%H", "--", "data"]));
-  } catch {
+  } catch (error) {
+    rethrowGitDeadline(error);
     return [];
   }
 }
@@ -220,7 +261,8 @@ export function getChangedDataJsonFilesAtRevision(input, revision) {
       paths.push(workspacePrefix ? repositoryPath.slice(workspacePrefix.length + 1) : repositoryPath);
     }
     return [...new Set(paths)];
-  } catch {
+  } catch (error) {
+    rethrowGitDeadline(error);
     return [];
   }
 }
@@ -234,53 +276,177 @@ export function getRecordIdentityHistories(input, ids) {
   return new Map([...new Set(ids)].map((id) => [id, index.historiesById.get(id) || []]));
 }
 
-export function getDataRecordHistoryIndex(input) {
+export function getDataRecordHistoryIndex(input, options = {}) {
   const root = resolveWorkspaceRoot(input);
-  const head = tryGit(root, ["rev-parse", "HEAD"]) || null;
   const cached = dataRecordHistoryIndexCache.get(root);
-  if (cached?.head === head) return cached;
+  const suppliedHead = /^[a-f0-9]{40}$/i.test(String(options.head)) ? String(options.head) : undefined;
+  if (
+    suppliedHead
+    && cached?.head === suppliedHead
+    && !cached.available
+    && cached.failureExpiresAt > performance.now()
+  ) return cached;
+  if (suppliedHead && cached?.head === suppliedHead && cached.available) return cached;
+  const hasDeadline = options.deadline !== undefined;
+  const deadline = hasDeadline ? Number(options.deadline) : performance.now() + DATA_HISTORY_BUILD_TIMEOUT_MS;
+  if (!Number.isFinite(deadline) || deadline <= performance.now()) {
+    const error = new Error("Git data history exceeded its cumulative time limit.");
+    error.code = "FILEGRC_HISTORY_DEADLINE";
+    throw error;
+  }
+  const remainingTime = () => {
+    const remainingMs = Math.floor(deadline - performance.now());
+    if (remainingMs <= 0) {
+      const error = new Error("Git data history exceeded its cumulative time limit.");
+      error.code = "FILEGRC_HISTORY_DEADLINE";
+      throw error;
+    }
+    return remainingMs;
+  };
+  const historyGit = (args) => git(root, args, { timeoutMs: remainingTime() });
+  const historyGitRaw = (args) => gitRaw(root, args, { timeoutMs: remainingTime() });
+  let head = null;
+  let discoveryError = null;
+  if (suppliedHead) {
+    head = suppliedHead;
+  } else {
+    try {
+      head = historyGit(["rev-parse", "HEAD"]) || null;
+    } catch (cause) {
+      rethrowGitDeadline(cause);
+      discoveryError = cause;
+    }
+  }
+  if (cached?.head === head && cached.available) return cached;
+  if (cached) {
+    dataRecordHistoryIndexCache.delete(root);
+    dataRecordHistoryIndexCacheBytes -= cached.cacheBytes || 0;
+  }
   const changes = [];
-  const shallow = head && tryGit(root, ["rev-parse", "--is-shallow-repository"]) === "true";
+  const sourceChanges = [];
+  const changesByCommit = new Map();
+  let shallow = false;
+  if (head) {
+    try {
+      shallow = historyGit(["rev-parse", "--is-shallow-repository"]) === "true";
+    } catch (cause) {
+      rethrowGitDeadline(cause);
+      discoveryError = cause;
+    }
+  }
   let available = Boolean(head) && !shallow;
-  let error = !head
+  let error = discoveryError || (!head
     ? new Error("Git history is unavailable because the workspace has no committed HEAD.")
-    : shallow ? new Error("Git history is shallow.") : null;
+    : shallow ? new Error("Git history is shallow.") : null);
+  if (discoveryError) available = false;
   try {
     if (available) {
-      const output = gitRaw(root, [
-        "log", "--reverse", "-m", "-z", "--relative",
-        "--format=%H%x00%cI%x00%an%x00%s%x00", "--name-status", "-M", "--", "data"
+      const output = historyGitRaw([
+        "log", "--topo-order", "--reverse", "--diff-merges=first-parent", "-z", "--relative",
+        "--format=%H%x00%cI%x00%an%x00%s%x00", "--name-status", "-M", head, "--", "data"
       ]);
-      changes.push(...parseDataRecordHistory(output));
+      const parsed = parseDataRecordHistory(output);
+      if (parsed.commitCount > DATA_HISTORY_MAX_COMMITS || parsed.changes.length > DATA_HISTORY_MAX_CHANGES) {
+        throw dataHistoryLimitError("Git data history is too large to reconcile safely.");
+      }
+      changes.push(...parsed.recordChanges);
+      sourceChanges.push(...parsed.sourceChanges);
+      for (const change of parsed.changes) {
+        if (!changesByCommit.has(change.summary.commit)) changesByCommit.set(change.summary.commit, []);
+        changesByCommit.get(change.summary.commit).push(change);
+      }
     }
   } catch (cause) {
+    rethrowGitDeadline(cause);
     available = false;
     error = cause;
   }
-  const sources = available
-    ? getFilesAtRevisions(
-      root,
-      changes.map(({ summary, path }) => ({ revision: summary.commit, relativePath: path })),
-      { batchSize: 512 }
-    )
-    : [];
+  let sources = [];
+  if (available) {
+    try {
+      sources = getFilesAtRevisions(
+        root,
+        sourceChanges.map(({ summary, path }) => ({ revision: summary.commit, relativePath: path })),
+        {
+          batchSize: 512,
+          maxRequests: DATA_HISTORY_MAX_SOURCE_REQUESTS,
+          maxTotalBytes: DATA_HISTORY_MAX_SOURCE_BYTES,
+          deadline
+        }
+      );
+    } catch (cause) {
+      rethrowGitDeadline(cause);
+      available = false;
+      error = cause;
+    }
+  }
   if (head && sources.some((source) => source === null)) {
     available = false;
     error ||= new Error("Git could not read every historical data record.");
   }
   const recordsByCommit = new Map();
   const historiesById = new Map();
+  const fileChangesByCommit = new Map();
+  const historicalRecordPaths = new Set();
+  const sourceByCommitAndPath = new Map();
+  sourceChanges.forEach(({ summary, path }, index) => {
+    sourceByCommitAndPath.set(`${summary.commit}\0${path}`, sources[index]);
+  });
+  for (const [commit, commitChanges] of changesByCommit) {
+    const fileChanges = new Map();
+    for (const change of commitChanges) {
+      if (change.beforePath?.match(/\.(?:json|md)$/) && change.beforePath !== change.afterPath) {
+        if (change.beforePath.endsWith(".json")) historicalRecordPaths.add(change.beforePath);
+        fileChanges.set(change.beforePath, null);
+      }
+      if (change.afterPath?.match(/\.(?:json|md)$/)) {
+        if (change.afterPath.endsWith(".json")) historicalRecordPaths.add(change.afterPath);
+        fileChanges.set(change.afterPath, sourceByCommitAndPath.get(`${commit}\0${change.afterPath}`) ?? null);
+      }
+    }
+    fileChangesByCommit.set(commit, fileChanges);
+  }
   for (let index = 0; index < changes.length; index += 1) {
     const { summary, path } = changes[index];
     try {
-      const record = JSON.parse(sources[index]);
-      if (!record?.id) continue;
+      const record = JSON.parse(sourceByCommitAndPath.get(`${summary.commit}\0${path}`));
+      if (!record || Array.isArray(record) || typeof record.id !== "string" || typeof record.type !== "string") {
+        throw new Error("Historical data records require string IDs and types.");
+      }
       if (!recordsByCommit.has(summary.commit)) recordsByCommit.set(summary.commit, new Map());
+      if (recordsByCommit.get(summary.commit).has(record.id)) {
+        throw new Error(`Historical data records reuse ID "${record.id}" in one commit.`);
+      }
       recordsByCommit.get(summary.commit).set(record.id, { record, path });
       if (!historiesById.has(record.id)) historiesById.set(record.id, []);
       historiesById.get(record.id).push({ ...summary, path });
-    } catch {
-      // Ignore malformed historical files.
+    } catch (cause) {
+      rethrowGitDeadline(cause);
+      available = false;
+      error = new Error(`Git history contains an unreadable data record at ${summary.commit.slice(0, 12)}:${path}.`, { cause });
+      break;
+    }
+  }
+  const parentsByCommit = new Map();
+  if (available) {
+    try {
+      for (const line of lines(historyGit(["rev-list", "--parents", head]))) {
+        const [commit, ...parents] = line.split(" ");
+        if (!/^[a-f0-9]{40}$/i.test(commit) || parents.some((parent) => !/^[a-f0-9]{40}$/i.test(parent))) {
+          throw new Error("Git returned invalid commit ancestry.");
+        }
+        parentsByCommit.set(commit, parents);
+        if (parentsByCommit.size > DATA_HISTORY_MAX_ANCESTRY_COMMITS) {
+          throw dataHistoryLimitError("Git ancestry is too large to reconcile safely.");
+        }
+      }
+      if (!parentsByCommit.has(head) || [...changesByCommit.keys()].some((commit) => !parentsByCommit.has(commit))) {
+        throw new Error("Git returned incomplete commit ancestry.");
+      }
+    } catch (cause) {
+      rethrowGitDeadline(cause);
+      available = false;
+      error = cause;
     }
   }
   for (const [id, history] of historiesById) {
@@ -297,13 +463,38 @@ export function getDataRecordHistoryIndex(input) {
     head,
     available,
     error,
-    commits: [...new Set(changes.map(({ summary }) => summary.commit))],
-    recordsByCommit,
-    historiesById
+    commits: available ? [...changesByCommit.keys()] : [],
+    changesByCommit: available ? changesByCommit : new Map(),
+    parentsByCommit: available ? parentsByCommit : new Map(),
+    fileChangesByCommit: available ? fileChangesByCommit : new Map(),
+    historicalRecordPaths: available ? historicalRecordPaths : new Set(),
+    recordsByCommit: available ? recordsByCommit : new Map(),
+    historiesById: available ? historiesById : new Map(),
+    sourceBytes: available
+      ? sources.reduce((total, source) => total + (typeof source === "string" ? Buffer.byteLength(source, "utf8") : 0), 0)
+      : 0,
+    ancestryCache: new Map(),
+    indexedFileCache: new Map()
   };
-  if (available) {
+  result.failureExpiresAt = available ? null : performance.now() + DATA_HISTORY_FAILURE_CACHE_MS;
+  result.estimatedBytes = available
+    ? result.sourceBytes * 3
+      + [...result.changesByCommit.values()].reduce((total, commitChanges) => total + commitChanges.length * 512, 0)
+      + result.parentsByCommit.size * 256
+      + [...result.historiesById.values()].reduce((total, history) => total + history.length * 128, 0)
+    : 512 + Buffer.byteLength(error?.message || "", "utf8");
+  result.cacheBytes = result.estimatedBytes;
+  if (result.estimatedBytes <= DATA_HISTORY_CACHE_MAX_BYTES) {
     dataRecordHistoryIndexCache.set(root, result);
-    while (dataRecordHistoryIndexCache.size > 16) dataRecordHistoryIndexCache.delete(dataRecordHistoryIndexCache.keys().next().value);
+    dataRecordHistoryIndexCacheBytes += result.cacheBytes;
+  }
+  if (dataRecordHistoryIndexCache.has(root)) {
+    while (dataRecordHistoryIndexCache.size > 4 || dataRecordHistoryIndexCacheBytes > DATA_HISTORY_CACHE_MAX_BYTES) {
+      const oldestRoot = dataRecordHistoryIndexCache.keys().next().value;
+      const oldest = dataRecordHistoryIndexCache.get(oldestRoot);
+      dataRecordHistoryIndexCache.delete(oldestRoot);
+      dataRecordHistoryIndexCacheBytes -= oldest?.cacheBytes || 0;
+    }
   }
   return result;
 }
@@ -311,6 +502,9 @@ export function getDataRecordHistoryIndex(input) {
 function parseDataRecordHistory(output) {
   const fields = output.split("\0");
   const changes = [];
+  const recordChanges = [];
+  const sourceChanges = [];
+  const commits = new Set();
   let index = 0;
   while (index < fields.length) {
     while (fields[index] === "") index += 1;
@@ -324,6 +518,8 @@ function parseDataRecordHistory(output) {
       throw new Error("Git returned an incomplete data-history header.");
     }
     const summary = { commit, shortCommit: commit.slice(0, 8), timestamp, author, subject };
+    if (commits.has(commit)) throw new Error("Git returned duplicate data-history commit output.");
+    commits.add(commit);
     while (index < fields.length) {
       while (fields[index] === "") index += 1;
       const rawStatus = fields[index];
@@ -337,29 +533,95 @@ function parseDataRecordHistory(output) {
       const renamed = status.startsWith("R") || status.startsWith("C");
       const second = renamed ? fields[index++] : null;
       if (!first || (renamed && !second)) throw new Error("Git returned an incomplete data-history path.");
-      if (status === "D") continue;
-      const path = renamed ? second : first;
-      if (path.startsWith("data/") && path.endsWith(".json")) {
+      const beforePath = status === "A" ? null : first;
+      const afterPath = status === "D" ? null : renamed ? second : first;
+      for (const path of [beforePath, afterPath].filter(Boolean)) {
         if (!isSafeDataGitPath(path)) throw new Error("Git returned an unsafe data-history path.");
-        changes.push({ summary, path });
       }
+      const change = { summary, status, beforePath, afterPath };
+      changes.push(change);
+      if (afterPath?.endsWith(".json")) {
+        recordChanges.push({ summary, path: afterPath });
+      }
+      if (afterPath?.endsWith(".json") || afterPath?.endsWith(".md")) {
+        sourceChanges.push({ summary, path: afterPath });
+      }
+    }
+  }
+  return { changes, recordChanges, sourceChanges, commitCount: commits.size };
+}
+
+function indexedPathHistory(index, relativePath) {
+  if (!index?.available) return null;
+  for (const history of index.historiesById.values()) {
+    if (history[0]?.path === relativePath) return history;
+  }
+  return null;
+}
+
+function limitedHistory(history, limit) {
+  if (Number(limit) >= Number.MAX_SAFE_INTEGER) return history;
+  return history.slice(0, Math.max(1, Math.min(Number(limit) || 50, 200)));
+}
+
+function indexedDataFile(index, revision, relativePath) {
+  if (
+    !index?.available
+    || !relativePath?.match(/\.(?:json|md)$/)
+    || !index.parentsByCommit.has(revision)
+  ) return undefined;
+  const key = `${revision}\0${relativePath}`;
+  if (index.indexedFileCache.has(key)) return index.indexedFileCache.get(key);
+  let commit = revision;
+  let source = null;
+  while (commit) {
+    const changes = index.fileChangesByCommit.get(commit);
+    if (changes?.has(relativePath)) {
+      source = changes.get(relativePath);
+      break;
     }
+    commit = index.parentsByCommit.get(commit)?.[0] || null;
+  }
+  index.indexedFileCache.set(key, source);
+  while (index.indexedFileCache.size > 20_000) index.indexedFileCache.delete(index.indexedFileCache.keys().next().value);
+  return source;
+}
+
+function indexedAncestor(index, ancestor, descendant) {
+  if (ancestor === descendant) return true;
+  const key = `${ancestor}\0${descendant}`;
+  if (index.ancestryCache.has(key)) return index.ancestryCache.get(key);
+  const pending = [descendant];
+  const visited = new Set();
+  let result = false;
+  while (pending.length) {
+    const commit = pending.pop();
+    if (commit === ancestor) {
+      result = true;
+      break;
+    }
+    if (visited.has(commit)) continue;
+    visited.add(commit);
+    pending.push(...(index.parentsByCommit.get(commit) || []));
   }
-  return changes;
+  index.ancestryCache.set(key, result);
+  while (index.ancestryCache.size > 20_000) index.ancestryCache.delete(index.ancestryCache.keys().next().value);
+  return result;
 }
 
 export function isGitAncestor(input, ancestor, descendant) {
   if (!/^[a-f0-9]{40}$/i.test(String(ancestor)) || !/^[a-f0-9]{40}$/i.test(String(descendant))) return false;
   const root = resolveWorkspaceRoot(input);
   try {
-    execFileSync("git", ["merge-base", "--is-ancestor", ancestor, descendant], {
+    observedExecFileSync("git", ["merge-base", "--is-ancestor", ancestor, descendant], {
       cwd: root,
       stdio: "ignore",
       timeout: 10_000,
       env: gitEnvironment()
     });
     return true;
-  } catch {
+  } catch (error) {
+    rethrowGitDeadline(error);
     return false;
   }
 }
@@ -372,18 +634,10 @@ export function isDataHistoryAncestor(input, ancestor, descendant) {
     index = getDataRecordHistoryIndex(root);
     if (context) dataHistoryContextCache.set(context, index);
   }
-  if (
-    !index.available
-    || (descendant !== index.head && !index.commits.includes(descendant))
-  ) return isGitAncestor(root, ancestor, descendant);
-  const key = `${root}\0${ancestor}\0${descendant}`;
-  if (reachableDataAncestryCache.has(key)) return reachableDataAncestryCache.get(key);
-  const result = isGitAncestor(root, ancestor, descendant);
-  reachableDataAncestryCache.set(key, result);
-  while (reachableDataAncestryCache.size > 20_000) {
-    reachableDataAncestryCache.delete(reachableDataAncestryCache.keys().next().value);
+  if (!index.available || !index.parentsByCommit.has(descendant)) {
+    return isGitAncestor(root, ancestor, descendant);
   }
-  return result;
+  return indexedAncestor(index, ancestor, descendant);
 }
 
 export function getFileBufferAtRevision(input, revision, relativePath) {
@@ -394,14 +648,15 @@ export function getFileBufferAtRevision(input, revision, relativePath) {
     const workspacePrefix = relative(topLevel, root).split(sep).join("/");
     if (workspacePrefix === ".." || workspacePrefix.startsWith("../")) return null;
     const repositoryPath = workspacePrefix ? `${workspacePrefix}/${relativePath}` : relativePath;
-    return execFileSync("git", ["show", `${revision}:${repositoryPath}`], {
+    return observedExecFileSync("git", ["show", `${revision}:${repositoryPath}`], {
       cwd: root,
       stdio: ["ignore", "pipe", "ignore"],
       timeout: 10_000,
       maxBuffer: 20_000_000,
       env: gitEnvironment()
     });
-  } catch {
+  } catch (error) {
+    rethrowGitDeadline(error);
     return null;
   }
 }
@@ -416,7 +671,8 @@ export function getFileObjectIdAtRevision(input, revision, relativePath) {
     const repositoryPath = workspacePrefix ? `${workspacePrefix}/${relativePath}` : relativePath;
     const objectId = git(root, ["rev-parse", `${revision}:${repositoryPath}`]);
     return /^[a-f0-9]{40}(?:[a-f0-9]{24})?$/i.test(objectId) ? objectId : null;
-  } catch {
+  } catch (error) {
+    rethrowGitDeadline(error);
     return null;
   }
 }
@@ -427,7 +683,8 @@ export function getWorkingFileObjectId(input, relativePath) {
   try {
     const objectId = git(root, ["hash-object", "--no-filters", "--", relativePath]);
     return /^[a-f0-9]{40}(?:[a-f0-9]{24})?$/i.test(objectId) ? objectId : null;
-  } catch {
+  } catch (error) {
+    rethrowGitDeadline(error);
     return null;
   }
 }
@@ -437,11 +694,28 @@ export function getWorkspaceHistories(input, relativePaths, limitPerFile = 12, o
   const wanted = new Set(relativePaths);
   const histories = new Map([...wanted].map((path) => [path, []]));
   if (!wanted.size) return histories;
-  const head = tryGit(root, ["rev-parse", "HEAD"]) || null;
+  const remainingTime = () => {
+    if (options.deadlineAt === undefined) return undefined;
+    const remaining = Math.ceil(options.deadlineAt - performance.now());
+    if (remaining > 0) return remaining;
+    const error = new Error("The Git history deadline expired before another subprocess could start.");
+    error.code = "FILEGRC_GIT_DEADLINE";
+    throw error;
+  };
+  const withinDeadline = (task) => options.deadlineAt === undefined
+    ? task()
+    : withGitCommandDeadline(options.deadlineAt, task);
+  let head = null;
+  try {
+    head = withinDeadline(() => git(root, ["rev-parse", "HEAD"], { timeoutMs: remainingTime() })) || null;
+  } catch (error) {
+    if (error?.code === "FILEGRC_GIT_DEADLINE") throw error;
+    head = null;
+  }
   const cached = workspaceHistoryCache.get(root);
   if (cached?.head === head && cached.limitPerFile === limitPerFile) {
     if (options.strict === true && cached.available === false) {
-      throw new Error("Git history is unavailable for the requested workspace files.");
+      throw gitHistoryUnavailableError();
     }
     for (const path of wanted) histories.set(path, cached.histories.get(path) ?? []);
     return histories;
@@ -449,7 +723,9 @@ export function getWorkspaceHistories(input, relativePaths, limitPerFile = 12, o
   const allHistories = new Map();
   let available = true;
   try {
-    const output = git(root, ["log", "--relative", "--format=%x1e%H%x1f%aI%x1f%an%x1f%s", "--name-only", "--", "data"]);
+    const output = withinDeadline(() => git(root, ["log", "--relative", "--format=%x1e%H%x1f%aI%x1f%an%x1f%s", "--name-only", "--", "data"], {
+      timeoutMs: remainingTime()
+    }));
     for (const block of output.split("\x1e")) {
       const lines = block.trim().split("\n").filter(Boolean);
       if (lines.length < 2) continue;
@@ -460,30 +736,64 @@ export function getWorkspaceHistories(input, relativePaths, limitPerFile = 12, o
         if (history.length < limitPerFile) history.push(commit);
       }
     }
-  } catch {
+  } catch (error) {
+    if (error?.code === "FILEGRC_GIT_DEADLINE") throw error;
     available = false;
     if (options.strict === true) {
-      throw new Error("Git history is unavailable for the requested workspace files.");
+      throw gitHistoryUnavailableError(error);
     }
     // Browser and workflow views tolerate an uncommitted workspace with no history yet.
   }
-  workspaceHistoryCache.set(root, { head, limitPerFile, histories: allHistories, available });
+  if (available) workspaceHistoryCache.set(root, { head, limitPerFile, histories: allHistories, available });
   for (const path of wanted) histories.set(path, allHistories.get(path) ?? []);
   return histories;
 }
 
+function gitHistoryUnavailableError(cause) {
+  const error = new Error("Git history is unavailable for the requested workspace files.", { cause });
+  error.code = "FILEGRC_GIT_HISTORY_UNAVAILABLE";
+  return error;
+}
+
 export function getFileAtRevision(input, revision, relativePath) {
-  return getFilesAtRevisions(input, [{ revision, relativePath }])[0];
+  const root = resolveWorkspaceRoot(input);
+  historicalRevisionReadObserver?.({ root, revision, relativePath });
+  const indexed = indexedDataFile(dataRecordHistoryIndexCache.get(root), revision, relativePath);
+  return indexed === undefined
+    ? getFilesAtRevisions(root, [{ revision, relativePath }])[0]
+    : indexed;
 }
 
 export function getFilesAtRevisions(input, requests, options = {}) {
   const root = resolveWorkspaceRoot(input);
+  const hasDeadline = options.deadline !== undefined;
+  const deadline = hasDeadline ? Number(options.deadline) : performance.now() + DATA_HISTORY_BUILD_TIMEOUT_MS;
+  if (!Number.isFinite(deadline) || deadline <= performance.now()) {
+    const error = new Error("Git historical file export exceeded its cumulative deadline.");
+    error.code = "FILEGRC_HISTORY_DEADLINE";
+    throw error;
+  }
+  const remainingTime = () => {
+    const remainingMs = Math.floor(deadline - performance.now());
+    if (remainingMs <= 0) {
+      const error = new Error("Git historical file export exceeded its cumulative deadline.");
+      error.code = "FILEGRC_HISTORY_DEADLINE";
+      throw error;
+    }
+    return remainingMs;
+  };
   const invalid = Array.isArray(requests) && requests.find(({ revision, relativePath } = {}) => (
     !/^[a-f0-9]{40}$/i.test(String(revision)) || !isSafeDataGitPath(relativePath)
   ));
   if (!Array.isArray(requests) || invalid) {
     throw new Error("Historical file exports require a Git commit and a data/ path.");
   }
+  const maxRequests = Number(options.maxRequests) > 0 ? Math.floor(Number(options.maxRequests)) : null;
+  if (maxRequests && requests.length > maxRequests) {
+    const error = new Error(`Git historical file exports exceed the ${maxRequests}-request safety limit.`);
+    error.code = "FILEGRC_HISTORY_EXPORT_LIMIT";
+    throw error;
+  }
   if (!requests.length) return [];
   const results = new Array(requests.length);
   const missing = [];
@@ -497,31 +807,49 @@ export function getFilesAtRevisions(input, requests, options = {}) {
       missing.push({ ...request, index, key });
     }
   });
+  const maxTotalBytes = Number(options.maxTotalBytes) > 0 ? Number(options.maxTotalBytes) : null;
+  const cachedBytes = maxTotalBytes
+    ? results.reduce((total, value) => total + (typeof value === "string" ? Buffer.byteLength(value, "utf8") : 0), 0)
+    : 0;
+  if (maxTotalBytes && cachedBytes > maxTotalBytes) throw historicalExportLimitError(maxTotalBytes);
   if (!missing.length) return results;
   try {
-    const topLevel = git(root, ["rev-parse", "--show-toplevel"]);
+    const topLevel = git(root, ["rev-parse", "--show-toplevel"], { timeoutMs: remainingTime() });
     const workspacePrefix = relative(topLevel, root).split(sep).join("/");
     if (workspacePrefix === ".." || workspacePrefix.startsWith("../")) return requests.map(() => null);
+    const missingSpecifications = missing.map(({ revision, relativePath }) => {
+      const repositoryPath = workspacePrefix ? `${workspacePrefix}/${relativePath}` : relativePath;
+      return `${revision}:${repositoryPath}`;
+    });
+    if (maxTotalBytes) {
+      assertHistoricalExportSize(root, missingSpecifications, maxTotalBytes - cachedBytes, maxTotalBytes, remainingTime());
+    }
     const batchSize = Math.max(1, Math.min(Number(options.batchSize) || 4, 512));
     for (let offset = 0; offset < missing.length; offset += batchSize) {
       const batch = missing.slice(offset, offset + batchSize);
-      const specifications = batch.map(({ revision, relativePath }) => {
-        const repositoryPath = workspacePrefix ? `${workspacePrefix}/${relativePath}` : relativePath;
-        return `${revision}:${repositoryPath}`;
-      });
+      const specifications = missingSpecifications.slice(offset, offset + batchSize);
       let values;
       try {
-        const output = measureTimingSync("git-history-export", () => execFileSync("git", ["cat-file", "--batch"], {
-          cwd: root,
-          input: `${specifications.join("\n")}\n`,
-          stdio: ["pipe", "pipe", "ignore"],
-          timeout: 10_000,
-          maxBuffer: 80_000_000,
-          env: gitEnvironment()
-        }));
+        const run = () => {
+          const remainingMs = remainingTime();
+          return observedExecFileSync("git", ["cat-file", "--batch"], {
+            cwd: root,
+            input: `${specifications.join("\n")}\n`,
+            stdio: ["pipe", "pipe", "ignore"],
+            timeout: remainingMs,
+            maxBuffer: 80_000_000,
+            env: gitEnvironment()
+          });
+        };
+        const output = measureTimingSync("git-history-export", () => (
+          historicalBatchInterceptor ? historicalBatchInterceptor({ root, specifications, run }) : run()
+        ));
         values = parseBatchObjects(output, batch.length);
-      } catch {
-        values = specifications.map((specification) => readHistoricalFile(root, specification));
+      } catch (cause) {
+        rethrowGitDeadline(cause);
+        const error = new Error("Git could not read the historical file batch safely.", { cause });
+        error.code = "FILEGRC_HISTORY_BATCH_FAILED";
+        throw error;
       }
       batch.forEach(({ index, key }, batchIndex) => {
         const value = values[batchIndex];
@@ -533,14 +861,79 @@ export function getFilesAtRevisions(input, requests, options = {}) {
       }
     }
     return results;
-  } catch {
+  } catch (error) {
+    if (["FILEGRC_HISTORY_EXPORT_LIMIT", "FILEGRC_HISTORY_BATCH_FAILED", "FILEGRC_HISTORY_DEADLINE", "FILEGRC_GIT_DEADLINE"].includes(error?.code)) throw error;
     return results.map((value) => value ?? null);
   }
 }
 
+export function setHistoricalBatchInterceptorForTests(interceptor) {
+  const previous = historicalBatchInterceptor;
+  historicalBatchInterceptor = interceptor;
+  return () => {
+    historicalBatchInterceptor = previous;
+  };
+}
+
+function assertHistoricalExportSize(root, specifications, remainingBytes, maxTotalBytes, timeoutMs = GIT_DEFAULT_TIMEOUT_MS) {
+  const output = measureTimingSync("git-history-size", () => observedExecFileSync("git", [
+    "cat-file",
+    "--batch-check=%(objectname) %(objecttype) %(objectsize)"
+  ], {
+    cwd: root,
+    input: `${specifications.join("\n")}\n`,
+    encoding: "utf8",
+    stdio: ["pipe", "pipe", "ignore"],
+    timeout: timeoutMs,
+    maxBuffer: 20_000_000,
+    env: gitEnvironment()
+  }));
+  let total = 0;
+  for (const line of output.trim().split("\n")) {
+    if (!line || line.endsWith(" missing")) continue;
+    const match = line.match(/^[a-f0-9]+ blob (\d+)$/i);
+    if (!match) throw new Error("Git returned invalid historical object metadata.");
+    total += Number(match[1]);
+    if (!Number.isSafeInteger(total) || total > remainingBytes) throw historicalExportLimitError(maxTotalBytes);
+  }
+}
+
+function historicalExportLimitError(maxTotalBytes) {
+  const megabytes = maxTotalBytes / (1024 * 1024);
+  const limit = Number.isInteger(megabytes) && megabytes >= 1
+    ? `${megabytes} MB`
+    : `${maxTotalBytes} byte`;
+  const error = new Error(`Git historical file exports exceed the ${limit} safety limit.`);
+  error.code = "FILEGRC_HISTORY_EXPORT_LIMIT";
+  return error;
+}
+
+function dataHistoryLimitError(message) {
+  const error = new Error(message);
+  error.code = "FILEGRC_HISTORY_INDEX_LIMIT";
+  return error;
+}
+
 export function getDataFilesAtRevision(input, revision) {
   if (!/^[a-f0-9]{40}$/i.test(String(revision))) return [];
   const root = resolveWorkspaceRoot(input);
+  const index = dataRecordHistoryIndexCache.get(root);
+  if (index?.available && index.parentsByCommit.has(revision)) {
+    const lineage = [];
+    let commit = revision;
+    while (commit) {
+      lineage.push(commit);
+      commit = index.parentsByCommit.get(commit)?.[0] || null;
+    }
+    const files = new Set();
+    for (let position = lineage.length - 1; position >= 0; position -= 1) {
+      for (const [path, source] of index.fileChangesByCommit.get(lineage[position]) || []) {
+        if (source === null) files.delete(path);
+        else files.add(path);
+      }
+    }
+    return [...files].filter((path) => path.endsWith(".json"));
+  }
   try {
     const topLevel = git(root, ["rev-parse", "--show-toplevel"]);
     const workspacePrefix = relative(topLevel, root).split(sep).join("/");
@@ -549,14 +942,15 @@ export function getDataFilesAtRevision(input, revision) {
     return lines(git(root, ["ls-tree", "-r", "--name-only", revision, "--", dataPrefix]))
       .filter((path) => path.startsWith(`${dataPrefix}/`) && path.endsWith(".json"))
       .map((path) => workspacePrefix ? path.slice(workspacePrefix.length + 1) : path);
-  } catch {
+  } catch (error) {
+    rethrowGitDeadline(error);
     return [];
   }
 }
 
 function readHistoricalFile(root, specification) {
   try {
-    return measureTimingSync("git-history-export", () => execFileSync("git", ["show", specification], {
+    return measureTimingSync("git-history-export", () => observedExecFileSync("git", ["show", specification], {
       cwd: root,
       encoding: "utf8",
       stdio: ["ignore", "pipe", "ignore"],
@@ -564,7 +958,8 @@ function readHistoricalFile(root, specification) {
       maxBuffer: 20_000_000,
       env: gitEnvironment()
     }));
-  } catch {
+  } catch (error) {
+    rethrowGitDeadline(error);
     return null;
   }
 }
@@ -607,7 +1002,8 @@ export function getChangedDataPathsSinceRevision(input, revision) {
       ...lines(git(root, ["diff", "--name-only", "--relative", revision, "--", "data"])),
       ...lines(git(root, ["ls-files", "--others", "--exclude-standard", "--", "data"]))
     ])].filter((path) => path.startsWith("data/"));
-  } catch {
+  } catch (error) {
+    rethrowGitDeadline(error);
     return null;
   }
 }
@@ -615,10 +1011,13 @@ export function getChangedDataPathsSinceRevision(input, revision) {
 export function hasGitRevision(input, revision) {
   if (!/^[a-f0-9]{40}$/i.test(String(revision))) return false;
   const root = resolveWorkspaceRoot(input);
+  const index = dataRecordHistoryIndexCache.get(root);
+  if (index?.available && index.parentsByCommit.has(revision)) return true;
   try {
     git(root, ["cat-file", "-e", `${revision}^{commit}`]);
     return true;
-  } catch {
+  } catch (error) {
+    rethrowGitDeadline(error);
     return false;
   }
 }
@@ -652,6 +1051,66 @@ export function getRepositorySnapshot(input = process.cwd(), options = {}) {
   return snapshot;
 }
 
+export async function getRepositoryStateSignature(input = process.cwd(), options = {}) {
+  const root = resolveWorkspaceRoot(input);
+  const timeout = { timeoutMs: options.timeoutMs };
+  let status;
+  let gitDirectory;
+  let refs;
+  let remotes;
+  try {
+    [status, gitDirectory, refs, remotes] = await Promise.all([
+      runGitCommand(root, [
+        "status",
+        "--porcelain=v2",
+        "--branch",
+        "-z",
+        "--untracked-files=all"
+      ], { ...timeout, operation: "verify repository state" }),
+      runGitCommand(root, ["rev-parse", "--absolute-git-dir"], {
+        ...timeout,
+        operation: "locate repository state"
+      }),
+      runGitCommand(root, ["rev-parse", "--verify", "@{upstream}"], {
+        ...timeout,
+        operation: "verify the upstream repository revision"
+      }).catch((error) => {
+        if (error?.code === "FILEGRC_GIT_DEADLINE") throw error;
+        return "";
+      }),
+      runGitCommand(root, ["remote", "-v"], { ...timeout, operation: "verify repository remotes" })
+    ]);
+  } catch (error) {
+    if (error?.code === "FILEGRC_GIT_DEADLINE") throw error;
+    status = "git-unavailable";
+    gitDirectory = "";
+    refs = "";
+    remotes = "";
+  }
+  const background = backgroundSynchronizations.get(root);
+  const backgroundState = background ? {
+    status: background.status,
+    commit: background.commit,
+    startedAt: background.startedAt ?? null,
+    finishedAt: background.finishedAt ?? null,
+    remotePushed: background.remotePushed === true,
+    error: background.error ?? null
+  } : null;
+  return createHash("sha256")
+    .update(status)
+    .update("\0")
+    .update(refs)
+    .update("\0")
+    .update(remotes)
+    .update("\0")
+    .update(repositoryOperationFromDirectory(gitDirectory.trim()) || "")
+    .update("\0")
+    .update(JSON.stringify(backgroundState))
+    .update("\0")
+    .update(lastSuccessfulSynchronizations.get(root) || "")
+    .digest("hex");
+}
+
 export async function getWorkspaceRevisionSnapshot(input = process.cwd()) {
   const root = resolveWorkspaceRoot(input);
   try {
@@ -676,6 +1135,7 @@ export async function getWorkspaceRevisionSnapshot(input = process.cwd()) {
       workspaceChangePaths: parsed.changePaths
     };
   } catch (error) {
+    if (error?.code === "FILEGRC_GIT_DEADLINE") throw error;
     return unavailableSnapshot(error, { workspaceChangePaths: [] });
   }
 }
@@ -689,6 +1149,7 @@ async function buildRepositorySnapshot(root) {
       { operation: "locate the repository" }
     ));
   } catch (error) {
+    if (error?.code === "FILEGRC_GIT_DEADLINE") throw error;
     return unavailableSnapshot(error);
   }
   const [topLevel, gitDirectory] = repositoryPaths.split("\n");
@@ -754,6 +1215,7 @@ async function buildRepositorySnapshot(root) {
       invocationCount: 3 + (parsed.commit ? 1 : 0) + (parsed.upstream ? 1 : 0) + (parsed.ahead > 0 ? 1 : 0)
     };
   } catch (error) {
+    if (error?.code === "FILEGRC_GIT_DEADLINE") throw error;
     return unavailableSnapshot(error, { root: topLevel, gitDirectory });
   }
 }
@@ -1855,7 +2317,7 @@ function assertNoHiddenIndexEntries(root) {
 }
 
 function hashWorkspaceBytes(root, bytes, write = false) {
-  return execFileSync("git", ["hash-object", ...(write ? ["-w"] : []), "--stdin"], {
+  return observedExecFileSync("git", ["hash-object", ...(write ? ["-w"] : []), "--stdin"], {
     cwd: root,
     input: bytes,
     encoding: "utf8",
@@ -2141,6 +2603,24 @@ export function setGitCommandInterceptorForTests(interceptor) {
   return () => { gitCommandInterceptor = previous; };
 }
 
+export function setGitSubprocessObserverForTests(observer) {
+  if (observer !== null && typeof observer !== "function") {
+    throw new TypeError("The Git subprocess observer must be a function or null.");
+  }
+  const previous = gitSubprocessObserver;
+  gitSubprocessObserver = observer;
+  return () => { gitSubprocessObserver = previous; };
+}
+
+export function setHistoricalRevisionReadObserverForTests(observer) {
+  if (observer !== null && typeof observer !== "function") {
+    throw new TypeError("The historical revision-read observer must be a function or null.");
+  }
+  const previous = historicalRevisionReadObserver;
+  historicalRevisionReadObserver = observer;
+  return () => { historicalRevisionReadObserver = previous; };
+}
+
 export function runGitCommand(cwd, args, options = {}) {
   if (gitCommandInterceptor) {
     return Promise.resolve().then(() => gitCommandInterceptor({
@@ -2153,8 +2633,8 @@ export function runGitCommand(cwd, args, options = {}) {
   return runGitCommandNative(cwd, args, options);
 }
 
-export function runGitCommandSync(cwd, args) {
-  return git(resolveWorkspaceRoot(cwd), args);
+export function runGitCommandSync(cwd, args, options = {}) {
+  return git(resolveWorkspaceRoot(cwd), args, options);
 }
 
 function runGitCommandNative(cwd, args, options = {}) {
@@ -2168,8 +2648,9 @@ function runGitCommandNative(cwd, args, options = {}) {
   if (options.expectedNoOperation) assertNoGitOperationInProgress(cwd);
   const operation = options.operation || "run a Git command";
   const configuredTimeout = options.timeoutMs ?? GIT_DEFAULT_TIMEOUT_MS;
-  const timeoutMs = Math.max(1, Number(configuredTimeout) || GIT_DEFAULT_TIMEOUT_MS);
+  const { timeoutMs, deadlineLimited } = gitTimeoutPlan(configuredTimeout, GIT_DEFAULT_TIMEOUT_MS);
   const maxOutputBytes = Math.max(1, Number(options.maxOutputBytes) || GIT_MAX_OUTPUT_BYTES);
+  gitSubprocessObserver?.({ kind: "async", cwd, args: [...args], options: { ...options } });
   return new Promise((resolveCommand, rejectCommand) => {
     const child = spawn("git", args, {
       cwd,
@@ -2248,7 +2729,9 @@ function runGitCommandNative(cwd, args, options = {}) {
         : /not a git repository|outside repository/i.test(errorOutput)
           ? "invalid-repository"
           : "command-failure";
-      rejectCommand(new GitOperationError(kind, operation, detail));
+      rejectCommand(new GitOperationError(kind, operation, detail, {
+        code: timedOut && deadlineLimited ? "FILEGRC_GIT_DEADLINE" : undefined
+      }));
     });
   });
 }
@@ -2261,21 +2744,24 @@ async function tryGitAsync(cwd, args, operation) {
   }
 }
 
-function git(cwd, args) {
-  return measureTimingSync("git-command-sync", () => execFileSync("git", args, {
-    cwd,
-    encoding: "utf8",
-    stdio: ["ignore", "pipe", "ignore"],
-    timeout: 10_000,
-    maxBuffer: 20_000_000,
-    env: gitEnvironment()
-  }).trim());
+function git(cwd, args, options = {}) {
+  return cachedGitCommand("text", cwd, args, options, () => {
+    return measureTimingSync("git-command-sync", () => observedExecFileSync("git", args, {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: Math.max(1, Number(options.timeoutMs) || GIT_DEFAULT_TIMEOUT_MS),
+      maxBuffer: 20_000_000,
+      env: gitEnvironment()
+    }).trim());
+  });
 }
 
 function tryGit(cwd, args) {
   try {
     return git(cwd, args);
-  } catch {
+  } catch (error) {
+    if (error?.code === "FILEGRC_GIT_DEADLINE") throw error;
     return "";
   }
 }
@@ -2292,22 +2778,107 @@ function gitOptionalMatch(cwd, args) {
 function tryGitRaw(cwd, args) {
   try {
     return gitRaw(cwd, args);
-  } catch {
+  } catch (error) {
+    if (error?.code === "FILEGRC_GIT_DEADLINE") throw error;
     return "";
   }
 }
 
 function gitRaw(cwd, args, options = {}) {
-  return execFileSync("git", args, {
-    cwd,
-    encoding: "utf8",
-    stdio: ["ignore", "pipe", "ignore"],
-    timeout: 10_000,
-    maxBuffer: 20_000_000,
-    env: gitEnvironment(options.gitIndexFile ? { GIT_INDEX_FILE: options.gitIndexFile } : {})
+  return cachedGitCommand("raw", cwd, args, options, () => {
+    return observedExecFileSync("git", args, {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: Math.max(1, Number(options.timeoutMs) || GIT_DEFAULT_TIMEOUT_MS),
+      maxBuffer: 20_000_000,
+      env: gitEnvironment(options.gitIndexFile ? { GIT_INDEX_FILE: options.gitIndexFile } : {})
+    });
   });
 }
 
+function cachedGitCommand(outputKind, cwd, args, options, run) {
+  const cache = gitCommandCaches.getStore();
+  if (!cache) return run();
+  const key = JSON.stringify([
+    outputKind,
+    resolve(cwd),
+    args,
+    options.gitIndexFile || null
+  ]);
+  const cached = cache.get(key);
+  if (cached) {
+    cache.delete(key);
+    cache.set(key, cached);
+    return cached.value;
+  }
+  const value = run();
+  const size = Buffer.byteLength(value);
+  if (size <= GIT_COMMAND_CACHE_MAX_ENTRY_BYTES) {
+    let totalBytes = gitCommandCacheBytes.get(cache) || 0;
+    while (cache.size >= GIT_COMMAND_CACHE_MAX_ENTRIES || totalBytes + size > GIT_COMMAND_CACHE_MAX_BYTES) {
+      const oldestKey = cache.keys().next().value;
+      if (oldestKey === undefined) break;
+      totalBytes -= cache.get(oldestKey)?.size || 0;
+      cache.delete(oldestKey);
+    }
+    cache.set(key, { value, size });
+    gitCommandCacheBytes.set(cache, totalBytes + size);
+  }
+  return value;
+}
+
+function observedExecFileSync(executable, args, options = {}) {
+  const timeoutPlan = executable === "git"
+    ? gitTimeoutPlan(options.timeout, GIT_DEFAULT_TIMEOUT_MS)
+    : null;
+  const boundedOptions = timeoutPlan
+    ? { ...options, timeout: timeoutPlan.timeoutMs }
+    : options;
+  try {
+    if (executable === "git") {
+      gitSubprocessObserver?.({
+        kind: "sync",
+        cwd: boundedOptions.cwd,
+        args: [...args],
+        options: { ...boundedOptions, input: boundedOptions.input === undefined ? undefined : "[redacted]" }
+      });
+    }
+    return execFileSync(executable, args, boundedOptions);
+  } catch (error) {
+    if (timeoutPlan?.deadlineLimited && (error?.code === "ETIMEDOUT" || error?.signal)) {
+      const deadlineError = new Error("The Git command exceeded the shared request deadline.", { cause: error });
+      deadlineError.code = "FILEGRC_GIT_DEADLINE";
+      throw deadlineError;
+    }
+    throw error;
+  }
+}
+
+function boundedGitTimeout(configured, fallback) {
+  return gitTimeoutPlan(configured, fallback).timeoutMs;
+}
+
+function gitTimeoutPlan(configured, fallback) {
+  const requested = Math.max(1, Number(configured) || fallback);
+  const deadlineAt = gitCommandDeadlines.getStore();
+  if (deadlineAt === undefined) return { timeoutMs: requested, deadlineLimited: false };
+  const remaining = Math.ceil(deadlineAt - performance.now());
+  if (remaining <= 0) {
+    const error = new Error("The Git command deadline expired before another subprocess could start.");
+    error.code = "FILEGRC_GIT_DEADLINE";
+    throw error;
+  }
+  return {
+    timeoutMs: Math.min(requested, remaining),
+    deadlineLimited: remaining <= requested
+  };
+}
+
+function rethrowGitDeadline(error) {
+  if (error?.code === "FILEGRC_GIT_DEADLINE") throw error;
+}
+
 function nulFields(source) {
   return source ? source.split("\0").filter(Boolean) : [];
 }
@@ -2315,7 +2886,7 @@ function nulFields(source) {
 function gitForWrite(cwd, args, action = "create the commit", options = {}) {
   try {
     assertWorkspaceInsideGitWorktree(cwd);
-    return execFileSync("git", args, {
+    return observedExecFileSync("git", args, {
       cwd,
       encoding: "utf8",
       stdio: ["ignore", "pipe", "pipe"],