@hominis/fireforge 0.31.0 → 0.33.0

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

@@ -7,8 +7,8 @@ import { toError } from '../utils/errors.js';
 import { pathExists, readText } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
 import { exec } from '../utils/process.js';
-import { ensureGit, git } from './git-base.js';
-import { fileExistsInHead, isBinaryFile } from './git-file-ops.js';
+import { chunkPathspecs, ensureGit, git } from './git-base.js';
+import { fileExistsInHead, hashObjectBatch, isBinaryFile, listTrackedInHead, } from './git-file-ops.js';
 import { getUntrackedFiles, getUntrackedFilesInDir } from './git-status.js';
 async function execGitWithAllowedExitCodes(repoDir, args, allowedExitCodes = [0]) {
     const result = await exec('git', args, { cwd: repoDir });
@@ -28,35 +28,33 @@ export async function getFileDiff(repoDir, filePath) {
     return git(['diff', 'HEAD', '--', filePath], repoDir);
 }
 /**
- * Generates a unified diff for a new (untracked) file.
- * @param repoDir - Repository directory
+ * Abbreviates a full git blob hash to the 10-character form used in the
+ * synthesized `index 0000000000..<hash>` line, falling back to the all-zero
+ * placeholder when no usable hash is available. Mirrors the original per-file
+ * truncation exactly.
+ * @param fullHash - Full blob hash, or undefined when hashing failed
+ * @returns 10-character abbreviated hash or the zero placeholder
+ */
+function abbreviateBlobHash(fullHash) {
+    if (fullHash !== undefined && fullHash.length >= 10) {
+        return fullHash.slice(0, 10);
+    }
+    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.
  * @param filePath - Path to the file (relative to repo)
+ * @param content - File content
+ * @param blobHash - Abbreviated blob hash for the index line
  * @returns Diff content in unified diff format
  */
-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`).
-    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}`);
-    }
-    const content = await readText(fullPath);
-    // Compute the abbreviated git blob hash for the index line
-    let blobHash = '0000000000';
-    try {
-        const fullHash = (await git(['hash-object', fullPath], repoDir)).trim();
-        if (fullHash.length >= 10) {
-            blobHash = fullHash.slice(0, 10);
-        }
-    }
-    catch (error) {
-        verbose(`git hash-object failed for ${filePath}; falling back to zero blob hash: ${toError(error).message}`);
-    }
+function buildNewFileDiffBody(filePath, content, blobHash) {
     // Handle empty files
     if (content.length === 0) {
         return [
@@ -91,6 +89,36 @@ export async function generateNewFileDiff(repoDir, filePath) {
     }
     return diffLines.join('\n') + '\n';
 }
+/**
+ * Generates a unified diff for a new (untracked) file.
+ * @param repoDir - Repository directory
+ * @param filePath - Path to the file (relative to repo)
+ * @returns Diff content in unified diff format
+ */
+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`).
+    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}`);
+    }
+    const content = await readText(fullPath);
+    // Compute the abbreviated git blob hash for the index line
+    let blobHash = '0000000000';
+    try {
+        const fullHash = (await git(['hash-object', fullPath], repoDir)).trim();
+        blobHash = abbreviateBlobHash(fullHash);
+    }
+    catch (error) {
+        verbose(`git hash-object failed for ${filePath}; falling back to zero blob hash: ${toError(error).message}`);
+    }
+    return buildNewFileDiffBody(filePath, content, blobHash);
+}
 /**
  * Generates a patch for a file.
  * If the file is tracked in HEAD, it generates a standard contextual diff.
@@ -185,10 +213,93 @@ export async function getAllDiff(repoDir) {
     const combined = allDiffs.join('');
     return combined.endsWith('\n') ? combined : combined + '\n';
 }
+/**
+ * Splits a combined `git diff` body into one string per file section,
+ * preserving exact bytes. A section runs from a column-0 `diff --git ` line up
+ * to (but not including) the next such line. Boundary detection is anchored to
+ * column 0 because every diff *body* line is prefixed by a space, `+`, `-`,
+ * `\`, or `@`, so a context or added line that merely contains the text
+ * `diff --git` can never be mistaken for a header. Paths are deliberately NOT
+ * parsed out of the header here — see {@link buildTrackedSections}.
+ * @param combined - Combined `git diff` stdout
+ * @returns File sections in git's emission order
+ */
+function splitDiffSections(combined) {
+    const marker = 'diff --git ';
+    const sections = [];
+    let start = -1;
+    for (let i = 0; i < combined.length; i++) {
+        if ((i === 0 || combined[i - 1] === '\n') && combined.startsWith(marker, i)) {
+            if (start !== -1)
+                sections.push(combined.slice(start, i));
+            start = i;
+        }
+    }
+    if (start !== -1)
+        sections.push(combined.slice(start, combined.length));
+    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.
+ *
+ * `--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
+ * section (`a/<old> b/<new>`) that a single-path `git diff HEAD -- <file>` can
+ * never produce; `--no-renames` re-splits it into the same delete + add bytes
+ * the per-file loop emitted.
+ *
+ * Sections are attributed to paths by POSITION against a companion
+ * `git diff --no-renames HEAD -z --name-only` (raw, unquoted, NUL-delimited
+ * paths, emitted in the same order as the sections) — never by parsing the
+ * `diff --git` header, which is ambiguous or unparseable under `core.quotePath`
+ * (non-ASCII paths are C-quoted), paths containing spaces, or
+ * `diff.noprefix`/`diff.mnemonicPrefix`. If the section and name counts ever
+ * disagree (an unmodeled config), that chunk falls back to per-file
+ * {@link getFileDiff} so no file's diff is ever silently dropped.
+ * @param repoDir - Repository directory
+ * @param trackedFiles - Repo-relative files known to exist in HEAD
+ * @returns Map from path to its exact diff section (changed files only)
+ */
+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 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);
+        if (sections.length === names.length) {
+            for (let i = 0; i < names.length; i++) {
+                // Exact-path keys (raw git bytes, same encoding as the inputs) — never
+                // a substring/startsWith match, so `foo.txt` cannot capture
+                // `foo.txt.bak`'s section.
+                sectionsByPath.set(names[i], sections[i]);
+            }
+            continue;
+        }
+        // Counts disagree — recover the exact pre-batch per-file bytes for this
+        // chunk rather than risk dropping or mis-keying a section.
+        for (const file of chunk) {
+            const diff = await getFileDiff(repoDir, file);
+            if (diff.trim())
+                sectionsByPath.set(file, diff);
+        }
+    }
+    return sectionsByPath;
+}
 /**
  * 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.
+ *
+ * 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
@@ -215,15 +326,24 @@ export async function getDiffForFilesAgainstHead(repoDir, files) {
         expandedFiles.push(file);
     }
     const uniqueFiles = [...new Set(expandedFiles)].sort();
-    const diffs = [];
+    if (uniqueFiles.length === 0)
+        return '';
+    // Batch 1: classify tracked-vs-new for the whole set in one `ls-tree` pass,
+    // replacing one `fileExistsInHead` spawn per file.
+    const tracked = await listTrackedInHead(repoDir, uniqueFiles);
+    // Batch 2: one diff over every tracked file, split back to exact per-file
+    // sections keyed by path.
+    const trackedSections = await buildTrackedSections(repoDir, uniqueFiles.filter((file) => tracked.has(file)));
+    // Classify the non-tracked files. Directory and binary entries keep their
+    // per-file handling (rare, and binary patches mutate the index so they must
+    // stay serial); plain new text files are collected for a single batched
+    // `git hash-object`. Results land in `sectionByFile`, keyed by path, to be
+    // emitted in sorted order below.
+    const sectionByFile = new Map();
+    const newTextFiles = [];
     for (const file of uniqueFiles) {
-        if (await fileExistsInHead(repoDir, file)) {
-            const diff = await getFileDiff(repoDir, file);
-            if (diff.trim()) {
-                diffs.push(diff);
-            }
+        if (tracked.has(file))
             continue;
-        }
         const fullPath = join(repoDir, file);
         if (!(await pathExists(fullPath))) {
             continue;
@@ -244,17 +364,42 @@ export async function getDiffForFilesAgainstHead(repoDir, files) {
                 throw new GitError(`'${file}' is a directory with no untracked content (submodule or gitignored?) — cannot diff as a file`, `ls-files --others -- ${file}`);
             }
             const innerDiff = await getDiffForFilesAgainstHead(repoDir, innerFiles);
-            if (innerDiff.trim()) {
-                diffs.push(innerDiff);
-            }
+            if (innerDiff.trim())
+                sectionByFile.set(file, innerDiff);
             continue;
         }
-        const diff = (await isBinaryFile(repoDir, file))
-            ? await generateBinaryFilePatch(repoDir, file)
-            : await generateNewFileDiff(repoDir, file);
-        if (diff.trim()) {
-            diffs.push(diff);
+        if (await isBinaryFile(repoDir, file)) {
+            const diff = await generateBinaryFilePatch(repoDir, file);
+            if (diff.trim())
+                sectionByFile.set(file, diff);
+            continue;
+        }
+        newTextFiles.push(file);
+    }
+    // Batch 3: blob hashes for every new text file in one `git hash-object`.
+    // A miss (rare: a path became unreadable after the stat above) falls back to
+    // the zero hash with the same verbose log the per-file path emitted.
+    const blobHashes = await hashObjectBatch(repoDir, newTextFiles.map((file) => join(repoDir, file)));
+    for (const file of newTextFiles) {
+        const fullPath = join(repoDir, file);
+        const fullHash = blobHashes.get(fullPath);
+        if (fullHash === undefined) {
+            verbose(`git hash-object failed for ${file}; falling back to zero blob hash`);
         }
+        const body = buildNewFileDiffBody(file, await readText(fullPath), abbreviateBlobHash(fullHash));
+        if (body.trim())
+            sectionByFile.set(file, body);
+    }
+    // Reassemble in the sorted `uniqueFiles` order — NOT git's section order,
+    // which uses git's own collation and diverges from JS `.sort()` for
+    // non-ASCII paths. Driving emission off `uniqueFiles` (as the previous
+    // per-file loop did) keeps the combined output byte-identical. Do not change
+    // this to push sections in git's emission order.
+    const diffs = [];
+    for (const file of uniqueFiles) {
+        const section = trackedSections.get(file) ?? sectionByFile.get(file);
+        if (section && section.trim())
+            diffs.push(section);
     }
     if (diffs.length === 0) {
         return '';
@@ -275,6 +420,22 @@ export async function getStagedDiffForFiles(repoDir, files) {
     await ensureGit();
     return git(['diff', '--cached', 'HEAD', '--', ...files], repoDir);
 }
+/**
+ * Serializes the index-mutating untracked-binary path. The bounded per-patch
+ * lint pool can call {@link getDiffForFilesAgainstHead} (and thus this) for
+ * several patches at once; two concurrent `git add --intent-to-add` / `git
+ * reset` sequences would collide on `.git/index.lock` (a hard failure) or
+ * interleave one file's stage with another's unstage. This process-level
+ * promise chain runs the staging sequences one at a time. Read-only callers
+ * (`git diff --binary HEAD`) do not need it. Binary patches are rare, so the
+ * serialization cost is negligible.
+ */
+let binaryStagingLock = Promise.resolve();
+function runWithBinaryStagingLock(task) {
+    const result = binaryStagingLock.then(task, task);
+    binaryStagingLock = result.then(() => undefined, () => undefined);
+    return result;
+}
 /**
  * Generates a GIT binary patch for a binary file.
  * For tracked files, uses `git diff --binary HEAD`.
@@ -285,7 +446,7 @@ export async function getStagedDiffForFiles(repoDir, files) {
  */
 export async function generateBinaryFilePatch(repoDir, filePath) {
     await ensureGit();
-    // Try tracked file diff first
+    // Try tracked file diff first (read-only — no index lock needed)
     const result = await execGitWithAllowedExitCodes(repoDir, [
         'diff',
         '--binary',
@@ -295,20 +456,24 @@ export async function generateBinaryFilePatch(repoDir, filePath) {
     ]);
     if (result.stdout.trim())
         return result.stdout;
-    // For untracked files, stage temporarily to produce a binary diff
-    try {
-        await execGitWithAllowedExitCodes(repoDir, ['add', '--intent-to-add', '--', filePath]);
-        const diffResult = await execGitWithAllowedExitCodes(repoDir, [
-            'diff',
-            '--binary',
-            '--',
-            filePath,
-        ]);
-        return diffResult.stdout;
-    }
-    finally {
-        // Always unstage, even if diff fails
-        await execGitWithAllowedExitCodes(repoDir, ['reset', 'HEAD', '--', filePath]);
-    }
+    // 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).
+    return runWithBinaryStagingLock(async () => {
+        try {
+            await execGitWithAllowedExitCodes(repoDir, ['add', '--intent-to-add', '--', filePath]);
+            const diffResult = await execGitWithAllowedExitCodes(repoDir, [
+                'diff',
+                '--binary',
+                '--',
+                filePath,
+            ]);
+            return diffResult.stdout;
+        }
+        finally {
+            // Always unstage, even if diff fails
+            await execGitWithAllowedExitCodes(repoDir, ['reset', 'HEAD', '--', filePath]);
+        }
+    });
 }
 //# sourceMappingURL=git-diff.js.map

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

@@ -30,6 +30,45 @@ export declare function unstageFiles(repoDir: string, files: string[]): Promise<
  * @returns true if file exists in HEAD
  */
 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.
+ *
+ * `-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
+ */
+export declare function listTrackedInHead(repoDir: string, files: string[]): Promise<Set<string>>;
+/**
+ * Batched equivalent of the per-file `git hash-object` in
+ * {@link import('./git-diff.js').generateNewFileDiff}: computes the git blob
+ * hash for every path in one spawn per ARG_MAX chunk and returns a
+ * `Map<fullPath, fullHash>`.
+ *
+ * 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.
+ * @param repoDir - Repository directory
+ * @param fullPaths - Absolute file paths to hash
+ * @returns Map from each input path to its full blob hash (misses omitted)
+ */
+export declare function hashObjectBatch(repoDir: string, fullPaths: string[]): Promise<Map<string, string>>;
 /**
  * Gets the content of a file at a specific git ref (HEAD by default).
  * @param repoDir - Repository directory

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

@@ -4,7 +4,7 @@ import { join } from 'node:path';
 import { GitError } from '../errors/git.js';
 import { removeFile } from '../utils/fs.js';
 import { exec } from '../utils/process.js';
-import { ensureGit, git } from './git-base.js';
+import { chunkPathspecs, ensureGit, git } from './git-base.js';
 /**
  * Restores a tracked path from HEAD, including staged changes.
  * @param repoDir - Repository directory
@@ -87,6 +87,87 @@ 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, and the old per-file fan-out spent
+ * ~99s in serial `git ls-tree`/`git diff` spawns.
+ *
+ * `-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
+ */
+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
+            // result is always a subset of the requested files, never a superset.
+            if (name.length > 0 && wanted.has(name))
+                tracked.add(name);
+        }
+    }
+    return tracked;
+}
+/**
+ * Batched equivalent of the per-file `git hash-object` in
+ * {@link import('./git-diff.js').generateNewFileDiff}: computes the git blob
+ * hash for every path in one spawn per ARG_MAX chunk and returns a
+ * `Map<fullPath, fullHash>`.
+ *
+ * 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.
+ * @param repoDir - Repository directory
+ * @param fullPaths - Absolute file paths to hash
+ * @returns Map from each input path to its full blob hash (misses omitted)
+ */
+export async function hashObjectBatch(repoDir, fullPaths) {
+    const hashes = new Map();
+    if (fullPaths.length === 0)
+        return hashes;
+    await ensureGit();
+    for (const chunk of chunkPathspecs(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]);
+            }
+            continue;
+        }
+        // Batch aborted partway (a path became unreadable between the caller's stat
+        // and here, or otherwise failed). Recover per file so one bad path only
+        // loses its own hash, exactly as the pre-batch per-file code behaved.
+        for (const path of chunk) {
+            const single = await exec('git', ['hash-object', '--', path], { cwd: repoDir });
+            const hash = single.stdout.trim();
+            if (single.exitCode === 0 && hash.length > 0)
+                hashes.set(path, hash);
+        }
+    }
+    return hashes;
+}
 /**
  * Gets the content of a file at a specific git ref (HEAD by default).
  * @param repoDir - Repository directory

package/dist/src/core/mach-resource-shim.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Resource-monitor degrade shim for `mach build`.
+ *
+ * mozbuild's build resource monitor calls `psutil.virtual_memory()` at
+ * startup (`start_resource_recording`). On some hosts (psutil vs Darwin 27)
+ * that raises `RuntimeError: host_statistics64(HOST_VM_INFO64) syscall
+ * failed`, which aborts `mach build` / `mach build faster` before any work
+ * happens — so a raw `./mach build faster` dies while the build never
+ * reaches the compiler. The suite-specific test commands sidestep the
+ * monitor entirely, but the build commands have no such escape.
+ *
+ * FireForge writes a tiny `sitecustomize.py` and points the mach
+ * subprocess's `PYTHONPATH` at it. Python imports `sitecustomize` at
+ * interpreter startup (before mach runs), so the shim wraps
+ * `psutil.virtual_memory` / `swap_memory` to downgrade the host syscall
+ * failure into a non-fatal `UserWarning` and return a zeroed reading. The
+ * build then proceeds regardless of which mach entry point spawned it. When
+ * psutil works normally the wrapper is a transparent pass-through.
+ */
+/** Ensures the shim exists and returns the mach `env` overlay that enables it. */
+export declare function resolveMachBuildEnv(): Promise<Record<string, string>>;

