@hominis/fireforge 0.43.0 → 0.44.0

package/dist/src/core/git-readonly-index.d.ts

@@ -1,32 +1,30 @@
 /**
  * Private-index scope for FireForge's READ-ONLY git plumbing.
  *
- * `git status` and `git diff HEAD` are read-only in the sense operators
- * care about — they never change tracked content — but they are NOT
- * read-only to git: both refresh the index's stat cache and write
- * `.git/index` (through `.git/index.lock`) when a file's stat data has
- * moved. That makes `fireforge verify` / `lint --per-patch` / `typecheck`
- * a second WRITER of the primary `engine/` checkout, even when the command
- * was pointed at a CoW tree clone.
+ * `git status` and `git diff HEAD` are read-only in the sense operators care
+ * about — they never change tracked content — but they are NOT read-only to
+ * git: both refresh the index's stat cache and write `.git/index` (through
+ * `.git/index.lock`) when a file's stat data has moved. That makes
+ * `fireforge verify` / `lint --per-patch` / `typecheck` a second WRITER of
+ * the primary `engine/` checkout, even when the command was pointed at a CoW
+ * tree clone.
  *
  * The consequence is not cosmetic. A concurrent `fireforge test`
  * fingerprints `engine/` before and after the harness run and refuses a
- * verdict taken across a change (`FAIL reason=inconclusive`). That refusal
- * is CORRECT and stays; the defect is that FireForge's own read-only
- * commands were tripping it. Measured downstream: perfect correlation
- * between lane overlap and inconclusive verdicts, on suites that had
- * actually passed.
+ * verdict taken across a change (`FAIL reason=inconclusive`). That refusal is
+ * CORRECT and stays; the defect is FireForge's own read-only commands
+ * tripping it.
  *
  * The fix is the standard git one: point the plumbing at a PRIVATE index
- * (`GIT_INDEX_FILE`) seeded from the repository's own, in a temp
- * directory. Refreshes land there and are thrown away; the primary
- * `.git/index` — and `.git/index.lock`, which is what made a concurrent
- * `git status` fail outright rather than merely churn — is never touched.
+ * (`GIT_INDEX_FILE`) seeded from the repository's own, in a temp directory.
+ * Refreshes land there and are thrown away; the primary `.git/index` — and
+ * `.git/index.lock`, which is what makes a concurrent `git status` fail
+ * outright rather than merely churn — is never touched.
  *
  * Fail-open by design: if the git dir or the index cannot be resolved or
- * copied, the scope simply does not activate and the commands behave
- * exactly as before. A read-only command must not start failing because
- * an optimisation could not be set up.
+ * copied, the scope does not activate and the commands behave exactly as
+ * before. A read-only command must not start failing because an optimisation
+ * could not be set up.
  *
  * The scope is process-global and non-reentrant on purpose: FireForge
  * commands are one-shot CLI invocations, and nesting two different private
@@ -57,3 +55,39 @@ export declare function hasReadOnlyGitIndexScope(): boolean;
  * @returns Whatever `operation` returns
  */
 export declare function withPrivateGitIndex<T>(repoDir: string, operation: () => Promise<T>): Promise<T>;
+/**
+ * A private index file plus the cleanup that removes it.
+ *
+ * `env` is meant to be handed to a SINGLE git invocation (or a small
+ * sequence of them), rather than installed process-wide the way
+ * {@link withPrivateGitIndex} installs a scope.
+ */
+export interface DisposableGitIndex {
+    /** Environment overlay pointing git at the private index. */
+    env: Record<string, string>;
+    /** Removes the private index. Never throws. */
+    dispose: () => Promise<void>;
+}
+/**
+ * Mints a private index seeded from `repoDir`'s own, for a caller that
+ * needs to WRITE the index without the write being visible to anyone else.
+ *
+ * The distinction from {@link withPrivateGitIndex} matters. That one exists
+ * so a read-only command's incidental index refreshes do not touch the
+ * primary checkout, and it is process-global, non-reentrant, and fail-open,
+ * all of which are right for that job. This one serves a caller whose index
+ * write is DELIBERATE and whose visibility is the defect: it is per-call, so
+ * two concurrent callers cannot collide, and it never depends on an ambient
+ * scope having been installed by whichever command happens to be running.
+ *
+ * The seed is a plain copy, which is safe against a concurrent writer: git
+ * writes the index through `index.lock` and an atomic rename, so a reader
+ * sees either the old file or the new one, never a torn one. Seeding is
+ * REQUIRED rather than merely tidy — an empty index makes a tracked,
+ * unmodified file look like a fresh add.
+ *
+ * @param repoDir - Repository whose index should be shadowed
+ * @returns The overlay and its cleanup, or undefined when one could not be
+ *   minted (a non-git directory, an unreadable index, no writable tmpdir)
+ */
+export declare function mintDisposableGitIndex(repoDir: string): Promise<DisposableGitIndex | undefined>;

