@hominis/fireforge 0.45.0 → 0.46.1

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

@@ -11,27 +11,16 @@ import { chunkPathspecs, ensureGit, git } from './git-base.js';
  * @param filePath - Path to the file (relative to repo)
  */
 export async function restoreTrackedPath(repoDir, filePath) {
-    await ensureGit();
     await git(['restore', '--source', 'HEAD', '--staged', '--worktree', '--', filePath], repoDir);
 }
-/**
- * Removes an untracked path from disk.
- * @param repoDir - Repository directory
- * @param filePath - Path to the file (relative to repo)
- */
-async function removeUntrackedPath(repoDir, filePath) {
-    const fullPath = join(repoDir, filePath);
-    await removeFile(fullPath);
-}
 /**
  * Removes a path that is present only in the index/worktree and not in HEAD.
  * @param repoDir - Repository directory
  * @param filePath - Path to remove
  */
 async function removeAddedPath(repoDir, filePath) {
-    await ensureGit();
     await git(['reset', 'HEAD', '--', filePath], repoDir);
-    await removeUntrackedPath(repoDir, filePath);
+    await removeFile(join(repoDir, filePath));
 }
 /**
  * Discards a status entry according to its git state.
@@ -40,7 +29,7 @@ async function removeAddedPath(repoDir, filePath) {
  */
 export async function discardStatusEntry(repoDir, entry) {
     if (entry.isUntracked) {
-        await removeUntrackedPath(repoDir, entry.file);
+        await removeFile(join(repoDir, entry.file));
         return;
     }
     if (entry.isRenameOrCopy && entry.originalPath) {
@@ -65,7 +54,6 @@ export async function discardStatusEntry(repoDir, entry) {
  * @param files - File paths to stage (relative to repo)
  */
 export async function stageFiles(repoDir, files) {
-    await ensureGit();
     await git(['add', '--', ...files], repoDir);
 }
 /**
@@ -74,7 +62,6 @@ export async function stageFiles(repoDir, files) {
  * @param files - File paths to unstage (relative to repo)
  */
 export async function unstageFiles(repoDir, files) {
-    await ensureGit();
     await git(['reset', 'HEAD', '--', ...files], repoDir);
 }
 /**
@@ -84,16 +71,15 @@ export async function unstageFiles(repoDir, files) {
  * @returns true if file exists in HEAD
  */
 export async function fileExistsInHead(repoDir, filePath) {
-    await ensureGit();
     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.
+ * chunk instead of one spawn per file. This is the cold-run hot path, and
+ * a Firefox-sized checkout has hundreds of affected files.
  *
- * `-r` lists nested blobs by full repo-relative path; `--name-only -z` makes
+ * `-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
@@ -107,13 +93,12 @@ export async function listTrackedInHead(repoDir, files) {
     const tracked = new Set();
     if (files.length === 0)
         return tracked;
-    await ensureGit();
     const wanted = new Set(files);
     for (const chunk of chunkPathspecs(files)) {
         const output = await git(['ls-tree', '-r', 'HEAD', '--name-only', '-z', '--', ...chunk], repoDir);
         for (const name of output.split('\0')) {
             // `ls-tree -r` can surface entries beyond the literal inputs only when an
-            // input is itself a directory in HEAD; intersect with `wanted` so the
+            // input is itself a directory in HEAD. Intersect with `wanted` so the
             // result is always a subset of the requested files, never a superset.
             if (name.length > 0 && wanted.has(name))
                 tracked.add(name);
@@ -130,10 +115,10 @@ 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 keep the per-file contract — where one bad path zeroes
- * only its own index line — a chunk that does not return exactly one hash
+ * 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
+ * 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.
@@ -151,8 +136,8 @@ export async function hashObjectBatch(repoDir, fullPaths) {
         const result = await exec('git', ['hash-object', '--', ...chunk], { cwd: repoDir });
         const lines = result.stdout.split('\n').filter((line) => line.length > 0);
         if (result.exitCode === 0 && lines.length === chunk.length) {
-            for (let i = 0; i < chunk.length; i++) {
-                hashes.set(chunk[i], lines[i]);
+            for (const [i, path] of chunk.entries()) {
+                hashes.set(path, lines[i]);
             }
             continue;
         }
@@ -190,15 +175,6 @@ export async function getFileContentAtRef(repoDir, filePath, ref = 'HEAD') {
     }
     return result.stdout;
 }
-/**
- * Gets the content of a file from HEAD commit.
- * @param repoDir - Repository directory
- * @param filePath - Path to the file (relative to repo)
- * @returns File content or null if file doesn't exist in HEAD
- */
-export async function getFileContentFromHead(repoDir, filePath) {
-    return getFileContentAtRef(repoDir, filePath, 'HEAD');
-}
 /**
  * Checks if a file is binary by looking for NUL bytes in the first 8KB.
  * Uses the same heuristic as git.

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

@@ -1,25 +1,25 @@
 /**
- * Private-index scope for FireForge's READ-ONLY git plumbing.
+ * 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
+ * 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
+ * `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 FireForge's own read-only commands
+ * 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
+ * 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 makes a concurrent `git status` fail
- * outright rather than merely churn — is never touched.
+ * Refreshes land there and are thrown away. The primary `.git/index` is
+ * never touched, and neither is `.git/index.lock`, which is what makes a
+ * concurrent `git status` fail outright rather than merely churn.
  *
  * Fail-open by design: if the git dir or the index cannot be resolved or
  * copied, the scope does not activate and the commands behave exactly as
@@ -43,8 +43,6 @@
  * @returns `{ GIT_INDEX_FILE }` when scoped, otherwise undefined
  */
 export declare function readOnlyGitIndexEnv(cwd: string): Record<string, string> | undefined;
-/** True while a private-index scope is installed (diagnostics and tests). */
-export declare function hasReadOnlyGitIndexScope(): boolean;
 /**
  * Runs `operation` with FireForge's git plumbing pointed at a private
  * index seeded from `repoDir`'s own, so the primary checkout's
@@ -58,7 +56,7 @@ export declare function withPrivateGitIndex<T>(repoDir: string, operation: () =>
 /**
  * A private index file plus the cleanup that removes it.
  *
- * `env` is meant to be handed to a SINGLE git invocation (or a small
+ * `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.
  */
@@ -70,20 +68,20 @@ export interface DisposableGitIndex {
 }
 /**
  * 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.
+ * 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
+ * write is intentional 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,
+ * 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

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

@@ -1,26 +1,26 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Private-index scope for FireForge's READ-ONLY git plumbing.
+ * 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
+ * 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
+ * `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 FireForge's own read-only commands
+ * 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
+ * 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 makes a concurrent `git status` fail
- * outright rather than merely churn — is never touched.
+ * Refreshes land there and are thrown away. The primary `.git/index` is
+ * never touched, and neither is `.git/index.lock`, which is what makes a
+ * concurrent `git status` fail outright rather than merely churn.
  *
  * Fail-open by design: if the git dir or the index cannot be resolved or
  * copied, the scope does not activate and the commands behave exactly as
@@ -64,13 +64,9 @@ export function readOnlyGitIndexEnv(cwd) {
         return undefined;
     return { GIT_INDEX_FILE: activeScope.indexFile };
 }
-/** True while a private-index scope is installed (diagnostics and tests). */
-export function hasReadOnlyGitIndexScope() {
-    return activeScope !== undefined;
-}
 /**
  * Resolves a repository's git directory. Returns undefined for anything
- * that is not a readable git checkout — `engine/` is not always one
+ * that is not a readable git checkout. `engine/` is not always one
  * (`fireforge download` extracts a source tarball).
  */
 async function resolveGitDir(repoDir) {
@@ -119,20 +115,20 @@ export async function withPrivateGitIndex(repoDir, operation) {
 }
 /**
  * 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.
+ * 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
+ * write is intentional 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,
+ * 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

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

@@ -1,6 +1,13 @@
 import type { GitStatusEntry } from './git-base.js';
 /**
  * Parses NUL-delimited porcelain status output.
+ *
+ * A rename or copy occupies two NUL records (`XY new\0old\0`), and the `R`/`C`
+ * may sit in either column: git >= 2.18 detects renames in the worktree too
+ * (`status.renames`), emitting ` R new\0old\0` for an unstaged rename and
+ * `RM`/`R ` for a staged one. Only consuming the second record for an index
+ * `R`/`C` turned the worktree form's `old` field into a bogus extra entry
+ * whose status was whatever its first two path characters happened to be.
  * @param output - Raw git status output
  * @returns Parsed entries
  */
@@ -23,8 +30,8 @@ export declare function resolveMaxUntrackedFilesPerDir(): number;
  *
  * Expansion is capped per directory (FIREFORGE_MAX_UNTRACKED_FILES, default
  * 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.
+ * 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

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

@@ -1,8 +1,25 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { warn } from '../utils/logger.js';
-import { ensureGit, git } from './git-base.js';
+import { git } from './git-base.js';
+/**
+ * True when a porcelain status column carries a rename or copy, i.e. the
+ * record is followed by a second NUL-terminated field holding the original
+ * path.
+ * @param column - A single status column character
+ * @returns Whether the column is `R` or `C`
+ */
+function isRenameOrCopyColumn(column) {
+    return column === 'R' || column === 'C';
+}
 /**
  * Parses NUL-delimited porcelain status output.
+ *
+ * A rename or copy occupies two NUL records (`XY new\0old\0`), and the `R`/`C`
+ * may sit in either column: git >= 2.18 detects renames in the worktree too
+ * (`status.renames`), emitting ` R new\0old\0` for an unstaged rename and
+ * `RM`/`R ` for a staged one. Only consuming the second record for an index
+ * `R`/`C` turned the worktree form's `old` field into a bogus extra entry
+ * whose status was whatever its first two path characters happened to be.
  * @param output - Raw git status output
  * @returns Parsed entries
  */
@@ -18,7 +35,7 @@ export function parsePorcelainStatus(output) {
         const worktreeStatus = record[1] ?? ' ';
         const status = `${indexStatus}${worktreeStatus}`;
         const pathField = record.slice(3);
-        const isRenameOrCopy = indexStatus === 'R' || indexStatus === 'C';
+        const isRenameOrCopy = isRenameOrCopyColumn(indexStatus) || isRenameOrCopyColumn(worktreeStatus);
         const originalPath = isRenameOrCopy ? records[i + 1] : undefined;
         if (isRenameOrCopy) {
             i++;
@@ -42,7 +59,6 @@ export function parsePorcelainStatus(output) {
  * @returns Parsed git status entries
  */
 export async function getWorkingTreeStatus(repoDir) {
-    await ensureGit();
     return parsePorcelainStatus(await git(['status', '--porcelain=v1', '-z'], repoDir));
 }
 /** Default per-directory cap for untracked-directory expansion. */
@@ -57,7 +73,7 @@ export function resolveMaxUntrackedFilesPerDir() {
         return DEFAULT_MAX_UNTRACKED_FILES_PER_DIR;
     const parsed = Number.parseInt(raw, 10);
     if (!Number.isFinite(parsed) || parsed <= 0) {
-        warn(`Ignoring FIREFORGE_MAX_UNTRACKED_FILES="${raw}" — expected a positive integer. Falling back to ${String(DEFAULT_MAX_UNTRACKED_FILES_PER_DIR)}.`);
+        warn(`Ignoring FIREFORGE_MAX_UNTRACKED_FILES="${raw}" — expected a positive integer. Falling back to ${DEFAULT_MAX_UNTRACKED_FILES_PER_DIR}.`);
         return DEFAULT_MAX_UNTRACKED_FILES_PER_DIR;
     }
     return parsed;
@@ -68,8 +84,8 @@ export function resolveMaxUntrackedFilesPerDir() {
  *
  * Expansion is capped per directory (FIREFORGE_MAX_UNTRACKED_FILES, default
  * 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.
+ * 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
@@ -86,7 +102,7 @@ export async function expandUntrackedDirectoryEntries(repoDir, entries) {
         }
         const individualFiles = await getUntrackedFilesInDir(repoDir, entry.file);
         if (individualFiles.length > maxPerDir) {
-            warn(`Untracked directory ${entry.file} contains ${String(individualFiles.length)} files — only the first ${String(maxPerDir)} are listed. Add a .gitignore entry or clean the directory.`);
+            warn(`Untracked directory ${entry.file} contains ${individualFiles.length} files — only the first ${maxPerDir} are listed. Add a .gitignore entry or clean the directory.`);
         }
         for (const file of individualFiles.slice(0, maxPerDir)) {
             expanded.push({
@@ -108,7 +124,6 @@ export async function expandUntrackedDirectoryEntries(repoDir, entries) {
  * @returns List of untracked file paths
  */
 export async function getUntrackedFiles(repoDir) {
-    await ensureGit();
     // Use git ls-files to get all untracked files, which properly expands directories
     const output = await git(['ls-files', '--others', '--exclude-standard'], repoDir);
     return output.split('\n').filter((line) => line.trim().length > 0);
@@ -121,7 +136,6 @@ export async function getUntrackedFiles(repoDir) {
  * @returns List of untracked file paths relative to repo root
  */
 export async function getUntrackedFilesInDir(repoDir, dir) {
-    await ensureGit();
     const output = await git(['ls-files', '--others', '--exclude-standard', '--', dir], repoDir);
     return output.split('\n').filter((line) => line.trim().length > 0);
 }
@@ -133,7 +147,6 @@ export async function getUntrackedFilesInDir(repoDir, dir) {
  * @returns List of modified file paths relative to repo root
  */
 export async function getModifiedFilesInDir(repoDir, dir) {
-    await ensureGit();
     const output = await git(['diff', '--name-only', 'HEAD', '--', dir], repoDir);
     return output.split('\n').filter((line) => line.trim().length > 0);
 }
@@ -146,7 +159,6 @@ export async function getModifiedFilesInDir(repoDir, dir) {
 export async function getDirtyFiles(repoDir, files) {
     if (files.length === 0)
         return [];
-    await ensureGit();
     // Check both staged and unstaged changes for the given files
     const trackedOutput = await git(['diff', '--name-only', 'HEAD', '--', ...files], repoDir);
     const tracked = trackedOutput.split('\n').filter((line) => line.trim().length > 0);

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

@@ -17,7 +17,7 @@ export declare function isGitRepository(dir: string): Promise<boolean>;
 export declare function ensureOriginRemote(dir: string): Promise<void>;
 /**
  * Stages all files in the repository.
- * Tries a monolithic `git add -A` first; if that times out, falls back to
+ * Tries a monolithic `git add -A` first. If that times out, falls back to
  * directory-by-directory staged adds.
  */
 export declare function stageAllFiles(dir: string, options?: {
@@ -56,8 +56,8 @@ export declare function applyPatch(patchPath: string, repoDir: string, options?:
  * @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
+ * @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
@@ -103,12 +103,6 @@ export declare function getCurrentBranch(repoDir: string): Promise<string>;
  * @param repoDir - Repository directory
  */
 export declare function resetChanges(repoDir: string): Promise<void>;
-/**
- * Creates a commit with all current changes.
- * @param repoDir - Repository directory
- * @param message - Commit message
- */
-export declare function commit(repoDir: string, message: string): Promise<void>;
 /**
  * Gets the status of files with their status codes.
  * @param repoDir - Repository directory

package/dist/src/core/git.js

@@ -41,8 +41,8 @@ export async function ensureOriginRemote(dir) {
 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` — Node's `child_process` layer rejects with an
+ * 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) {
@@ -76,7 +76,7 @@ async function cleanupIndexLock(dir) {
  * 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
+ * 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
@@ -93,7 +93,7 @@ async function isPathIgnored(dir, relativePath) {
         return true;
     if (result.exitCode === 1)
         return false;
-    // Any other shape is "we don't know" — let the caller proceed and
+    // Any other shape is "we don't know", so let the caller proceed and
     // surface the real error if `git add` rejects the path.
     return false;
 }
@@ -104,7 +104,7 @@ async function isPathIgnored(dir, relativePath) {
  *
  * 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
+ * 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 = {}) {
@@ -134,7 +134,7 @@ async function stageAllFilesChunked(dir, scan, options = {}) {
         options.onProgress?.(`Staging directory ${stagedDirectories}/${directories.length}: ${dirName}/...`);
         await runChunk(['add', '--', dirName], dirName);
     }
-    // Stage any top-level files (excluding gitignored ones — `git add`
+    // Stage any top-level files (excluding gitignored ones, because `git add`
     // on an explicit ignored path errors out, which would otherwise
     // abort the chunked fallback after the monolithic path has already
     // timed out).
@@ -154,7 +154,7 @@ 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
+ * 60 to 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.
  */
@@ -175,7 +175,7 @@ async function scanTopLevelSource(dir) {
 }
 /**
  * Stages all files in the repository.
- * Tries a monolithic `git add -A` first; if that times out, falls back to
+ * Tries a monolithic `git add -A` first. If that times out, falls back to
  * directory-by-directory staged adds.
  */
 export async function stageAllFiles(dir, options = {}) {
@@ -184,7 +184,7 @@ 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'}`);
-    // The heartbeat tracks a PER-PHASE start timestamp and labels each tick
+    // 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
@@ -225,15 +225,8 @@ export async function stageAllFiles(dir, options = {}) {
         // monolithic budget forward.
         phase = 'chunked';
         phaseStartedAt = Date.now();
-        try {
-            await stageAllFilesChunked(dir, scan, options);
-            reportProgress?.('Git phase complete: chunked source indexing finished.');
-        }
-        catch (error) {
-            if (error instanceof GitIndexingTimeoutError)
-                throw error;
-            throw error;
-        }
+        await stageAllFilesChunked(dir, scan, options);
+        reportProgress?.('Git phase complete: chunked source indexing finished.');
     }
     finally {
         if (heartbeatTimer)
@@ -285,10 +278,20 @@ export async function initRepository(dir, branchName = 'main', options = {}) {
     reportProgress('Configuring origin remote for build compatibility...');
     await git(['remote', 'add', 'origin', 'https://github.com/mozilla-firefox/firefox'], dir);
     reportProgress('Git phase complete: source git repository metadata initialized.');
+    await stageAndCommitSource(dir, reportProgress, 'Indexing Firefox source with git add -A (this can take several minutes on large trees)...');
+}
+/**
+ * The tail shared by {@link initRepository} and {@link resumeRepository}:
+ * normalizes the Firefox ignore files, stages the whole tree, and creates
+ * the initial source commit. Index-lock failures on either git step are
+ * wrapped into the typed lock error so both entry points report them the
+ * same way.
+ */
+async function stageAndCommitSource(dir, reportProgress, stagingMessage) {
     reportProgress('Normalizing Firefox ignore files for Git-backed mach lint compatibility...');
     await ensureFirefoxIgnorefileCompatibility(dir);
     // Add all files
-    reportProgress('Indexing Firefox source with git add -A (this can take several minutes on large trees)...');
+    reportProgress(stagingMessage);
     await assertNoGitIndexLock(dir);
     try {
         await stageAllFiles(dir, { onProgress: reportProgress });
@@ -310,7 +313,6 @@ export async function initRepository(dir, branchName = 'main', options = {}) {
  * cleans up stale locks, stages all files, and creates the initial commit.
  */
 export async function resumeRepository(dir, options = {}) {
-    await ensureGit();
     const reportProgress = options.onProgress ?? (() => { });
     if (!(await isGitRepository(dir))) {
         throw new GitError('Not a git repository', 'resume');
@@ -324,24 +326,7 @@ export async function resumeRepository(dir, options = {}) {
     await cleanupIndexLock(dir);
     // Ensure origin remote exists (may have been added before the interrupt)
     await ensureOriginRemote(dir);
-    reportProgress('Normalizing Firefox ignore files for Git-backed mach lint compatibility...');
-    await ensureFirefoxIgnorefileCompatibility(dir);
-    // Stage all files
-    reportProgress('Indexing Firefox source (resuming)...');
-    await assertNoGitIndexLock(dir);
-    try {
-        await stageAllFiles(dir, { onProgress: reportProgress });
-    }
-    catch (error) {
-        throw await maybeWrapIndexLockError(dir, error);
-    }
-    // Create initial commit
-    try {
-        await createInitialSourceCommit(dir, reportProgress);
-    }
-    catch (error) {
-        throw await maybeWrapIndexLockError(dir, error);
-    }
+    await stageAndCommitSource(dir, reportProgress, 'Indexing Firefox source (resuming)...');
 }
 async function assertNoGitIndexLock(dir) {
     const lockPath = join(dir, '.git', 'index.lock');
@@ -407,8 +392,8 @@ export async function applyPatch(patchPath, repoDir, options = {}) {
  * @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
+ * @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
@@ -439,14 +424,14 @@ 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,
+ * Restores `files` to their HEAD state, deleting files the patch would create
+ * (present on disk from a partial apply but absent in HEAD, where
  * `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
+ * 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) {
@@ -499,7 +484,6 @@ export async function reversePatch(patchPath, repoDir) {
  * @returns True if there are uncommitted changes
  */
 export async function hasChanges(repoDir) {
-    await ensureGit();
     const entries = await getWorkingTreeStatus(repoDir);
     return entries.length > 0;
 }
@@ -518,7 +502,6 @@ export function isMissingHeadError(error) {
  * @returns Commit hash
  */
 export async function getHead(repoDir) {
-    await ensureGit();
     const output = await git(['rev-parse', 'HEAD'], repoDir);
     return output.trim();
 }
@@ -528,7 +511,6 @@ export async function getHead(repoDir) {
  * @returns Branch name
  */
 export async function getCurrentBranch(repoDir) {
-    await ensureGit();
     const output = await git(['rev-parse', '--abbrev-ref', 'HEAD'], repoDir);
     return output.trim();
 }
@@ -537,7 +519,6 @@ export async function getCurrentBranch(repoDir) {
  * @param repoDir - Repository directory
  */
 export async function resetChanges(repoDir) {
-    await ensureGit();
     try {
         await git(['reset', '--hard', 'HEAD'], repoDir);
     }
@@ -546,16 +527,6 @@ export async function resetChanges(repoDir) {
     }
     await git(['clean', '-fd'], repoDir);
 }
-/**
- * Creates a commit with all current changes.
- * @param repoDir - Repository directory
- * @param message - Commit message
- */
-export async function commit(repoDir, message) {
-    await ensureGit();
-    await stageAllFiles(repoDir);
-    await git(['commit', '-m', message], repoDir);
-}
 /**
  * Gets the status of files with their status codes.
  * @param repoDir - Repository directory