package/dist/src/core/mach-resource-shim.js

@@ -0,0 +1,92 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Resource-monitor degrade shim for `mach build`.
+ *
+ * mozbuild's build resource monitor calls `psutil.virtual_memory()` at
+ * startup (`start_resource_recording`). On some hosts (psutil vs Darwin 27)
+ * that raises `RuntimeError: host_statistics64(HOST_VM_INFO64) syscall
+ * failed`, which aborts `mach build` / `mach build faster` before any work
+ * happens — so a raw `./mach build faster` dies while the build never
+ * reaches the compiler. The suite-specific test commands sidestep the
+ * monitor entirely, but the build commands have no such escape.
+ *
+ * FireForge writes a tiny `sitecustomize.py` and points the mach
+ * subprocess's `PYTHONPATH` at it. Python imports `sitecustomize` at
+ * interpreter startup (before mach runs), so the shim wraps
+ * `psutil.virtual_memory` / `swap_memory` to downgrade the host syscall
+ * failure into a non-fatal `UserWarning` and return a zeroed reading. The
+ * build then proceeds regardless of which mach entry point spawned it. When
+ * psutil works normally the wrapper is a transparent pass-through.
+ */
+import { tmpdir } from 'node:os';
+import { delimiter, join } from 'node:path';
+import { ensureDir, writeText } from '../utils/fs.js';
+/** Directory name (under the OS temp dir) holding the generated shim. */
+const RESOURCE_SHIM_DIRNAME = 'fireforge-mach-resource-shim';
+/**
+ * `sitecustomize.py` body. Defensive: a missing/broken psutil leaves mach
+ * untouched, and the wrapper only intercepts the failure path.
+ */
+const SITECUSTOMIZE_SOURCE = `# Generated by FireForge — do not edit.
+# Degrades a broken host resource monitor (psutil vs Darwin) from a fatal
+# RuntimeError in start_resource_recording into a non-fatal warning, so
+# \`mach build\` does not abort before the build runs. Loaded via PYTHONPATH
+# so it patches psutil before mach's resource monitor starts.
+import warnings
+
+try:
+    import psutil
+except Exception:
+    psutil = None
+
+if psutil is not None:
+    class _DegradedReading(object):
+        total = available = used = free = active = inactive = wired = 0
+        percent = 0.0
+
+        def __getattr__(self, _name):
+            return 0
+
+    def _guard(orig):
+        def wrapper(*args, **kwargs):
+            try:
+                return orig(*args, **kwargs)
+            except Exception as exc:  # noqa: BLE001
+                warnings.warn(
+                    "FireForge: host resource monitor degraded (%s); build continues." % exc
+                )
+                return _DegradedReading()
+
+        return wrapper
+
+    for _name in ("virtual_memory", "swap_memory"):
+        _orig = getattr(psutil, _name, None)
+        if _orig is not None:
+            setattr(psutil, _name, _guard(_orig))
+`;
+/**
+ * Writes the `sitecustomize.py` degrade shim into a stable FireForge-owned
+ * temp directory and returns that directory. Idempotent — overwriting the
+ * file each call keeps it in sync with this source if FireForge upgrades.
+ */
+async function ensureMachResourceShim() {
+    const dir = join(tmpdir(), RESOURCE_SHIM_DIRNAME);
+    await ensureDir(dir);
+    await writeText(join(dir, 'sitecustomize.py'), SITECUSTOMIZE_SOURCE);
+    return dir;
+}
+/**
+ * Builds the `env` overlay (merged over `process.env` by the exec layer)
+ * that prepends the shim directory to `PYTHONPATH`, so the mach subprocess
+ * imports the degrade `sitecustomize` without clobbering an existing
+ * `PYTHONPATH`.
+ */
+function machResourceShimEnv(shimDir, baseEnv = process.env) {
+    const existing = baseEnv['PYTHONPATH'];
+    return { PYTHONPATH: existing ? `${shimDir}${delimiter}${existing}` : shimDir };
+}
+/** Ensures the shim exists and returns the mach `env` overlay that enables it. */
+export async function resolveMachBuildEnv() {
+    return machResourceShimEnv(await ensureMachResourceShim());
+}
+//# sourceMappingURL=mach-resource-shim.js.map

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