package/dist/src/core/git-readonly-index.js

@@ -2,32 +2,30 @@
 /**
  * Private-index scope for FireForge's READ-ONLY git plumbing.
  *
- * `git status` and `git diff HEAD` are read-only in the sense operators
- * care about — they never change tracked content — but they are NOT
- * read-only to git: both refresh the index's stat cache and write
- * `.git/index` (through `.git/index.lock`) when a file's stat data has
- * moved. That makes `fireforge verify` / `lint --per-patch` / `typecheck`
- * a second WRITER of the primary `engine/` checkout, even when the command
- * was pointed at a CoW tree clone.
+ * `git status` and `git diff HEAD` are read-only in the sense operators care
+ * about — they never change tracked content — but they are NOT read-only to
+ * git: both refresh the index's stat cache and write `.git/index` (through
+ * `.git/index.lock`) when a file's stat data has moved. That makes
+ * `fireforge verify` / `lint --per-patch` / `typecheck` a second WRITER of
+ * the primary `engine/` checkout, even when the command was pointed at a CoW
+ * tree clone.
  *
  * The consequence is not cosmetic. A concurrent `fireforge test`
  * fingerprints `engine/` before and after the harness run and refuses a
- * verdict taken across a change (`FAIL reason=inconclusive`). That refusal
- * is CORRECT and stays; the defect is that FireForge's own read-only
- * commands were tripping it. Measured downstream: perfect correlation
- * between lane overlap and inconclusive verdicts, on suites that had
- * actually passed.
+ * verdict taken across a change (`FAIL reason=inconclusive`). That refusal is
+ * CORRECT and stays; the defect is FireForge's own read-only commands
+ * tripping it.
  *
  * The fix is the standard git one: point the plumbing at a PRIVATE index
- * (`GIT_INDEX_FILE`) seeded from the repository's own, in a temp
- * directory. Refreshes land there and are thrown away; the primary
- * `.git/index` — and `.git/index.lock`, which is what made a concurrent
- * `git status` fail outright rather than merely churn — is never touched.
+ * (`GIT_INDEX_FILE`) seeded from the repository's own, in a temp directory.
+ * Refreshes land there and are thrown away; the primary `.git/index` — and
+ * `.git/index.lock`, which is what makes a concurrent `git status` fail
+ * outright rather than merely churn — is never touched.
  *
  * Fail-open by design: if the git dir or the index cannot be resolved or
- * copied, the scope simply does not activate and the commands behave
- * exactly as before. A read-only command must not start failing because
- * an optimisation could not be set up.
+ * copied, the scope does not activate and the commands behave exactly as
+ * before. A read-only command must not start failing because an optimisation
+ * could not be set up.
  *
  * The scope is process-global and non-reentrant on purpose: FireForge
  * commands are one-shot CLI invocations, and nesting two different private
@@ -106,6 +104,56 @@ export async function withPrivateGitIndex(repoDir, operation) {
     const gitDir = await resolveGitDir(repoDir);
     if (gitDir === undefined)
         return operation();
+    const minted = await mintPrivateIndex(gitDir);
+    if (minted === undefined)
+        return operation();
+    activeScope = { repoDir: resolve(repoDir), indexFile: minted.indexFile };
+    verbose(`Private git index active for ${repoDir} (${minted.indexFile}).`);
+    try {
+        return await operation();
+    }
+    finally {
+        activeScope = undefined;
+        await minted.dispose();
+    }
+}
+/**
+ * Mints a private index seeded from `repoDir`'s own, for a caller that
+ * needs to WRITE the index without the write being visible to anyone else.
+ *
+ * The distinction from {@link withPrivateGitIndex} matters. That one exists
+ * so a read-only command's incidental index refreshes do not touch the
+ * primary checkout, and it is process-global, non-reentrant, and fail-open,
+ * all of which are right for that job. This one serves a caller whose index
+ * write is DELIBERATE and whose visibility is the defect: it is per-call, so
+ * two concurrent callers cannot collide, and it never depends on an ambient
+ * scope having been installed by whichever command happens to be running.
+ *
+ * The seed is a plain copy, which is safe against a concurrent writer: git
+ * writes the index through `index.lock` and an atomic rename, so a reader
+ * sees either the old file or the new one, never a torn one. Seeding is
+ * REQUIRED rather than merely tidy — an empty index makes a tracked,
+ * unmodified file look like a fresh add.
+ *
+ * @param repoDir - Repository whose index should be shadowed
+ * @returns The overlay and its cleanup, or undefined when one could not be
+ *   minted (a non-git directory, an unreadable index, no writable tmpdir)
+ */
+export async function mintDisposableGitIndex(repoDir) {
+    const gitDir = await resolveGitDir(repoDir);
+    if (gitDir === undefined)
+        return undefined;
+    const minted = await mintPrivateIndex(gitDir);
+    if (minted === undefined)
+        return undefined;
+    return { env: { GIT_INDEX_FILE: minted.indexFile }, dispose: minted.dispose };
+}
+/**
+ * Copies `gitDir`'s index into a fresh temp directory. Returns undefined
+ * rather than throwing: every caller has a defined behaviour for "no private
+ * index available", and none of them wants an exception from an optimisation.
+ */
+async function mintPrivateIndex(gitDir) {
     let tempDir;
     try {
         tempDir = await mkdtemp(join(tmpdir(), 'fireforge-roindex-'));
@@ -116,22 +164,18 @@ export async function withPrivateGitIndex(repoDir, operation) {
         if (await pathExists(sourceIndex)) {
             await copyFile(sourceIndex, privateIndex);
         }
-        activeScope = { repoDir: resolve(repoDir), indexFile: privateIndex };
-        verbose(`Private git index active for ${repoDir} (${privateIndex}).`);
+        const dir = tempDir;
+        return {
+            indexFile: privateIndex,
+            dispose: async () => {
+                await rm(dir, { recursive: true, force: true });
+            },
+        };
     }
     catch (error) {
-        // Fail-open: an unset-up scope must never fail a read-only command.
         verbose(`Private git index unavailable — ${toError(error).message}`);
-        activeScope = undefined;
         if (tempDir !== undefined)
             await rm(tempDir, { recursive: true, force: true });
-        return operation();
-    }
-    try {
-        return await operation();
-    }
-    finally {
-        activeScope = undefined;
-        await rm(tempDir, { recursive: true, force: true });
+        return undefined;
     }
 }

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

@@ -22,15 +22,14 @@ export declare function resolveMaxUntrackedFilesPerDir(): number;
  * Git status may report "?? dir/" instead of listing each file underneath.
  *
  * Expansion is capped per directory (FIREFORGE_MAX_UNTRACKED_FILES, default
- * 5000) with a warning on overflow. The cap used to exist only in the
- * status command's private expander; this shared one — used by reset,
- * discard, verify, lint, export-all — was unbounded, so e.g. `reset
- * --dry-run` after an interrupted download (unborn HEAD, the entire ~300k
- * file tree untracked) enumerated and printed every file.
+ * 5000) with a warning on overflow. Without the cap, `reset --dry-run` after
+ * an interrupted download — unborn HEAD, the entire ~300k file tree
+ * untracked — enumerates and prints every file.
  *
  * @param repoDir - Repository directory
  * @param entries - Parsed status entries
