@hominis/fireforge 0.43.1 → 0.44.0

package/dist/src/core/furnace-version-drift.d.ts

@@ -5,21 +5,20 @@
  * Overrides are forks of Firefox source files taken at a specific point in
  * time. If Firefox moves forward and the override's `baseVersion` is not
  * refreshed, the override may apply against a file whose upstream shape has
- * changed — which is the single biggest silent failure mode for furnace.
+ * changed — the single biggest silent failure mode for furnace.
  *
- * This module is deliberately pure and string-only: it does no I/O and does
- * not parse Firefox version components. Comparing by string equality is
- * sufficient because `fireforge.json` stores a canonical version string
- * (e.g. `"140.9.0esr"`) and overrides are created with exactly that string
- * copied from `forgeConfig.firefox.version`. Any string mismatch is worth
- * surfacing — even "140.0" vs "140.9.0esr" is a real drift signal.
+ * Deliberately pure and string-only: no I/O, and no parsing of Firefox
+ * version components. String equality is sufficient because `fireforge.json`
+ * stores a canonical version string (e.g. `"140.9.0esr"`) and overrides are
+ * created with exactly that string copied from
+ * `forgeConfig.firefox.version`. Any mismatch is worth surfacing — even
+ * "140.0" vs "140.9.0esr" is a real drift signal.
  *
  * The result GATES apply/deploy: both warn and then FAIL without --force
  * (see furnaceApplyCommand / furnaceDeployCommand), and `furnace sync`
- * re-checks it after refresh before applying. Status reports drift
- * alongside the component overview. Keep this doc in sync with the gates —
- * an earlier version claimed the result was advisory, which invited
- * re-breaking the gate.
+ * re-checks it after refresh before applying. Status reports drift alongside
+ * the component overview. Keep this doc in sync with the gates — it is not
+ * advisory.
  */
 import type { FurnaceConfig } from '../types/furnace.js';
 /** Severity of the version drift between an override's base and the current Firefox version. */

package/dist/src/core/furnace-version-drift.js

@@ -6,21 +6,20 @@
  * Overrides are forks of Firefox source files taken at a specific point in
  * time. If Firefox moves forward and the override's `baseVersion` is not
  * refreshed, the override may apply against a file whose upstream shape has
- * changed — which is the single biggest silent failure mode for furnace.
+ * changed — the single biggest silent failure mode for furnace.
  *
- * This module is deliberately pure and string-only: it does no I/O and does
- * not parse Firefox version components. Comparing by string equality is
- * sufficient because `fireforge.json` stores a canonical version string
- * (e.g. `"140.9.0esr"`) and overrides are created with exactly that string
- * copied from `forgeConfig.firefox.version`. Any string mismatch is worth
- * surfacing — even "140.0" vs "140.9.0esr" is a real drift signal.
+ * Deliberately pure and string-only: no I/O, and no parsing of Firefox
+ * version components. String equality is sufficient because `fireforge.json`
+ * stores a canonical version string (e.g. `"140.9.0esr"`) and overrides are
+ * created with exactly that string copied from
+ * `forgeConfig.firefox.version`. Any mismatch is worth surfacing — even
+ * "140.0" vs "140.9.0esr" is a real drift signal.
  *
  * The result GATES apply/deploy: both warn and then FAIL without --force
  * (see furnaceApplyCommand / furnaceDeployCommand), and `furnace sync`