@@ -199,3 +199,20 @@ export declare function test(engineDir: string, testPaths?: string[], args?: str
  *   `fireforge test --perf-samples` to publish the artifact-path contract.
  */
 export declare function testWithOutput(engineDir: string, testPaths?: string[], args?: string[], env?: Record<string, string>): Promise<MachCommandResult>;
+/**
+ * Runs `mach xpcshell-test` (the suite-specific xpcshell command) while
+ * capturing output. Unlike the generic `mach test`, the suite-specific
+ * commands degrade a broken mozlog resource monitor to a warning instead of
+ * crashing at startup, so `fireforge test` dispatches single-suite runs here
+ * to stay resilient to the host psutil failure (field report E1).
+ *
+ * Signature mirrors {@link testWithOutput} so the two are interchangeable in
+ * the dispatch path.
+ */
+export declare function xpcshellTestWithOutput(engineDir: string, testPaths?: string[], args?: string[], env?: Record<string, string>): Promise<MachCommandResult>;
+/**
+ * Runs `mach mochitest` (covers browser-chrome / mochitest flavors) while
+ * capturing output. The suite-specific counterpart to {@link testWithOutput}
+ * for non-xpcshell single-suite runs — see {@link xpcshellTestWithOutput}.
+ */
+export declare function mochitestWithOutput(engineDir: string, testPaths?: string[], args?: string[], env?: Record<string, string>): Promise<MachCommandResult>;