- * @returns Status entries with untracked directories expanded to individual files
+ * @returns Status entries with untracked directories expanded to individual
+ *   files
  */
 export declare function expandUntrackedDirectoryEntries(repoDir: string, entries: GitStatusEntry[]): Promise<GitStatusEntry[]>;
 /**

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

@@ -67,15 +67,14 @@ export function resolveMaxUntrackedFilesPerDir() {
  * Git status may report "?? dir/" instead of listing each file underneath.
  *
  * Expansion is capped per directory (FIREFORGE_MAX_UNTRACKED_FILES, default
- * 5000) with a warning on overflow. The cap used to exist only in the
- * status command's private expander; this shared one — used by reset,
- * discard, verify, lint, export-all — was unbounded, so e.g. `reset
- * --dry-run` after an interrupted download (unborn HEAD, the entire ~300k
- * file tree untracked) enumerated and printed every file.
+ * 5000) with a warning on overflow. Without the cap, `reset --dry-run` after
+ * an interrupted download — unborn HEAD, the entire ~300k file tree
+ * untracked — enumerates and prints every file.
  *
  * @param repoDir - Repository directory
  * @param entries - Parsed status entries
- * @returns Status entries with untracked directories expanded to individual files
+ * @returns Status entries with untracked directories expanded to individual
+ *   files
  */
 export async function expandUntrackedDirectoryEntries(repoDir, entries) {
     const expanded = [];

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

@@ -50,20 +50,19 @@ export declare function applyPatch(patchPath: string, repoDir: string, options?:
     reject?: boolean;
 }): Promise<void>;
 /**
- * Applies a patch idempotently using reverse-forward pattern.
- * First tries to reverse the patch (in case it's already applied),
- * then applies it forward.
+ * Applies a patch idempotently using reverse-forward pattern. First tries to
+ * reverse the patch (in case it is already applied), then applies it forward.
  *
  * @param patchPath - Path to the patch file
  * @param repoDir - Repository directory
  * @param options.reject - Fall back to `git apply --reject`
- * @param options.protectedFiles - Files that must NOT be reset to HEAD by
- *   the recovery step. Callers applying a patch QUEUE pass the files
- *   already touched by previously applied patches in the same run: two
- *   overlapping patches (an `--allow-overlap` queue) share files, and the
- *   blanket `checkout HEAD` used to wipe the earlier patch's changes from
- *   the shared file before applying the later one — leaving the engine in
- *   a hybrid state the summary never described.
+ * @param options.protectedFiles - Files that must NOT be reset to HEAD by the
+ *   recovery step. Callers applying a patch QUEUE pass the files already
+ *   touched by previously applied patches in the same run: two overlapping
+ *   patches (an `--allow-overlap` queue) share files, and a blanket
+ *   `checkout HEAD` would wipe the earlier patch's changes from the shared
+ *   file before applying the later one, leaving the engine in a hybrid state
+ *   the summary never describes.
  */
 export declare function applyPatchIdempotent(patchPath: string, repoDir: string, options?: {
     reject?: boolean;

package/dist/src/core/git.js

@@ -40,12 +40,10 @@ export async function ensureOriginRemote(dir) {
 // ── Large-tree staging helpers ──
 const GIT_ADD_ENV = { GIT_INDEX_THREADS: '0' };
 /**
- * Returns true when the error looks like a process killed by the spawn timeout
- * (SIGTERM → exit code 143) OR an AbortError raised by
- * `AbortSignal.timeout`. The AbortSignal path is the one observed during
- * the 2026-04-24 eval (Finding 10): Node's `child_process` layer
- * rejects with an AbortError when the signal fires, so the timeout
- * detection here needs to recognise that shape too.
+ * Returns true when the error looks like a process killed by the spawn
+ * timeout (SIGTERM → exit code 143) OR an AbortError raised by
+ * `AbortSignal.timeout` — Node's `child_process` layer rejects with an
+ * AbortError when the signal fires, so both shapes have to be recognised.
  */
 function isTimeoutError(error) {
     // `exec` now rejects with a typed ExecTimeoutError when its `timeout`
@@ -74,23 +72,20 @@ async function cleanupIndexLock(dir) {
     }
 }
 /**
- * Returns true when {@link relativePath} is ignored by `.gitignore` (or
- * any other exclusion mechanism git considers, e.g. `.git/info/exclude`,
- * core.excludesFile). Used by the chunked staging fallback to skip
- * entries that would otherwise fail `git add -- <path>` with the fatal
- * "The following paths are ignored by one of your .gitignore files"
- * error — a state the monolithic `git add -A` path silently handles.
+ * Returns true when {@link relativePath} is ignored by `.gitignore` (or any
+ * other exclusion mechanism git considers, e.g. `.git/info/exclude`,
+ * core.excludesFile). Used by the chunked staging fallback to skip entries
+ * that would otherwise fail `git add -- <path>` with the fatal "The
+ * following paths are ignored by one of your .gitignore files" error — a
+ * state the monolithic `git add -A` path silently handles. A Firefox
+ * checkout's top-level `.vscode/` is the common case: without this, the
+ * chunked invocation aborts the whole fallback and turns a recoverable
+ * monolithic timeout into a hard setup failure.
  *
- * Implementation: `git check-ignore -q -- <path>` exits 0 when the path
- * is ignored, 1 when it isn't, and >=128 on real failures. Treat
- * anything other than 0/1 as "unknown" and conservatively return false
- * so the chunk runs and any real underlying failure surfaces normally.
- *
- * 2026-04-26 eval Finding 4: a Firefox checkout's top-level `.vscode/`
- * is gitignored by the source tree's own `.gitignore`. Pre-fix, the
- * chunked `git add -- .vscode` invocation aborted the entire fallback
- * and turned a recoverable monolithic timeout into a hard setup
- * failure that required `fireforge download --force`.
+ * `git check-ignore -q -- <path>` exits 0 when the path is ignored, 1 when
+ * it is not, and >=128 on real failures. Anything other than 0/1 is treated
+ * as "unknown" and conservatively returns false, so the chunk runs and any
+ * real underlying failure surfaces normally.
  */
 async function isPathIgnored(dir, relativePath) {
     const result = await exec('git', ['check-ignore', '-q', '--', relativePath], { cwd: dir });
@@ -103,15 +98,14 @@ async function isPathIgnored(dir, relativePath) {
     return false;
 }
 /**
- * Stages every file by walking top-level directories one at a time.
- * This avoids a single monolithic `git add -A` that may time out on
- * very large (~300 K file) trees like Firefox.
+ * Stages every file by walking top-level directories one at a time. This
+ * avoids a single monolithic `git add -A` that may time out on very large
+ * (~300 K file) trees like Firefox.
  *
- * 2026-04-24 eval Finding 10: a chunked pass that hits its own timeout
- * now raises a typed {@link GitIndexingTimeoutError} rather than the
- * opaque `AbortError: The operation was aborted` the caller otherwise
- * saw. The typed error carries the environment-variable override so the
- * operator can extend the budget and re-run.
+ * A chunked pass that hits its own timeout raises a typed
+ * {@link GitIndexingTimeoutError} rather than an opaque `AbortError: The
+ * operation was aborted`; the typed error carries the environment-variable
+ * override so the operator can extend the budget and re-run.
  */
 async function stageAllFilesChunked(dir, scan, options = {}) {
     const { directories, topLevelFiles: topLevelCandidates } = scan;
@@ -160,10 +154,9 @@ async function stageAllFilesChunked(dir, scan, options = {}) {
 /**
  * Interval between heartbeat progress messages during the monolithic
  * `git add -A`. On a fresh ~600 MB Firefox tree the monolithic add runs
- * 60–120 seconds, during which git emits nothing to stdout/stderr. Without
- * a heartbeat the CLI spinner stays pinned on "Indexing Firefox source …"
- * for the full window, looks hung, and in the eval scenario operators
- * SIGINT'd mid-way assuming the process had stalled.
+ * 60–120 seconds, during which git emits nothing to stdout/stderr. Without a
+ * heartbeat the CLI spinner stays pinned on "Indexing Firefox source …" for
+ * the full window and looks hung, which invites a SIGINT mid-way.
  */
 const GIT_ADD_HEARTBEAT_MS = 15_000;
 const GIT_COMMIT_HEARTBEAT_MS = 15_000;
@@ -191,16 +184,12 @@ export async function stageAllFiles(dir, options = {}) {
     reportProgress?.('Scanning Firefox source tree before indexing...');
     const scan = await scanTopLevelSource(dir);
     reportProgress?.(`Source scan complete: ${scan.directories.length} top-level director${scan.directories.length === 1 ? 'y' : 'ies'}, ${scan.topLevelFiles.length} top-level file${scan.topLevelFiles.length === 1 ? '' : 's'}`);
-    // 2026-04-26 eval Finding 5: the pre-fix heartbeat used a single
-    // `heartbeatStartedAt` set at function entry and reported cumulative
-    // elapsed for the whole `stageAllFiles` invocation. After a
-    // monolithic timeout, the chunked-phase ticks therefore named
-    // numbers that already included the entire monolithic budget plus
-    // any host-sleep time, with no way for an operator watching the log
-    // to tell where the monolithic attempt ended and the chunked pass
-    // began. The heartbeat now tracks a per-phase start timestamp and
-    // labels each tick with the phase, so the chunked pass reports its
-    // own elapsed window and the monolithic→chunked handoff is visible.
+    // The heartbeat tracks a PER-PHASE start timestamp and labels each tick
+    // with the phase. A single start time set at function entry reports
+    // cumulative elapsed for the whole `stageAllFiles` invocation, so after a
+    // monolithic timeout the chunked-phase ticks name numbers that already
+    // include the entire monolithic budget, with no way to tell from the log
+    // where one attempt ended and the next began.
     let phase = 'monolithic';
     let phaseStartedAt = Date.now();
     const heartbeatTimer = reportProgress
@@ -223,13 +212,10 @@ export async function stageAllFiles(dir, options = {}) {
             if (!isTimeoutError(error)) {
                 throw await maybeWrapIndexLockError(dir, error);
             }
-            // 2026-04-24 eval Finding 10: the fallback transition used to be
-            // an implementation detail invisible to operators watching the
-            // spinner. Emit a loud, one-line banner so non-TTY log scrapers
-            // and TTY operators both see that the monolithic attempt lost and
-            // the chunked pass is starting. This was the missing signal in
-            // the eval log where the heartbeat went quiet for ~600s between
-            // the monolithic timeout and the chunked-pass failure.
+            // Emit a loud, one-line banner so non-TTY log scrapers and TTY
+            // operators both see that the monolithic attempt lost and the chunked
+            // pass is starting. Without it the fallback transition is invisible
+            // and the heartbeat simply goes quiet for minutes.
             options.onProgress?.(`Monolithic git add reached the ${Math.round(timeout / 1000)}s timeout; falling back to chunked staging. This pass may take several more minutes on a large tree.`);
         }
         // The killed process may have left an index lock
@@ -413,20 +399,19 @@ export async function applyPatch(patchPath, repoDir, options = {}) {
     }
 }
 /**
- * Applies a patch idempotently using reverse-forward pattern.
- * First tries to reverse the patch (in case it's already applied),
- * then applies it forward.
+ * Applies a patch idempotently using reverse-forward pattern. First tries to
+ * reverse the patch (in case it is already applied), then applies it forward.
  *
  * @param patchPath - Path to the patch file
  * @param repoDir - Repository directory
  * @param options.reject - Fall back to `git apply --reject`
- * @param options.protectedFiles - Files that must NOT be reset to HEAD by
- *   the recovery step. Callers applying a patch QUEUE pass the files
- *   already touched by previously applied patches in the same run: two
- *   overlapping patches (an `--allow-overlap` queue) share files, and the
- *   blanket `checkout HEAD` used to wipe the earlier patch's changes from
- *   the shared file before applying the later one — leaving the engine in
- *   a hybrid state the summary never described.
+ * @param options.protectedFiles - Files that must NOT be reset to HEAD by the
+ *   recovery step. Callers applying a patch QUEUE pass the files already
+ *   touched by previously applied patches in the same run: two overlapping
+ *   patches (an `--allow-overlap` queue) share files, and a blanket
+ *   `checkout HEAD` would wipe the earlier patch's changes from the shared
+ *   file before applying the later one, leaving the engine in a hybrid state
+ *   the summary never describes.
  */
 export async function applyPatchIdempotent(patchPath, repoDir, options = {}) {
     await ensureGit();
@@ -452,16 +437,15 @@ export async function applyPatchIdempotent(patchPath, repoDir, options = {}) {
     await applyPatch(patchPath, repoDir, options);
 }
 /**
- * Restores `files` to their HEAD state, deleting files the patch would
- * CREATE (present on disk from a partial apply but absent in HEAD — for
- * those, `git checkout HEAD --` fails, and the historical code ignored
- * that failure entirely, leaving stray files that made the subsequent
- * forward apply die with "already exists" and no hint why).
+ * Restores `files` to their HEAD state, deleting files the patch would CREATE
+ * (present on disk from a partial apply but absent in HEAD — for those,
+ * `git checkout HEAD --` fails, and ignoring that failure leaves stray files
+ * that make the subsequent forward apply die with "already exists" and no
+ * hint why).
  *
- * Every git invocation is chunked via {@link chunkPathspecs} so a very
- * large patch cannot hit `E2BIG`, and every exit code is checked — a
- * silent failed restore is precisely the confusing state this recovery
- * step exists to prevent.
+ * Every git invocation is chunked via {@link chunkPathspecs} so a very large
+ * patch cannot hit `E2BIG`, and every exit code is checked — a silent failed
+ * restore is the confusing state this recovery step exists to prevent.
  */
 async function restoreFilesToHead(repoDir, patchPath, files) {
     // Partition into tracked-in-HEAD (restore via checkout) and absent-in-HEAD

package/dist/src/core/license-headers.d.ts

@@ -23,21 +23,19 @@ export declare function getLicenseHeader(license: ProjectLicense, style: Comment
  *
  * For `js` files, MPL-2.0 is also accepted in the upstream Mozilla block-
  * comment form (`/* ... *\/`) used by the Firefox source tree, not just the
- * `// ` line-comment form `getLicenseHeader` emits. Without that, a new JS
- * file copied from upstream Firefox (or written to match the surrounding
- * code's convention) hit `missing-license-header` even with a verbatim
- * standard MPL header — operators were forced to `--skip-lint` over a real
- * false positive.
+ * `// ` line-comment form `getLicenseHeader` emits — otherwise a new JS file
+ * copied from upstream Firefox hits `missing-license-header` even with a
+ * verbatim standard MPL header.
  *
  * Editor-directive block comments (`/* -*- ... -*- *\/`, `/* vim: ... *\/`)
- * leading the file are tolerated — Mozilla's canonical layout puts those
- * on lines 1–2 with the MPL header on lines 3+, which the raw
- * `startsWith` check would otherwise miss.
+ * leading the file are tolerated: Mozilla's canonical layout puts those on
+ * lines 1–2 with the MPL header on lines 3+, which a raw `startsWith` check
+ * would miss.
  *
- * The MPL-2.0 header is additionally matched on normalized whitespace
- * (see {@link normalizeCommentHead}) so upstream files using the older
- * Mozilla wrap — breaking after "file," instead of "with this" — are
- * accepted too; only the wrap position differs, never the wording.
+ * The MPL-2.0 header is additionally matched on normalized whitespace (see
+ * {@link normalizeCommentHead}) so upstream files using the older Mozilla
+ * wrap — breaking after "file," instead of "with this" — are accepted too;
+ * only the wrap position differs, never the wording.
  *
  * @param content - File content to check
  * @param style   - Comment syntax of the file
@@ -46,22 +44,18 @@ export declare function hasAnyLicenseHeader(content: string, style: CommentStyle
 /**
  * Returns true if `content` starts with the verbatim upstream Mozilla
  * MPL-2.0 block header (`/* This Source Code Form … *\/`), optionally
- * preceded by editor-directive comments — the exact shape a JS file
- * copied from the Firefox source tree carries.
+ * preceded by editor-directive comments — the exact shape a JS file copied
+ * from the Firefox source tree carries.
  *
  * Deliberately independent of the project license: a new JS file that
- * legitimately keeps its upstream MPL block header (copied-from-upstream
- * provenance) is valid in an EUPL/GPL/0BSD project too. Before 0.35.0
- * this acceptance only existed behind a `license === 'MPL-2.0'` gate in
- * patch-lint, making it dead code for every other project license and
- * forcing repo-side audit workarounds.
+ * legitimately keeps its upstream MPL block header is valid in an
+ * EUPL/GPL/0BSD project too.
  *
  * Matching is wrap-agnostic: after the exact `startsWith` fast path, the
  * leading block comment is compared on normalized whitespace (see
- * {@link normalizeCommentHead}) so the older upstream wrap — breaking
- * after "file," instead of "with this", as `ext-browser.js` ships —
- * passes too. Only the line-break position may differ; altered wording
- * still rejects.
+ * {@link normalizeCommentHead}) so the older upstream wrap — breaking after
+ * "file," instead of "with this", as `ext-browser.js` ships — passes too.
+ * Only the line-break position may differ; altered wording still rejects.
  *
  * @param content - File content to check
  */

package/dist/src/core/license-headers.js

@@ -145,21 +145,19 @@ function normalizeCommentHead(content, style) {
  *
  * For `js` files, MPL-2.0 is also accepted in the upstream Mozilla block-
  * comment form (`/* ... *\/`) used by the Firefox source tree, not just the
- * `// ` line-comment form `getLicenseHeader` emits. Without that, a new JS
- * file copied from upstream Firefox (or written to match the surrounding
- * code's convention) hit `missing-license-header` even with a verbatim
- * standard MPL header — operators were forced to `--skip-lint` over a real
- * false positive.
+ * `// ` line-comment form `getLicenseHeader` emits — otherwise a new JS file
+ * copied from upstream Firefox hits `missing-license-header` even with a
+ * verbatim standard MPL header.
  *
  * Editor-directive block comments (`/* -*- ... -*- *\/`, `/* vim: ... *\/`)
- * leading the file are tolerated — Mozilla's canonical layout puts those
- * on lines 1–2 with the MPL header on lines 3+, which the raw
- * `startsWith` check would otherwise miss.
+ * leading the file are tolerated: Mozilla's canonical layout puts those on
+ * lines 1–2 with the MPL header on lines 3+, which a raw `startsWith` check
+ * would miss.
  *
- * The MPL-2.0 header is additionally matched on normalized whitespace
- * (see {@link normalizeCommentHead}) so upstream files using the older
- * Mozilla wrap — breaking after "file," instead of "with this" — are
- * accepted too; only the wrap position differs, never the wording.
+ * The MPL-2.0 header is additionally matched on normalized whitespace (see
+ * {@link normalizeCommentHead}) so upstream files using the older Mozilla
+ * wrap — breaking after "file," instead of "with this" — are accepted too;
+ * only the wrap position differs, never the wording.
  *
  * @param content - File content to check
  * @param style   - Comment syntax of the file
@@ -183,22 +181,18 @@ export function hasAnyLicenseHeader(content, style) {
 /**
  * Returns true if `content` starts with the verbatim upstream Mozilla
  * MPL-2.0 block header (`/* This Source Code Form … *\/`), optionally
- * preceded by editor-directive comments — the exact shape a JS file
- * copied from the Firefox source tree carries.
+ * preceded by editor-directive comments — the exact shape a JS file copied
+ * from the Firefox source tree carries.
  *
  * Deliberately independent of the project license: a new JS file that
- * legitimately keeps its upstream MPL block header (copied-from-upstream
- * provenance) is valid in an EUPL/GPL/0BSD project too. Before 0.35.0
- * this acceptance only existed behind a `license === 'MPL-2.0'` gate in
- * patch-lint, making it dead code for every other project license and
- * forcing repo-side audit workarounds.
+ * legitimately keeps its upstream MPL block header is valid in an
+ * EUPL/GPL/0BSD project too.
  *
  * Matching is wrap-agnostic: after the exact `startsWith` fast path, the
  * leading block comment is compared on normalized whitespace (see
- * {@link normalizeCommentHead}) so the older upstream wrap — breaking
- * after "file," instead of "with this", as `ext-browser.js` ships —
- * passes too. Only the line-break position may differ; altered wording
- * still rejects.
+ * {@link normalizeCommentHead}) so the older upstream wrap — breaking after
+ * "file," instead of "with this", as `ext-browser.js` ships — passes too.
+ * Only the line-break position may differ; altered wording still rejects.
  *
  * @param content - File content to check
  */