- * re-checks it after refresh before applying. Status reports drift
- * alongside the component overview. Keep this doc in sync with the gates —
- * an earlier version claimed the result was advisory, which invited
- * re-breaking the gate.
+ * re-checks it after refresh before applying. Status reports drift alongside
+ * the component overview. Keep this doc in sync with the gates — it is not
+ * advisory.
  */
 /**
  * Parses a version string into its major, minor, and patch numeric

package/dist/src/core/git-base.d.ts

@@ -1,9 +1,8 @@
 /**
  * Environment variable that overrides the monolithic `git add -A` timeout
- * (milliseconds). 2026-04-24 eval Finding 10: operators on slow or loaded
- * filesystems legitimately exceeded the 10-minute default during a
- * 140.10.0esr baseline indexing pass; making the cap overridable lets
- * them retry without recompiling.
+ * (milliseconds). Operators on slow or loaded filesystems can legitimately
+ * exceed the 10-minute default during a baseline indexing pass; making the
+ * cap overridable lets them retry without recompiling.
  */
 export declare const GIT_ADD_TIMEOUT_ENV_VAR = "FIREFORGE_GIT_ADD_TIMEOUT_MS";
 /**
@@ -20,11 +19,10 @@ export declare const GIT_ADD_CHUNK_TIMEOUT_ENV_VAR = "FIREFORGE_GIT_ADD_CHUNK_TI
  */
 export declare const GIT_ADD_TIMEOUT_MS: number;
 /**
- * Resolved timeout for each chunk of the chunked fallback path. Grew
- * from 20 to 30 minutes in 0.18.1 because the fallback is already the
- * last line of defence before aborting — erring on the side of "complete
- * the indexing" over "fail fast" matches the real-world recovery
- * workflow.
+ * Resolved timeout for each chunk of the chunked fallback path. Generous by
+ * design: the fallback is already the last line of defence before aborting,
+ * so erring toward "complete the indexing" over "fail fast" matches the
+ * real-world recovery workflow.
  */
 export declare const GIT_ADD_CHUNK_TIMEOUT_MS: number;
 /**

package/dist/src/core/git-base.js

@@ -4,10 +4,9 @@ import { exec, executableExists } from '../utils/process.js';
 import { readOnlyGitIndexEnv } from './git-readonly-index.js';
 /**
  * Environment variable that overrides the monolithic `git add -A` timeout
- * (milliseconds). 2026-04-24 eval Finding 10: operators on slow or loaded
- * filesystems legitimately exceeded the 10-minute default during a
- * 140.10.0esr baseline indexing pass; making the cap overridable lets
- * them retry without recompiling.
+ * (milliseconds). Operators on slow or loaded filesystems can legitimately
+ * exceed the 10-minute default during a baseline indexing pass; making the
+ * cap overridable lets them retry without recompiling.
  */
 export const GIT_ADD_TIMEOUT_ENV_VAR = 'FIREFORGE_GIT_ADD_TIMEOUT_MS';
 /**
@@ -37,11 +36,10 @@ function resolveTimeoutFromEnv(envVar, fallbackMs) {
  */
 export const GIT_ADD_TIMEOUT_MS = resolveTimeoutFromEnv(GIT_ADD_TIMEOUT_ENV_VAR, DEFAULT_GIT_ADD_TIMEOUT_MS);
 /**
- * Resolved timeout for each chunk of the chunked fallback path. Grew
- * from 20 to 30 minutes in 0.18.1 because the fallback is already the
- * last line of defence before aborting — erring on the side of "complete
- * the indexing" over "fail fast" matches the real-world recovery
- * workflow.
+ * Resolved timeout for each chunk of the chunked fallback path. Generous by
+ * design: the fallback is already the last line of defence before aborting,
+ * so erring toward "complete the indexing" over "fail fast" matches the
+ * real-world recovery workflow.
  */
 export const GIT_ADD_CHUNK_TIMEOUT_MS = resolveTimeoutFromEnv(GIT_ADD_CHUNK_TIMEOUT_ENV_VAR, DEFAULT_GIT_ADD_CHUNK_TIMEOUT_MS);
 /**

package/dist/src/core/git-diff.d.ts

@@ -1,5 +1,11 @@
 /**
  * Gets the diff for a specific file.
+ *
+ * `--binary` is load-bearing: without it git degrades a binary file's section
+ * to the informational `Binary files a/x and b/x differ`, which carries none
+ * of the bytes and cannot be replayed by `git apply`. It only expands the
+ * BINARY section's index line to full hashes (text sections keep their
+ * abbreviated form), so text output stays byte-identical.
  * @param repoDir - Repository directory
  * @param filePath - Path to the file (relative to repo)
  * @returns Diff content
@@ -32,22 +38,27 @@ export declare function generateFullFilePatch(repoDir: string, filePath: string)
 export declare function generateModificationDiff(repoDir: string, filePath: string, baseContent: string): Promise<string>;
 /**
  * Gets the diff for all modified files, including untracked (new) files.
+ *
+ * Tracked binary files round-trip through `git diff --binary`; untracked ones
+ * go through {@link generateBinaryFilePatch} below. Both arms must stay
+ * binary-aware — see {@link getFileDiff} for why.
  * @param repoDir - Repository directory
  * @returns Diff content
  */
 export declare function getAllDiff(repoDir: string): Promise<string>;
 /**
  * Builds a combined diff against HEAD for the provided files without touching
- * the real git index. Tracked files use `git diff HEAD`; untracked files use
- * synthesized new-file diffs.
+ * the real git index. Tracked files use `git diff --binary HEAD` (binary
+ * sections included); untracked files use synthesized new-file diffs, or
+ * {@link generateBinaryFilePatch} when the file is binary.
+ *
+ * Performance: the work is batched into a handful of `git` invocations (one
+ * `ls-tree` to classify, one `diff` over all tracked files, one `hash-object`
+ * over all new text files) rather than ~2 spawns per file, which dominates
+ * the cold-run cost on a Firefox-sized checkout. Binary, directory, and
+ * recursion paths stay per-file because they are rare and (for binary)
+ * mutate the index.
  *
- * Performance: the work is batched into a handful of `git` invocations
- * (one `ls-tree` to classify, one `diff` over all tracked files, one
- * `hash-object` over all new text files) rather than the ~2 spawns per file the
- * previous per-file loop issued — that fan-out dominated the cold-run cost on a
- * Firefox-sized checkout (~700 serial spawns, ~99s). Binary, directory, and
- * recursion paths stay per-file because they are rare and (for binary) mutate
- * the index.
  * @param repoDir - Repository directory
  * @param files - File paths to diff (relative to repo root)
  * @returns Combined diff content

package/dist/src/core/git-diff.js

@@ -9,17 +9,24 @@ import { verbose } from '../utils/logger.js';
 import { exec } from '../utils/process.js';
 import { chunkPathspecs, ensureGit, git } from './git-base.js';
 import { fileExistsInHead, hashObjectBatch, isBinaryFile, listTrackedInHead, } from './git-file-ops.js';
-import { readOnlyGitIndexEnv } from './git-readonly-index.js';
+import { mintDisposableGitIndex, readOnlyGitIndexEnv } from './git-readonly-index.js';
 import { getUntrackedFiles, getUntrackedFilesInDir } from './git-status.js';
-async function execGitWithAllowedExitCodes(repoDir, args, allowedExitCodes = [0]) {
+async function execGitWithAllowedExitCodes(repoDir, args, allowedExitCodes = [0], envOverride) {
     // Honour a read-only command's private-index scope: the `--intent-to-add`
     // / `update-index` staging dance below is a genuine
     // index write, and inside a read-only command it must land on the
     // private index, not the primary checkout's.
+    //
+    // `envOverride` wins over that scope: a caller that minted an index for
+    // one specific invocation has said something more specific than the
+    // ambient scope did.
     const readOnlyIndexEnv = readOnlyGitIndexEnv(repoDir);
+    const env = readOnlyIndexEnv !== undefined || envOverride !== undefined
+        ? { ...readOnlyIndexEnv, ...envOverride }
+        : undefined;
     const result = await exec('git', args, {
         cwd: repoDir,
-        ...(readOnlyIndexEnv !== undefined ? { env: readOnlyIndexEnv } : {}),
+        ...(env !== undefined ? { env } : {}),
     });
     if (allowedExitCodes.includes(result.exitCode)) {
         return result;
@@ -28,13 +35,19 @@ async function execGitWithAllowedExitCodes(repoDir, args, allowedExitCodes = [0]
 }
 /**
  * Gets the diff for a specific file.
+ *
+ * `--binary` is load-bearing: without it git degrades a binary file's section
+ * to the informational `Binary files a/x and b/x differ`, which carries none
+ * of the bytes and cannot be replayed by `git apply`. It only expands the
+ * BINARY section's index line to full hashes (text sections keep their
+ * abbreviated form), so text output stays byte-identical.
  * @param repoDir - Repository directory
  * @param filePath - Path to the file (relative to repo)
  * @returns Diff content
  */
 export async function getFileDiff(repoDir, filePath) {
     await ensureGit();
-    return git(['diff', 'HEAD', '--', filePath], repoDir);
+    return git(['diff', '--binary', 'HEAD', '--', filePath], repoDir);
 }
 /**
  * Abbreviates a full git blob hash to the 10-character form used in the
@@ -51,13 +64,14 @@ function abbreviateBlobHash(fullHash) {
     return '0000000000';
 }
 /**
- * Pure formatter for a new (untracked) file's unified diff. Extracted from
- * {@link generateNewFileDiff} so the batched cold-run path in
- * {@link getDiffForFilesAgainstHead} and the standalone path share one source of
- * truth — the only thing that differs between them is where `blobHash` comes
- * from (a single batched `git hash-object` vs a per-file one), never the
- * formatting. Preserves the empty-file form, the trailing-newline handling, and
- * the "No newline at end of file" marker byte-for-byte.
+ * Pure formatter for a new (untracked) file's unified diff. Shared by the
+ * batched cold-run path in {@link getDiffForFilesAgainstHead} and the
+ * standalone {@link generateNewFileDiff} — the only thing that differs is
+ * where `blobHash` comes from (a single batched `git hash-object` vs a
+ * per-file one), never the formatting. Preserves the empty-file form, the
+ * trailing-newline handling, and the "No newline at end of file" marker
+ * byte-for-byte.
+ *
  * @param filePath - Path to the file (relative to repo)
  * @param content - File content
  * @param blobHash - Abbreviated blob hash for the index line
@@ -106,12 +120,10 @@ function buildNewFileDiffBody(filePath, content, blobHash) {
  */
 export async function generateNewFileDiff(repoDir, filePath) {
     const fullPath = join(repoDir, filePath);
-    // Defensive check: a directory here means a caller bypassed the
-    // expansion layers and handed the leaf reader a path it cannot
-    // read. Surface it with an actionable message naming the offending
-    // path rather than the raw `EISDIR` that `readText` would throw —
-    // recurring bug class (see the belt-and-suspenders note in
-    // `getDiffForFilesAgainstHead`).
+    // Defensive check: a directory here means a caller bypassed the expansion
+    // layers and handed the leaf reader a path it cannot read. Surface it with
+    // an actionable message naming the offending path rather than the raw
+    // `EISDIR` that `readText` would throw.
     const fileStat = await stat(fullPath);
     if (fileStat.isDirectory()) {
         throw new GitError(`expected a file but found a directory at '${filePath}' — caller must expand directory entries before diffing`, `hash-object ${filePath}`);
@@ -199,22 +211,65 @@ export async function generateModificationDiff(repoDir, filePath, baseContent) {
 }
 /**
  * Gets the diff for all modified files, including untracked (new) files.
+ *
+ * Tracked binary files round-trip through `git diff --binary`; untracked ones
+ * go through {@link generateBinaryFilePatch} below. Both arms must stay
+ * binary-aware — see {@link getFileDiff} for why.
  * @param repoDir - Repository directory
  * @returns Diff content
  */
 export async function getAllDiff(repoDir) {
     await ensureGit();
     // Get diff for tracked files
-    const trackedDiff = await git(['diff', 'HEAD'], repoDir);
+    const trackedDiff = await git(['diff', '--binary', 'HEAD'], repoDir);
     // Get untracked files (properly expanded, not directories)
     const untrackedFiles = await getUntrackedFiles(repoDir);
-    // Generate diffs for untracked files
+    // Classify first. `isBinaryFile` reads the file's first 8 KB directly and
+    // spawns nothing, so the only per-file process in this loop is the
+    // `git hash-object` inside `generateNewFileDiff` — one spawn per untracked
+    // TEXT file, uncapped, against a Firefox tree where "untracked" can mean a
+    // very large number. Hence classify → one batched hash → render.
+    //
+    // Everything else here is deliberately untouched: `git diff HEAD` (with
+    // renames, unlike the `--no-renames` scoped sibling), the `ls-files`
+    // ordering, tracked-block-first emission, and the `'\n'` empty-result
+    // sentinel are all observable. `getAllDiff`'s output is SHA-256'd into
+    // every tree fingerprint (tree-store.ts) and written verbatim into `.patch`
+    // files (export-all.ts), so its bytes are a contract.
+    const binaryFiles = [];
+    const textFiles = [];
+    for (const file of untrackedFiles) {
+        if (await isBinaryFile(repoDir, file)) {
+            binaryFiles.push(file);
+        }
+        else {
+            textFiles.push(file);
+        }
+    }
+    const textHashes = await hashObjectBatch(repoDir, textFiles.map((file) => join(repoDir, file)));
+    // Binary patches stage into the index and must stay serial; text patches
+    // are pure formatting over the already-batched hashes.
+    const binaryDiffs = new Map();
+    for (const file of binaryFiles) {
+        binaryDiffs.set(file, await generateBinaryFilePatch(repoDir, file));
+    }
     const untrackedDiffs = [];
     for (const file of untrackedFiles) {
-        const diff = (await isBinaryFile(repoDir, file))
-            ? await generateBinaryFilePatch(repoDir, file)
-            : await generateNewFileDiff(repoDir, file);
-        untrackedDiffs.push(diff);
+        const binary = binaryDiffs.get(file);
+        if (binary !== undefined) {
+            untrackedDiffs.push(binary);
+            continue;
+        }
+        const fullPath = join(repoDir, file);
+        // Same defensive directory check `generateNewFileDiff` carries: a
+        // directory here means a caller bypassed the expansion layers, and its
+        // comment records this as a recurring bug class.
+        const fileStat = await stat(fullPath);
+        if (fileStat.isDirectory()) {
+            throw new GitError(`expected a file but found a directory at '${file}' — caller must expand directory entries before diffing`, `hash-object ${file}`);
+        }
+        const content = await readText(fullPath);
+        untrackedDiffs.push(buildNewFileDiffBody(file, content, abbreviateBlobHash(textHashes.get(fullPath))));
     }
     // Combine all diffs — each already ends with \n, so concatenate directly
     // to avoid inserting blank lines between diff sections.
@@ -249,9 +304,15 @@ function splitDiffSections(combined) {
     return sections;
 }
 /**
- * Runs one `git diff --no-renames HEAD` over the tracked files (chunked under
- * ARG_MAX) and returns a `Map<path, section>` whose sections are byte-identical
- * to the per-file `git diff HEAD -- <file>` they replace.
+ * Runs one `git diff --binary --no-renames HEAD` over the tracked files
+ * (chunked under ARG_MAX) and returns a `Map<path, section>` whose sections are
+ * byte-identical to the per-file `git diff --binary HEAD -- <file>` they
+ * replace.
+ *
+ * `--binary` is load-bearing: a tracked binary file would otherwise degrade to
+ * the un-appliable `Binary files a/x and b/x differ` stub. It expands only the
+ * binary section's index line to full hashes, so text sections are unaffected
+ * — see {@link getFileDiff}.
  *
  * `--no-renames` is load-bearing: a multi-path diff under a user's
  * `diff.renames=true`/`=copies` could otherwise emit a single 2-path rename
@@ -274,7 +335,7 @@ function splitDiffSections(combined) {
 async function buildTrackedSections(repoDir, trackedFiles) {
     const sectionsByPath = new Map();
     for (const chunk of chunkPathspecs(trackedFiles)) {
-        const combined = await git(['diff', '--no-renames', 'HEAD', '--', ...chunk], repoDir);
+        const combined = await git(['diff', '--binary', '--no-renames', 'HEAD', '--', ...chunk], repoDir);
         const namesOutput = await git(['diff', '--no-renames', 'HEAD', '-z', '--name-only', '--', ...chunk], repoDir);
         const names = namesOutput.split('\0').filter((name) => name.length > 0);
         const sections = splitDiffSections(combined);
@@ -299,16 +360,17 @@ async function buildTrackedSections(repoDir, trackedFiles) {
 }
 /**
  * Builds a combined diff against HEAD for the provided files without touching
- * the real git index. Tracked files use `git diff HEAD`; untracked files use
- * synthesized new-file diffs.
+ * the real git index. Tracked files use `git diff --binary HEAD` (binary
+ * sections included); untracked files use synthesized new-file diffs, or
+ * {@link generateBinaryFilePatch} when the file is binary.
+ *
+ * Performance: the work is batched into a handful of `git` invocations (one
+ * `ls-tree` to classify, one `diff` over all tracked files, one `hash-object`
+ * over all new text files) rather than ~2 spawns per file, which dominates
+ * the cold-run cost on a Firefox-sized checkout. Binary, directory, and
+ * recursion paths stay per-file because they are rare and (for binary)
+ * mutate the index.
  *
- * Performance: the work is batched into a handful of `git` invocations
- * (one `ls-tree` to classify, one `diff` over all tracked files, one
- * `hash-object` over all new text files) rather than the ~2 spawns per file the
- * previous per-file loop issued — that fan-out dominated the cold-run cost on a
- * Firefox-sized checkout (~700 serial spawns, ~99s). Binary, directory, and
- * recursion paths stay per-file because they are rare and (for binary) mutate
- * the index.
  * @param repoDir - Repository directory
  * @param files - File paths to diff (relative to repo root)
  * @returns Combined diff content
@@ -318,12 +380,10 @@ export async function getDiffForFilesAgainstHead(repoDir, files) {
     // Expand any directory entries (paths ending with `/`) into their
     // individual untracked files before diffing. `git status --porcelain=v1`
     // reports collapsed untracked directories as `?? dir/`, and every caller
-    // that feeds the aggregate working-tree state into this function must
-    // not trigger an EISDIR when the diff pass reads `dir/` as if it were a
-    // file. Belt-and-suspenders: the caller-side expansion in `lint.ts`
-    // and `export-all.ts` covers the common path, but a single bad call
-    // site re-introduced the bug in 0.17.0 — guarding here makes the
-    // regression impossible at this layer.
+    // that feeds the aggregate working-tree state into this function must not
+    // trigger an EISDIR when the diff pass reads `dir/` as if it were a file.
+    // The caller-side expansion in `lint.ts` and `export-all.ts` covers the
+    // common path; guarding here makes a single bad call site harmless.
     const expandedFiles = [];
     for (const file of files) {
         if (file.endsWith('/')) {
@@ -357,15 +417,13 @@ export async function getDiffForFilesAgainstHead(repoDir, files) {
         if (!(await pathExists(fullPath))) {
             continue;
         }
-        // Second defence against the EISDIR regression: a non-HEAD path
-        // that exists on disk is usually a new file, but can also be a
-        // directory that arrived without the trailing slash
-        // `expandUntrackedDirectoryEntries` would have produced (caller
-        // stripped it, submodule entry, tracked-file-replaced-by-dir).
-        // Expand it via the same helper used by the slash branch and
-        // recurse so each contained file is diffed individually; fail
-        // loud when the directory has no readable content rather than
-        // silently skipping it.
+        // Second defence against EISDIR: a non-HEAD path that exists on disk is
+        // usually a new file, but can also be a directory that arrived without
+        // the trailing slash `expandUntrackedDirectoryEntries` would have
+        // produced (caller stripped it, submodule entry, tracked-file-replaced-
+        // by-dir). Expand it via the same helper used by the slash branch and
+        // recurse so each contained file is diffed individually; fail loud when
+        // the directory has no readable content rather than silently skipping it.
         const fileStat = await stat(fullPath);
         if (fileStat.isDirectory()) {
             const innerFiles = await getUntrackedFilesInDir(repoDir, file);
@@ -427,7 +485,7 @@ export async function getDiffForFilesAgainstHead(repoDir, files) {
  */
 export async function getStagedDiffForFiles(repoDir, files) {
     await ensureGit();
-    return git(['diff', '--cached', 'HEAD', '--', ...files], repoDir);
+    return git(['diff', '--binary', '--cached', 'HEAD', '--', ...files], repoDir);
 }
 /**
  * Serializes the index-mutating untracked-binary path. The bounded per-patch
@@ -465,18 +523,45 @@ export async function generateBinaryFilePatch(repoDir, filePath) {
     ]);
     if (result.stdout.trim())
         return result.stdout;
-    // For untracked files, stage temporarily to produce a binary diff. The
-    // stage/unstage pair mutates the index, so it must not interleave with
-    // another concurrent binary patch (see runWithBinaryStagingLock).
+    // The diff for an untracked file has to come from an index entry, so one
+    // has to be written. Writing it to a PRIVATE index is what keeps that
+    // write invisible: the primary `.git/index` never moves, so a concurrent
+    // `fireforge test` fingerprinting `engine/` with `git status` cannot
+    // observe the transient `--intent-to-add` entry and void its own verdict
+    // on our bookkeeping. That was a real failure mode — parallel gate lanes
+    // killed three runs with `FAIL reason=inconclusive` on branding PNGs
+    // flapping between `A` and `??`.
+    //
+    // Nothing is restored afterwards because nothing shared was changed, and
+    // no lock is taken because two concurrent callers get two indexes. Both
+    // the restore dance and the in-process lock survive below purely for the
+    // fallback, where the primary index really is the one being written.
+    const disposable = await mintDisposableGitIndex(repoDir);
+    if (disposable !== undefined) {
+        try {
+            await execGitWithAllowedExitCodes(repoDir, ['add', '--intent-to-add', '--', filePath], [0], disposable.env);
+            const diffResult = await execGitWithAllowedExitCodes(repoDir, ['diff', '--binary', '--', filePath], [0], disposable.env);
+            return diffResult.stdout;
+        }
+        finally {
+            await disposable.dispose();
+        }
+    }
+    // Fallback: no private index could be minted (a non-git directory, an
+    // unreadable index, no writable tmpdir). Degrading to the shared index is
+    // the pre-existing behaviour rather than a new risk, and refusing instead
+    // would fail an export over an optimisation. The stage/unstage pair
+    // mutates the index, so it must not interleave with another concurrent
+    // binary patch (see runWithBinaryStagingLock).
+    verbose(`Binary patch for ${filePath} is staging on the shared index (no private index).`);
     return runWithBinaryStagingLock(async () => {
-        // Snapshot the path's exact index entry before touching it. The cleanup
-        // used to be a blanket `git reset HEAD -- <file>`, which restores the
-        // path to its HEAD state — for a path absent from HEAD that means
-        // *removing* whatever entry the index carried, so any staged state that
-        // arrived between the read-only diff above and this staging block (a
-        // concurrent writer, or a staged-add whose worktree file was deleted)
-        // was silently discarded. Restoring the captured entry
-        // instead makes the cleanup exact regardless of how the entry got there.
+        // Snapshot the path's exact index entry before touching it. A blanket
+        // `git reset HEAD -- <file>` cleanup restores the path to its HEAD state
+        // — for a path absent from HEAD that means *removing* whatever entry the
+        // index carried, silently discarding any staged state that arrived
+        // between the read-only diff above and this staging block (a concurrent
+        // writer, or a staged-add whose worktree file was deleted). Restoring
+        // the captured entry is exact regardless of how the entry got there.
         const priorEntry = (await execGitWithAllowedExitCodes(repoDir, ['ls-files', '--stage', '--', filePath])).stdout;
         try {
             await execGitWithAllowedExitCodes(repoDir, ['add', '--intent-to-add', '--', filePath]);

package/dist/src/core/git-file-ops.d.ts

@@ -31,17 +31,17 @@ export declare function unstageFiles(repoDir: string, files: string[]): Promise<
  */
 export declare function fileExistsInHead(repoDir: string, filePath: string): Promise<boolean>;
 /**
- * Batched equivalent of {@link fileExistsInHead}: returns the subset of `files`
- * that are tracked in HEAD, using a single `git ls-tree` per ARG_MAX chunk
- * instead of one spawn per file. This is the cold-run hot path — a Firefox-sized
- * checkout has hundreds of affected files, and the old per-file fan-out spent
- * ~99s in serial `git ls-tree`/`git diff` spawns.
+ * Batched equivalent of {@link fileExistsInHead}: returns the subset of
+ * `files` that are tracked in HEAD, using a single `git ls-tree` per ARG_MAX
+ * chunk instead of one spawn per file. This is the cold-run hot path — a
+ * Firefox-sized checkout has hundreds of affected files.
+ *
+ * `-r` lists nested blobs by full repo-relative path; `--name-only -z` makes
+ * the output a trivial NUL-split with no quoting to undo. Membership in the
+ * returned Set is exactly `await fileExistsInHead(repoDir, file)` for any
+ * non-directory `file`. Throws (via {@link git}) when HEAD itself is
+ * unresolvable, matching the per-file helper's failure mode.
  *
- * `-r` lists nested blobs by full repo-relative path; `--name-only -z` makes the
- * output a trivial NUL-split with no quoting to undo. Membership in the returned
- * Set is exactly `await fileExistsInHead(repoDir, file)` for any non-directory
- * `file`. Throws (via {@link git}) when HEAD itself is unresolvable, matching the
- * per-file helper's failure mode.
  * @param repoDir - Repository directory
  * @param files - Repo-relative paths to classify
  * @returns The subset of `files` present in HEAD
@@ -55,15 +55,15 @@ export declare function listTrackedInHead(repoDir: string, files: string[]): Pro
  *
  * Uses {@link import('../utils/process.js').exec} rather than {@link git}
  * (which throws on a non-zero exit) because `git hash-object f1 f2 …` is
- * all-or-nothing: it aborts at the first unreadable path and emits nothing for
- * the rest. To preserve the old per-file contract — where one bad path zeroed
- * only its own index line — a chunk that does not return exactly one hash per
- * input falls back to hashing that chunk's paths individually. A path that is
- * still unhashable is simply left out of the map; the caller applies the
- * `0000000000` zero-hash fallback (and the same verbose log) for any miss, so
- * the blob hash is byte-identical to `git hash-object` (filters/.gitattributes
- * are applied per path) without the risk of in-process hashing, which would
- * diverge under `core.autocrlf`/`text` attributes.
+ * all-or-nothing: it aborts at the first unreadable path and emits nothing
+ * for the rest. To keep the per-file contract — where one bad path zeroes
+ * only its own index line — a chunk that does not return exactly one hash
+ * per input falls back to hashing that chunk's paths individually. A path
+ * that is still unhashable is left out of the map; the caller applies the
+ * `0000000000` zero-hash fallback for any miss. Hashing stays in git rather
+ * than in-process so filters and `.gitattributes` are applied per path and
+ * the result cannot diverge under `core.autocrlf`/`text` attributes.
+ *
  * @param repoDir - Repository directory
  * @param fullPaths - Absolute file paths to hash
  * @returns Map from each input path to its full blob hash (misses omitted)

package/dist/src/core/git-file-ops.js

@@ -88,17 +88,17 @@ export async function fileExistsInHead(repoDir, filePath) {
     return (await git(['ls-tree', 'HEAD', '--', filePath], repoDir)).trim().length > 0;
 }
 /**
- * Batched equivalent of {@link fileExistsInHead}: returns the subset of `files`
- * that are tracked in HEAD, using a single `git ls-tree` per ARG_MAX chunk
- * instead of one spawn per file. This is the cold-run hot path — a Firefox-sized
- * checkout has hundreds of affected files, and the old per-file fan-out spent
- * ~99s in serial `git ls-tree`/`git diff` spawns.
+ * Batched equivalent of {@link fileExistsInHead}: returns the subset of
+ * `files` that are tracked in HEAD, using a single `git ls-tree` per ARG_MAX
+ * chunk instead of one spawn per file. This is the cold-run hot path — a
+ * Firefox-sized checkout has hundreds of affected files.
+ *
+ * `-r` lists nested blobs by full repo-relative path; `--name-only -z` makes
+ * the output a trivial NUL-split with no quoting to undo. Membership in the
+ * returned Set is exactly `await fileExistsInHead(repoDir, file)` for any
+ * non-directory `file`. Throws (via {@link git}) when HEAD itself is
+ * unresolvable, matching the per-file helper's failure mode.
  *
- * `-r` lists nested blobs by full repo-relative path; `--name-only -z` makes the
- * output a trivial NUL-split with no quoting to undo. Membership in the returned
- * Set is exactly `await fileExistsInHead(repoDir, file)` for any non-directory
- * `file`. Throws (via {@link git}) when HEAD itself is unresolvable, matching the
- * per-file helper's failure mode.
  * @param repoDir - Repository directory
  * @param files - Repo-relative paths to classify
  * @returns The subset of `files` present in HEAD
@@ -129,15 +129,15 @@ export async function listTrackedInHead(repoDir, files) {
  *
  * Uses {@link import('../utils/process.js').exec} rather than {@link git}
  * (which throws on a non-zero exit) because `git hash-object f1 f2 …` is
- * all-or-nothing: it aborts at the first unreadable path and emits nothing for
- * the rest. To preserve the old per-file contract — where one bad path zeroed
- * only its own index line — a chunk that does not return exactly one hash per
- * input falls back to hashing that chunk's paths individually. A path that is
- * still unhashable is simply left out of the map; the caller applies the
- * `0000000000` zero-hash fallback (and the same verbose log) for any miss, so
- * the blob hash is byte-identical to `git hash-object` (filters/.gitattributes
- * are applied per path) without the risk of in-process hashing, which would
- * diverge under `core.autocrlf`/`text` attributes.
+ * all-or-nothing: it aborts at the first unreadable path and emits nothing
+ * for the rest. To keep the per-file contract — where one bad path zeroes
+ * only its own index line — a chunk that does not return exactly one hash
+ * per input falls back to hashing that chunk's paths individually. A path
+ * that is still unhashable is left out of the map; the caller applies the
+ * `0000000000` zero-hash fallback for any miss. Hashing stays in git rather
+ * than in-process so filters and `.gitattributes` are applied per path and
+ * the result cannot diverge under `core.autocrlf`/`text` attributes.
+ *
  * @param repoDir - Repository directory
  * @param fullPaths - Absolute file paths to hash
  * @returns Map from each input path to its full blob hash (misses omitted)