@hominis/fireforge 0.45.0 → 0.46.1

package/dist/src/core/mach-known-noise-filter.js

@@ -5,40 +5,41 @@
  *
  * Headless test runs against recent engines can end with an
  * `AttributeError: 'SystemResourceMonitor' object has no attribute
- * 'stop_time'` traceback at harness teardown — upstream noise that sits
- * exactly where a reader looks for the failure summary. Real failure lines
- * already beat this traceback in CLASSIFICATION; this filter closes the
- * PRESENTATION gap by collapsing the echoed traceback to one labeled line.
+ * 'stop_time'` traceback at harness teardown. That is upstream noise, and
+ * it sits exactly where a reader looks for the failure summary. Real failure
+ * lines already beat this traceback in classification. This filter closes
+ * the presentation gap by collapsing the echoed traceback to one labeled
+ * line.
  *
- * Scope is deliberately narrow:
- *   - Only the terminal ECHO is filtered. The captured stdout/stderr strings
- *     stay raw — the classifier (`test-harness-crash.ts`) depends on the raw
- *     traceback for its green-summary override and secondary-noise
+ * Scope is narrow on purpose:
+ *   - Only the terminal echo is filtered. The captured stdout/stderr strings
+ *     stay raw, because the classifier (`test-harness-crash.ts`) depends on
+ *     the raw traceback for its green-summary override and secondary-noise
  *     detection.
  *   - Only the exact documented incident is collapsed, and every condition
  *     must hold: an `AttributeError` on `SystemResourceMonitor` naming one
- *     of the two known attributes (`stop_time`, `poll_interval`), AND a
- *     `mozsystemmonitor/resourcemonitor.py` stack frame, AND a
+ *     of the two known attributes (`stop_time`, `poll_interval`), and a
+ *     `mozsystemmonitor/resourcemonitor.py` stack frame, and a
  *     previously-seen SUITE_END shutdown marker (shared across the run's
- *     stdout/stderr filter instances — the marker usually lands on stdout
- *     while the traceback lands on stderr). A novel attribute, a novel
+ *     stdout/stderr filter instances, where the marker usually lands on
+ *     stdout while the traceback lands on stderr). A novel attribute, a novel
  *     exception type in resourcemonitor.py, or a pre-shutdown occurrence is
  *     echoed verbatim, always.
- *   - The hold buffer is bounded; on overflow the block is flushed verbatim
+ *   - The hold buffer is bounded. On overflow the block is flushed verbatim
  *     and the filter returns to pass-through, so output is never lost.
  *
- * The COLLAPSE is test-only, deliberately, and not an oversight — the two
- * reasons are worth stating because from outside it reads like one:
+ * The collapse is test-only on purpose, not an oversight. Two reasons,
+ * since from outside they read like one:
  *   1. Recognition requires a previously-seen SUITE_END shutdown marker, and
  *      `mach build` never prints one. Wiring the option into the build
  *      dispatch would therefore be a silent no-op.
  *   2. Relaxing that gate for builds would be wrong on its own terms. The
  *      marker is what separates teardown noise from a traceback raised while
- *      work was still happening; a build has no equivalent boundary, so
+ *      work was still happening. A build has no equivalent boundary, so
  *      FireForge cannot tell the known-cosmetic case from a real build-time
  *      failure and must not withhold the block.
- * The build path instead RECOGNIZES the signature and says so beside the
- * verbatim traceback — see {@link KNOWN_TEARDOWN_NOISE_BUILD_NOTE} and
+ * The build path instead recognizes the signature and says so beside the
+ * verbatim traceback. See {@link KNOWN_TEARDOWN_NOISE_BUILD_NOTE} and
  * `runProtectedMachBuild`.
  */
 const TRACEBACK_HEADER_PATTERN = /^Traceback \(most recent call last\)/;
@@ -47,52 +48,52 @@ const CHAINED_EXCEPTION_CONNECTOR_PATTERN = /^(?:During handling of the above ex
  * Closed allowlist of the documented teardown family's attributes:
  * `stop_time` and `poll_interval` (the same mozsystemmonitor init failure
  * `test-harness-crash.ts` already classifies as recognized noise). Any other
- * missing attribute is a NEW upstream defect and must print verbatim.
+ * missing attribute is a new upstream defect and must print verbatim.
  */
 const KNOWN_TEARDOWN_ATTRIBUTE_ERROR_PATTERN = /AttributeError: 'SystemResourceMonitor' object has no attribute '(?:stop_time|poll_interval)'/;
 const RESOURCEMONITOR_FRAME_PATTERN = /mozsystemmonitor[/\\]resourcemonitor\.py/;
 /**
  * Shutdown marker: the harness's SUITE_END line. Matches the shape
  * `test-harness-crash.ts` keys its summary parsing on (module-private
- * there; duplicated here with this cross-reference rather than exported).
+ * there, and duplicated here with this cross-reference rather than
+ * exported).
  */
 const SHUTDOWN_MARKER_PATTERN = /\bSUITE_END\b/;
-/** Whole-block recognition — every signal must hold (see module doc). */
-function isRecognizedTeardownNoise(block) {
-    return (KNOWN_TEARDOWN_ATTRIBUTE_ERROR_PATTERN.test(block) && RESOURCEMONITOR_FRAME_PATTERN.test(block));
-}
 /**
- * True when CAPTURED output carries the documented mozsystemmonitor
- * teardown traceback.
+ * Whole-block recognition. Every signal must hold (see module doc). True
+ * when captured output carries the documented mozsystemmonitor teardown
+ * traceback.
  *
- * The echo filter above only affects what a human sees. The CLASSIFIER
+ * The echo filter below only affects what a human sees. The classifier
  * reads the raw capture, and it needs the same recognition to tell "the
  * suite finished clean and then upstream fell over at shutdown" from "the
- * suite did not finish". Deliberately the same two-signal test the echo
- * filter applies — a novel attribute or a traceback from anywhere but
- * `resourcemonitor.py` is NOT this incident and must keep failing the run.
+ * suite did not finish". This is the same two-signal test the echo filter
+ * applies: a novel attribute or a traceback from anywhere but
+ * `resourcemonitor.py` is not this incident and must keep failing the run.
  *
  * The shutdown-marker precondition the echo filter adds is intentionally
- * omitted: the whole point at the classification layer is the case where
- * the teardown crash prevented the shutdown marker from printing.
+ * omitted: at the classification layer the case that matters is exactly
+ * the one where the teardown crash prevented the shutdown marker from
+ * printing.
  *
- * Pure; exported for the classifier and for direct unit testing.
+ * Pure. Exported for the classifier and for direct unit testing.
  *
  * @param output - Raw captured stdout/stderr
  * @returns True when the recognized teardown traceback is present
  */
 export function hasKnownTeardownNoise(output) {
-    return isRecognizedTeardownNoise(output);
+    return (KNOWN_TEARDOWN_ATTRIBUTE_ERROR_PATTERN.test(output) &&
+        RESOURCEMONITOR_FRAME_PATTERN.test(output));
 }
 /**
- * True when a SINGLE line is the documented teardown family's
+ * True when a single line is the documented teardown family's
  * `AttributeError`.
  *
- * The line-level half of {@link hasKnownTeardownNoise}: the traceback FRAME
+ * The line-level half of {@link hasKnownTeardownNoise}: the traceback frame
  * lives on a neighbouring line, so a per-line test cannot apply the
  * two-signal rule by itself. Callers pair this with
- * `hasKnownTeardownNoise(wholeOutput)` to recover the full recognition —
- * "this capture carries the incident, and THIS line is its header" — which
+ * `hasKnownTeardownNoise(wholeOutput)` to recover the full recognition
+ * ("this capture carries the incident, and this line is its header"), which
  * keeps the closed attribute allowlist (`stop_time`/`poll_interval`) doing
  * the same work it does everywhere else. A novel attribute is not this
  * incident and must stay a candidate failure.
@@ -103,13 +104,13 @@ export function hasKnownTeardownNoise(output) {
 export function isKnownTeardownNoiseLine(line) {
     return KNOWN_TEARDOWN_ATTRIBUTE_ERROR_PATTERN.test(line);
 }
-/** Fresh per-run context — hand the same instance to both stream filters. */
+/** Fresh per-run context. Hand the same instance to both stream filters. */
 export function createTeardownNoiseContext() {
     return { shutdownSeen: false };
 }
 /**
- * Build-phase note for the SAME recognized signature. The build path does
- * not COLLAPSE the traceback (see the module doc's "test-only" note) — it
+ * Build-phase note for the same recognized signature. The build path does
+ * not collapse the traceback (see the module doc's "test-only" note). It
  * prints verbatim and this line is added beside it, so one signature reads
  * the same in both phases without a build losing output it may need.
  */
@@ -125,7 +126,7 @@ const HOLD_BYTE_LIMIT = 16 * 1024;
 /**
  * Creates a stateful filter for one output stream. Complete lines outside a
  * traceback pass straight through (only the trailing partial line is held
- * back); a `Traceback (most recent call last)` header switches to hold mode
+ * back). A `Traceback (most recent call last)` header switches to hold mode
  * until the block ends, then either the one-line annotation (recognized
  * signature after a seen shutdown marker) or the verbatim block (anything
  * else) is emitted. Pass the run's shared {@link TeardownNoiseContext} so
@@ -134,18 +135,18 @@ const HOLD_BYTE_LIMIT = 16 * 1024;
 export function createKnownTeardownNoiseFilter(context = createTeardownNoiseContext()) {
     /** Partial (no trailing newline yet) input line. */
     let partial = '';
-    /** Held traceback lines (each WITH its newline) while in hold mode. */
+    /** Held traceback lines (each with its newline) while in hold mode. */
     let held = [];
     let heldBytes = 0;
     /**
      * State machine:
-     *   'pass'    — outside any traceback; lines echo through.
-     *   'inside'  — between a Traceback header and its closing exception line.
-     *   'closed'  — saw the closing `SomeError: …` line; still holding in
-     *               case a chained-exception connector continues the block
-     *               (the real fixture chains two tracebacks — the whole
-     *               chain must be evaluated as ONE block or the second half
-     *               would print raw after the annotation).
+     *   'pass':   outside any traceback, so lines echo through.
+     *   'inside': between a Traceback header and its closing exception line.
+     *   'closed': saw the closing `SomeError: …` line, still holding in
+     *             case a chained-exception connector continues the block
+     *             (the real fixture chains two tracebacks, so the whole
+     *             chain must be evaluated as one block or the second half
+     *             would print raw after the annotation).
      */
     let state = 'pass';
     const resetHold = () => {
@@ -159,7 +160,7 @@ export function createKnownTeardownNoiseFilter(context = createTeardownNoiseCont
         const block = resetHold();
         if (block.length === 0)
             return '';
-        return context.shutdownSeen && isRecognizedTeardownNoise(block)
+        return context.shutdownSeen && hasKnownTeardownNoise(block)
             ? KNOWN_TEARDOWN_NOISE_ANNOTATION
             : block;
     };
@@ -168,7 +169,7 @@ export function createKnownTeardownNoiseFilter(context = createTeardownNoiseCont
         heldBytes += line.length;
         if (held.length > HOLD_LINE_LIMIT || heldBytes > HOLD_BYTE_LIMIT) {
             // Pathological block: flush verbatim rather than risk withholding
-            // output; do not attempt recognition on oversized blocks.
+            // output. Do not attempt recognition on oversized blocks.
             return { out: resetHold(), overflowed: true };
         }
         return { out: '', overflowed: false };
@@ -189,7 +190,7 @@ export function createKnownTeardownNoiseFilter(context = createTeardownNoiseCont
                 /^[ \t]/.test(content) ||
                 TRACEBACK_HEADER_PATTERN.test(content);
             const { out, overflowed } = hold(line);
-            // The first unindented line is the closing `SomeError: …` line; keep
+            // The first unindented line is the closing `SomeError: …` line. Keep
             // holding in case a chained connector extends the block.
             if (!overflowed && !isContinuation) {
                 state = 'closed';
@@ -209,8 +210,8 @@ export function createKnownTeardownNoiseFilter(context = createTeardownNoiseCont
         }
         return releaseHeld() + processLineInPass(line);
     };
-    // Re-dispatch a line through pass-mode handling after a block release —
-    // the line that ended the block may itself start a new traceback.
+    // Re-dispatch a line through pass-mode handling after a block release.
+    // The line that ended the block may itself start a new traceback.
     const processLineInPass = (line) => {
         const content = line.replace(/\r?\n$/, '');
         if (TRACEBACK_HEADER_PATTERN.test(content)) {
@@ -240,7 +241,7 @@ export function createKnownTeardownNoiseFilter(context = createTeardownNoiseCont
             let out = '';
             if (state !== 'pass') {
                 // A stream that closes mid-block: fold the trailing partial line in
-                // and evaluate — the final exception line is often the last thing
+                // and evaluate. The final exception line is often the last thing
                 // printed, without a trailing newline.
                 if (partial.length > 0) {
                     held.push(partial);

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

@@ -10,7 +10,7 @@ export interface MozconfigVariables {
 }
 /**
  * Extracts the `--with-branding=<path>` value from a rendered mozconfig
- * body. Returns `undefined` when no directive is present — callers treat
+ * body. Returns `undefined` when no directive is present, and callers treat
  * that as "mozconfig is missing branding", which is itself an actionable
  * configuration error.
  *
@@ -18,13 +18,13 @@ export interface MozconfigVariables {
  */
 export declare function extractWithBrandingPath(mozconfigContent: string): string | undefined;
 /**
- * Extracts the objdir NAME a mozconfig declares — the single trailing path
+ * Extracts the objdir name a mozconfig declares: the single trailing path
  * segment, which is what the `obj-*` scan enumerates.
  *
  * `@TOPSRCDIR@` and a leading `./` are both spellings of "beside the
- * source", which is the only arrangement FireForge's scan can see anyway;
- * an absolute path outside the engine directory reduces to its basename and
- * simply will not match a candidate, which is the correct outcome — a
+ * source", which is the only arrangement FireForge's scan can see anyway.
+ * An absolute path outside the engine directory reduces to its basename and
+ * simply will not match a candidate, which is the correct outcome. A
  * declaration that names something the scan cannot see must not select
  * anything.
  *
@@ -33,7 +33,7 @@ export declare function extractWithBrandingPath(mozconfigContent: string): strin
 export declare function extractMozObjdirName(mozconfigContent: string): string | undefined;
 /**
  * Preflights the just-written mozconfig against the branding tree FireForge
- * set up. A drift between the two is silent-corruption territory — the
+ * set up. A drift between the two is silent-corruption territory: the
  * build runs, `mach configure` reads the stale directory name out of
  * mozconfig, and then the recursive make backend errors out with a "path
  * does not exist" message that names the branding dir the mozconfig

package/dist/src/core/mach-mozconfig.js

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import { MozconfigError } from '../errors/build.js';
 import { pathExists, readText, writeTextIfChanged } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
+import { normalizePathSlashes } from '../utils/paths.js';
 import { getPlatform } from '../utils/platform.js';
 import { BrandingMozconfigMismatchError, splitAppId } from './branding.js';
 /**
@@ -20,17 +21,17 @@ function replaceVariables(content, variables) {
 }
 /**
  * Matches an `--with-branding=<path>` directive anywhere in a rendered
- * mozconfig. The directive form is the one mach reads; an optional
+ * mozconfig. The directive form is the one mach reads, and an optional
  * `ac_add_options` prefix is the on-disk convention. `m` flag anchors the
  * search per-line so a multi-line mozconfig with older directives earlier
- * in the file doesn't confuse the extractor. We pick the LAST match
+ * in the file doesn't confuse the extractor. We pick the last match
  * because mach itself takes the last-write-wins semantics of shell
  * configuration for overlapping `ac_add_options` calls.
  */
 const WITH_BRANDING_PATTERN = /^\s*(?:ac_add_options\s+)?--with-branding\s*=\s*(\S+)/gm;
 /**
  * Extracts the `--with-branding=<path>` value from a rendered mozconfig
- * body. Returns `undefined` when no directive is present — callers treat
+ * body. Returns `undefined` when no directive is present, and callers treat
  * that as "mozconfig is missing branding", which is itself an actionable
  * configuration error.
  *
@@ -50,13 +51,13 @@ export function extractWithBrandingPath(mozconfigContent) {
  */
 const MOZ_OBJDIR_PATTERN = /^\s*(?:mk_add_options\s+|export\s+)?MOZ_OBJDIR\s*=\s*["']?([^"'\s#]+)/gm;
 /**
- * Extracts the objdir NAME a mozconfig declares — the single trailing path
+ * Extracts the objdir name a mozconfig declares: the single trailing path
  * segment, which is what the `obj-*` scan enumerates.
  *
  * `@TOPSRCDIR@` and a leading `./` are both spellings of "beside the
- * source", which is the only arrangement FireForge's scan can see anyway;
- * an absolute path outside the engine directory reduces to its basename and
- * simply will not match a candidate, which is the correct outcome — a
+ * source", which is the only arrangement FireForge's scan can see anyway.
+ * An absolute path outside the engine directory reduces to its basename and
+ * simply will not match a candidate, which is the correct outcome. A
  * declaration that names something the scan cannot see must not select
  * anything.
  *
@@ -73,7 +74,7 @@ export function extractMozObjdirName(mozconfigContent) {
 }
 /**
  * Preflights the just-written mozconfig against the branding tree FireForge
- * set up. A drift between the two is silent-corruption territory — the
+ * set up. A drift between the two is silent-corruption territory: the
  * build runs, `mach configure` reads the stale directory name out of
  * mozconfig, and then the recursive make backend errors out with a "path
  * does not exist" message that names the branding dir the mozconfig
@@ -93,10 +94,10 @@ export async function assertBrandingMozconfigAgreement(engineDir, mozconfigPath,
     if (!found) {
         throw new BrandingMozconfigMismatchError(expected, '(no --with-branding directive)', 'mozconfig-missing-branding');
     }
-    // Normalise both sides to forward slashes before compare — Windows-edited
+    // Normalise both sides to forward slashes before compare. Windows-edited
     // configs can carry backslash path separators that the build would treat
     // as literal characters in a repo-relative path.
-    const normalizedFound = found.replace(/\\/g, '/');
+    const normalizedFound = normalizePathSlashes(found);
     if (normalizedFound !== expected) {
         throw new BrandingMozconfigMismatchError(expected, found, 'name-mismatch');
     }
@@ -126,9 +127,9 @@ export async function generateMozconfig(configsDir, engineDir, config) {
         binaryName: config.binaryName,
     };
     let content = '';
-    // Bundle identity: branding configure.sh carries only the LEAF of appId
-    // (see splitAppId in branding.ts — upstream composes the mac bundle id as
-    // <distribution-id>.<MOZ_MACBUNDLE_ID>); the prefix travels here so the
+    // Bundle identity: branding configure.sh carries only the leaf of appId
+    // (see splitAppId in branding.ts, and upstream composes the mac bundle id
+    // as <distribution-id>.<MOZ_MACBUNDLE_ID>). The prefix travels here so the
     // two halves can never drift apart.
     const { distributionId } = splitAppId(config.appId);
     content +=
@@ -145,11 +146,11 @@ export async function generateMozconfig(configsDir, engineDir, config) {
     }
     const platformContent = await readText(platformPath);
     content += `# Platform configuration (${platform})\n${replaceVariables(platformContent, variables)}`;
-    // Write-if-changed: `mozconfig` is a mach CONFIGURE INPUT, so
-    // its mtime — not its content — is what `config.status` compares against.
+    // Write-if-changed: `mozconfig` is a mach configure input, so its mtime,
+    // not its content, is what `config.status` compares against.
     // Rewriting a byte-identical file on every build-capable invocation made
     // mach re-run `configure` plus backend regeneration ("Backend config
-    // changed; N files touched") on EVERY run, each run re-arming the next.
+    // changed; N files touched") on every run, each run re-arming the next.
     // Only touch the file when the rendered content actually differs.
     const wrote = await writeTextIfChanged(outputPath, content);
     if (!wrote) {

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

@@ -1,5 +1,8 @@
 /**
  * Resets the resolved Python executable. Primarily useful for testing.
+ *
+ * @internal Exported only so tests can reach it. Not part of the public
+ * surface.
  */
 export declare function resetResolvedPython(): void;
 /**

package/dist/src/core/mach-python.js

@@ -6,7 +6,12 @@ import { pathExists, readText } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
 import { exec, executableExists } from '../utils/process.js';
 /** Cached Python resolution state */
-const pythonCache = {};
+/**
+ * The resolved interpreter and the requirement range it was resolved for.
+ * `undefined` means "not resolved yet". The two always move together, so
+ * one nullable record beats two independently-deletable fields.
+ */
+let pythonCache;
 const DEFAULT_MACH_PYTHON_REQUIREMENTS = {
     min: { major: 3, minor: 8 },
     max: { major: 3, minor: 12 },
@@ -73,10 +78,12 @@ function buildPythonCandidates(requirements) {
 }
 /**
  * Resets the resolved Python executable. Primarily useful for testing.
+ *
+ * @internal Exported only so tests can reach it. Not part of the public
+ * surface.
  */
 export function resetResolvedPython() {
-    delete pythonCache.python;
-    delete pythonCache.requirementsKey;
+    pythonCache = undefined;
 }
 /**
  * Dynamically resolves the python executable and ensures it is available.
@@ -86,7 +93,7 @@ export function resetResolvedPython() {
 export async function ensurePython(engineDir) {
     const requirements = await readMachPythonRequirements(engineDir);
     const requirementsKey = formatRequirementsKey(requirements);
-    if (pythonCache.python && pythonCache.requirementsKey === requirementsKey) {
+    if (pythonCache?.requirementsKey === requirementsKey) {
         return;
     }
     const candidates = buildPythonCandidates(requirements);
@@ -99,8 +106,7 @@ export async function ensurePython(engineDir) {
                 ]);
                 const version = parsePythonVersion(stdout);
                 if (version && isVersionWithinRequirements(version, requirements)) {
-                    pythonCache.python = candidate;
-                    pythonCache.requirementsKey = requirementsKey;
+                    pythonCache = { python: candidate, requirementsKey };
                     return;
                 }
             }
@@ -118,7 +124,7 @@ export async function ensurePython(engineDir) {
  */
 export async function getPython(engineDir) {
     await ensurePython(engineDir);
-    if (!pythonCache.python) {
+    if (pythonCache === undefined) {
         throw new PythonNotFoundError();
     }
     return pythonCache.python;

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

@@ -12,7 +12,7 @@
  *
  * The guard is installed as a `fireforge_mach_guard.pth` + module pair in
  * every discovered mach virtualenv site-packages directory. A PYTHONPATH
- * `sitecustomize.py` is NOT sufficient on its own: mach re-execs itself into
+ * `sitecustomize.py` is not sufficient on its own: mach re-execs itself into
  * its private virtualenv and drops PYTHONPATH, so that route never loads.
  * `.pth` files execute at interpreter startup from the venv's own
  * site-packages, which survives the re-exec. The PYTHONPATH copy is retained
@@ -21,12 +21,12 @@
  *
  * The guard covers the whole crash family:
  *  - wraps `psutil.virtual_memory` / `swap_memory` / `cpu_percent` /
- *    `cpu_times` / `disk_io_counters` module-wide, so every call site —
+ *    `cpu_times` / `disk_io_counters` module-wide, so every call site,
  *    including the direct `psutil.virtual_memory()` in
- *    `mozbuild.base._run_make` — degrades to a `UserWarning` and a zeroed
+ *    `mozbuild.base._run_make`, degrades to a `UserWarning` and a zeroed
  *    reading instead of aborting.
  *
- *    The fallback must be per-function ARITY-CORRECT and reconstructible:
+ *    The fallback must be per-function arity-correct and reconstructible:
  *    mozsystemmonitor captures reading types at `__init__`
  *    (`self._swap_type = type(psutil.swap_memory())`) and rebuilds each
  *    collector sample via `self._swap_type(*swap_mem)`. An svmem-shaped
@@ -36,28 +36,28 @@
  *    sentinel, and mach hangs forever in its atexit `waitpid`. Each wrapped
  *    function therefore degrades to a zeroed instance of psutil's own result
  *    namedtuple where resolvable, else a module-level guard-owned namedtuple
- *    with the exact field order and arity for THAT function (module-level so
+ *    with the exact field order and arity for that function (module-level so
  *    readings pickle by reference across the collector pipe).
  *    `_DegradedReading` remains only as a documented last resort and
  *    tolerates `type(reading)(*values)` reconstruction. Guard-owned fallback
  *    classes never depend on psutil internals resolving, which also makes
  *    them safe when two guard copies load (PYTHONPATH `sitecustomize` in the
- *    bootstrap phase plus the in-venv `.pth`), each with its own classes;
- *  - guards `SystemResourceMonitor` CONSTRUCTION via an import hook:
+ *    bootstrap phase plus the in-venv `.pth`), each with its own classes.
+ *  - guards `SystemResourceMonitor` construction via an import hook:
  *    `poll_interval` is pre-populated before the real `__init__` runs, a
  *    failing `__init__` marks the instance degraded instead of raising, and
- *    every monitor method no-ops on a degraded instance — so a
+ *    every monitor method no-ops on a degraded instance, so a
  *    partially-constructed monitor can never surface the
  *    `AttributeError: poll_interval` variant. Degraded aggregate methods
  *    return zeroed shapes (not `None`) where callers subscript the result
  *    (`aggregate_io` → zeroed io reading, so mozbuild's `log_resource_usage`
- *    does not die on `usage["io"].read_bytes` after a successful compile);
+ *    does not die on `usage["io"].read_bytes` after a successful compile).
  *  - suppresses the mozsystemmonitor collector child on degradation: once
  *    any psutil degradation is observed in the process, monitors are kept
  *    inert (`start` never spawns the collector), and a degraded transition
  *    or raising `stop` best-effort terminates a live collector child and
  *    drains the pipe, so a malformed sample stream cannot wedge mach's
- *    shutdown even if a future shape mismatch slips through;
+ *    shutdown even if a future shape mismatch slips through.
  *  - wraps `mozbuild.controller.building.BuildMonitor.log_resource_usage` to
  *    warn-and-continue on any exception, so end-of-build resource reporting
  *    can never fail a build whose artifacts are complete.
@@ -71,7 +71,7 @@
  * regression test (mach-resource-shim.python.test.ts), which asserts the
  * degraded readings' runtime behavior rather than string-matching the source.
  */
-export declare const GUARD_PYTHON_SOURCE = "# Generated by FireForge - do not edit.\n# Degrades the broken host resource monitor family (psutil vs Darwin) from\n# fatal startup errors into non-fatal warnings, so mach builds and tests\n# proceed. Installed into the mach virtualenv site-packages via a .pth file\n# (survives mach's venv re-exec, which drops PYTHONPATH).\nimport builtins\nimport collections\nimport sys\nimport warnings\n\n# Any psutil degradation observed in this process. Once set, monitors are\n# kept inert (start never spawns the collector child) \u2014 on a flapping host a\n# healthy-looking moment must not be trusted to start a sample stream that a\n# later degraded reading could malform.\n_fireforge_host_degraded = [False]\n\n\ndef _fireforge_degraded_notice(exc):\n    _fireforge_host_degraded[0] = True\n    warnings.warn(\n        \"FireForge: host resource monitor degraded (%s); continuing without resource monitoring.\" % exc\n    )\n\n\nclass _DegradedReading(object):\n    # Last-resort duck type of psutil's namedtuple results (svmem field\n    # order): mozsystemmonitor subscripts, iterates, and unpacks readings,\n    # so the degraded fallback must survive r[0], list(r), len(r), r._fields\n    # and r._asdict(), not just attribute access. The parent also reconstructs\n    # readings via type(reading)(*values), so the constructor must tolerate\n    # the full positional field list. Normal\n    # degraded paths use the per-function namedtuple fallbacks below; this\n    # class only backstops a fallback that itself raised.\n    _fields = (\"total\", \"available\", \"percent\", \"used\", \"free\", \"active\", \"inactive\", \"wired\")\n    total = available = used = free = active = inactive = wired = 0\n    percent = 0.0\n\n    def __init__(self, *_args, **_kwargs):\n        pass\n\n    def __getattr__(self, _name):\n        return 0\n\n    def _values(self):\n        return tuple(getattr(self, _field) for _field in self._fields)\n\n    def __getitem__(self, index):\n        return self._values()[index]\n\n    def __iter__(self):\n        return iter(self._values())\n\n    def __len__(self):\n        return len(self._fields)\n\n    def _asdict(self):\n        return dict(zip(self._fields, self._values()))\n\n\n# Per-function fallback result classes with the exact macOS field\n# orders/arities. Module-level on purpose: readings cross the\n# mozsystemmonitor collector pipe via pickle (by reference), and the parent\n# rebuilds each sample with type(reading)(*values) \u2014 so a swap fallback must\n# be 6-field sswap-shaped in every position. An svmem-shaped fallback there\n# makes the parent reject every sample, fill the pipe, block the collector\n# child in send(), and wedge mach's atexit join forever.\n_FallbackVmem = collections.namedtuple(\n    \"_FallbackVmem\",\n    (\"total\", \"available\", \"percent\", \"used\", \"free\", \"active\", \"inactive\", \"wired\"),\n)\n_FallbackSwap = collections.namedtuple(\n    \"_FallbackSwap\", (\"total\", \"used\", \"free\", \"percent\", \"sin\", \"sout\")\n)\n_FallbackCpuTimes = collections.namedtuple(\"_FallbackCpuTimes\", (\"user\", \"nice\", \"system\", \"idle\"))\n_FallbackDiskIO = collections.namedtuple(\n    \"_FallbackDiskIO\",\n    (\"read_count\", \"write_count\", \"read_bytes\", \"write_bytes\", \"read_time\", \"write_time\"),\n)\n\n_FALLBACK_CLASSES = {\n    \"virtual_memory\": _FallbackVmem,\n    \"swap_memory\": _FallbackSwap,\n    \"cpu_times\": _FallbackCpuTimes,\n    \"disk_io_counters\": _FallbackDiskIO,\n}\n\n# psutil result namedtuple per wrapped function, resolvable via getattr from\n# the platform module / _common without invoking the failing syscall.\n_PSUTIL_RESULT_CLASSES = {\n    \"virtual_memory\": \"svmem\",\n    \"swap_memory\": \"sswap\",\n    \"cpu_times\": \"scputimes\",\n    \"disk_io_counters\": \"sdiskio\",\n}\n\n\ndef _zeroed(cls):\n    return cls(*([0] * len(cls._fields)))\n\n\ndef _percpu_requested(args, kwargs, positional_index):\n    if \"percpu\" in kwargs:\n        return bool(kwargs[\"percpu\"])\n    return len(args) > positional_index and bool(args[positional_index])\n\n\ndef _degraded_result_factory(psutil, name):\n    # cpu_percent returns a plain float (or a per-CPU list) callers do\n    # arithmetic on.\n    if name == \"cpu_percent\":\n        def _cpu_percent_fallback(*args, **kwargs):\n            # cpu_percent(interval=None, percpu=False)\n            if _percpu_requested(args, kwargs, 1):\n                return []\n            return 0.0\n\n        return _cpu_percent_fallback\n    # The guard-owned class is always shape-correct for this function;\n    # psutil's own result namedtuple is still preferred when resolvable so\n    # type() captures stay identical to real readings on a flapping host.\n    _cls = _FALLBACK_CLASSES.get(name, _DegradedReading)\n    _cls_name = _PSUTIL_RESULT_CLASSES.get(name)\n    if _cls_name is not None:\n        for _mod in (getattr(psutil, \"_psplatform\", None), getattr(psutil, \"_common\", None)):\n            _real = getattr(_mod, _cls_name, None) if _mod is not None else None\n            if _real is not None and getattr(_real, \"_fields\", None):\n                _cls = _real\n                break\n    if name == \"cpu_times\":\n        def _cpu_times_fallback(*args, **kwargs):\n            # cpu_times(percpu=False); the collector child samples per-CPU.\n            if _percpu_requested(args, kwargs, 0):\n                return []\n            return _zeroed(_cls)\n\n        return _cpu_times_fallback\n\n    def _reading_fallback(*_args, **_kwargs):\n        return _zeroed(_cls)\n\n    return _reading_fallback\n\n\ndef _guard_psutil():\n    try:\n        import psutil\n    except Exception:\n        return\n\n    def _wrap(orig, fallback):\n        def wrapper(*args, **kwargs):\n            try:\n                return orig(*args, **kwargs)\n            except Exception as exc:  # noqa: BLE001\n                _fireforge_degraded_notice(exc)\n                try:\n                    return fallback(*args, **kwargs)\n                except Exception:  # noqa: BLE001\n                    return _DegradedReading()\n\n        return wrapper\n\n    for _name in (\"virtual_memory\", \"swap_memory\", \"cpu_percent\", \"cpu_times\", \"disk_io_counters\"):\n        _orig = getattr(psutil, _name, None)\n        if _orig is not None and not getattr(_orig, \"_fireforge_guarded\", False):\n            try:\n                _fallback = _degraded_result_factory(psutil, _name)\n            except Exception:  # noqa: BLE001\n                _fallback = _DegradedReading\n            _wrapped = _wrap(_orig, _fallback)\n            _wrapped._fireforge_guarded = True\n            setattr(psutil, _name, _wrapped)\n\n\n_MONITOR_METHOD_NAMES = (\n    \"start\",\n    \"stop\",\n    \"record_event\",\n    \"record_marker\",\n    \"begin_phase\",\n    \"finish_phase\",\n    \"aggregate_cpu_percent\",\n    \"aggregate_cpu_times\",\n    \"aggregate_io\",\n    \"min_memory_available\",\n    \"as_dict\",\n)\n\n\ndef _fireforge_stop_collector(monitor):\n    # Best-effort: terminate a live collector child and drain the parent end\n    # of the pipe, so a child blocked in send() on a full pipe can never\n    # keep mach's atexit join (os.waitpid) waiting forever. Attribute names\n    # follow upstream resourcemonitor.py (self._process / self._pipe); a\n    # miss on a refactored upstream is harmless \u2014 the shape-correct\n    # fallbacks above still keep the sample stream well-formed.\n    try:\n        proc = getattr(monitor, \"_process\", None)\n        if proc is not None and getattr(proc, \"is_alive\", lambda: False)():\n            proc.terminate()\n            proc.join(1)\n    except Exception:  # noqa: BLE001\n        pass\n    try:\n        pipe = getattr(monitor, \"_pipe\", None)\n        if pipe is not None:\n            while pipe.poll(0):\n                pipe.recv()\n    except Exception:  # noqa: BLE001\n        pass\n\n\ndef _monitor_per_cpu_requested(args, kwargs):\n    # aggregate_cpu_percent/aggregate_cpu_times(start=None, end=None,\n    # phase=None, per_cpu=True) \u2014 self already stripped from args.\n    if \"per_cpu\" in kwargs:\n        return bool(kwargs[\"per_cpu\"])\n    if len(args) > 3:\n        return bool(args[3])\n    return True\n\n\ndef _monitor_degraded_result(name, args, kwargs):\n    # Degraded aggregate methods return zeroed shapes, not None, where\n    # callers subscript the result: mozbuild's log_resource_usage does\n    # usage[\"io\"].read_bytes after a successful compile, so None there fails\n    # the build with complete artifacts already on disk.\n    if name == \"aggregate_io\":\n        return _zeroed(_FallbackDiskIO)\n    if name == \"aggregate_cpu_percent\":\n        return [] if _monitor_per_cpu_requested(args, kwargs) else 0.0\n    if name == \"aggregate_cpu_times\":\n        return [] if _monitor_per_cpu_requested(args, kwargs) else _zeroed(_FallbackCpuTimes)\n    return None\n\n\ndef _patch_monitor_class(cls):\n    if cls is None or getattr(cls, \"_fireforge_guarded\", False):\n        return\n    orig_init = cls.__init__\n\n    def guarded_init(self, *args, **kwargs):\n        # Pre-populate the attributes a partially-constructed instance is\n        # later polled for, so a failing __init__ can never surface\n        # AttributeError: poll_interval.\n        self.poll_interval = kwargs.get(\"poll_interval\") or 1.0\n        self._fireforge_degraded = False\n        try:\n            orig_init(self, *args, **kwargs)\n        except Exception as exc:  # noqa: BLE001\n            self._fireforge_degraded = True\n            _fireforge_degraded_notice(exc)\n        if _fireforge_host_degraded[0] and not self._fireforge_degraded:\n            # Host already degraded once: keep the monitor inert so the\n            # collector child never spawns on a flapping host.\n            self._fireforge_degraded = True\n        if self._fireforge_degraded:\n            _fireforge_stop_collector(self)\n\n    cls.__init__ = guarded_init\n\n    def _wrap_method(name, orig):\n        def wrapper(self, *args, **kwargs):\n            if (\n                name == \"start\"\n                and _fireforge_host_degraded[0]\n                and not getattr(self, \"_fireforge_degraded\", False)\n            ):\n                self._fireforge_degraded = True\n                _fireforge_stop_collector(self)\n            if getattr(self, \"_fireforge_degraded\", False):\n                if name == \"stop\":\n                    _fireforge_stop_collector(self)\n                return _monitor_degraded_result(name, args, kwargs)\n            try:\n                return orig(self, *args, **kwargs)\n            except Exception as exc:  # noqa: BLE001\n                self._fireforge_degraded = True\n                _fireforge_degraded_notice(exc)\n                # A raising stop (or any degraded transition) must still\n                # take the collector child down, or the parent's atexit\n                # join hangs on a child blocked writing to a full pipe.\n                _fireforge_stop_collector(self)\n                return _monitor_degraded_result(name, args, kwargs)\n\n        return wrapper\n\n    for _name in _MONITOR_METHOD_NAMES:\n        _orig = getattr(cls, _name, None)\n        if _orig is not None:\n            setattr(cls, _name, _wrap_method(_name, _orig))\n    cls._fireforge_guarded = True\n\n\ndef _patch_build_monitor_class(cls):\n    # mozbuild's BuildMonitor is not a SystemResourceMonitor; only\n    # log_resource_usage needs guarding \u2014 end-of-build resource reporting\n    # must never fail a build whose artifacts are complete. No __init__\n    # replacement, no degraded-instance gating.\n    if cls is None or getattr(cls, \"_fireforge_guarded\", False):\n        return\n    _orig = getattr(cls, \"log_resource_usage\", None)\n    if _orig is not None:\n        def _guarded_log_resource_usage(self, *args, **kwargs):\n            try:\n                return _orig(self, *args, **kwargs)\n            except Exception as exc:  # noqa: BLE001\n                _fireforge_degraded_notice(exc)\n                return None\n\n        cls.log_resource_usage = _guarded_log_resource_usage\n    cls._fireforge_guarded = True\n\n\n_MONITOR_CLASS_PATCHES = (\n    (\"mozsystemmonitor.resourcemonitor\", \"SystemResourceMonitor\", _patch_monitor_class),\n    (\"mozbuild.resources\", \"SystemResourceMonitor\", _patch_monitor_class),\n    (\"mozbuild.controller.building\", \"BuildMonitor\", _patch_build_monitor_class),\n)\n\n\ndef _patch_loaded_monitor_modules():\n    for _mod_name, _cls_name, _patcher in _MONITOR_CLASS_PATCHES:\n        _mod = sys.modules.get(_mod_name)\n        if _mod is not None:\n            try:\n                _patcher(getattr(_mod, _cls_name, None))\n            except Exception:  # noqa: BLE001\n                pass\n\n\ndef _install_import_hook():\n    _orig_import = builtins.__import__\n    if getattr(_orig_import, \"_fireforge_guarded\", False):\n        return\n\n    def _guarding_import(name, *args, **kwargs):\n        _module = _orig_import(name, *args, **kwargs)\n        try:\n            _patch_loaded_monitor_modules()\n        except Exception:  # noqa: BLE001\n            pass\n        return _module\n\n    _guarding_import._fireforge_guarded = True\n    builtins.__import__ = _guarding_import\n\n\ntry:\n    _guard_psutil()\n    _patch_loaded_monitor_modules()\n    _install_import_hook()\nexcept Exception:  # noqa: BLE001\n    pass\n";
+export declare const GUARD_PYTHON_SOURCE = "# Generated by FireForge - do not edit.\n# Degrades the broken host resource monitor family (psutil vs Darwin) from\n# fatal startup errors into non-fatal warnings, so mach builds and tests\n# proceed. Installed into the mach virtualenv site-packages via a .pth file\n# (survives mach's venv re-exec, which drops PYTHONPATH).\nimport builtins\nimport collections\nimport inspect\nimport sys\nimport warnings\n\n# Any psutil degradation observed in this process. Once set, monitors are\n# kept inert (start never spawns the collector child) \u2014 on a flapping host a\n# healthy-looking moment must not be trusted to start a sample stream that a\n# later degraded reading could malform.\n_fireforge_host_degraded = [False]\n\n\ndef _fireforge_degraded_notice(exc):\n    _fireforge_host_degraded[0] = True\n    warnings.warn(\n        \"FireForge: host resource monitor degraded (%s); continuing without resource monitoring.\" % exc\n    )\n\n\nclass _DegradedReading(object):\n    # Last-resort duck type of psutil's namedtuple results (svmem field\n    # order): mozsystemmonitor subscripts, iterates, and unpacks readings,\n    # so the degraded fallback must survive r[0], list(r), len(r), r._fields\n    # and r._asdict(), not just attribute access. The parent also reconstructs\n    # readings via type(reading)(*values), so the constructor must tolerate\n    # the full positional field list. Normal\n    # degraded paths use the per-function namedtuple fallbacks below; this\n    # class only backstops a fallback that itself raised.\n    _fields = (\"total\", \"available\", \"percent\", \"used\", \"free\", \"active\", \"inactive\", \"wired\")\n    total = available = used = free = active = inactive = wired = 0\n    percent = 0.0\n\n    def __init__(self, *_args, **_kwargs):\n        pass\n\n    def __getattr__(self, _name):\n        return 0\n\n    def _values(self):\n        return tuple(getattr(self, _field) for _field in self._fields)\n\n    def __getitem__(self, index):\n        return self._values()[index]\n\n    def __iter__(self):\n        return iter(self._values())\n\n    def __len__(self):\n        return len(self._fields)\n\n    def _asdict(self):\n        return dict(zip(self._fields, self._values()))\n\n\n# Per-function fallback result classes with the exact macOS field\n# orders/arities. Module-level on purpose: readings cross the\n# mozsystemmonitor collector pipe via pickle (by reference), and the parent\n# rebuilds each sample with type(reading)(*values) \u2014 so a swap fallback must\n# be 6-field sswap-shaped in every position. An svmem-shaped fallback there\n# makes the parent reject every sample, fill the pipe, block the collector\n# child in send(), and wedge mach's atexit join forever.\n_FallbackVmem = collections.namedtuple(\n    \"_FallbackVmem\",\n    (\"total\", \"available\", \"percent\", \"used\", \"free\", \"active\", \"inactive\", \"wired\"),\n)\n_FallbackSwap = collections.namedtuple(\n    \"_FallbackSwap\", (\"total\", \"used\", \"free\", \"percent\", \"sin\", \"sout\")\n)\n_FallbackCpuTimes = collections.namedtuple(\"_FallbackCpuTimes\", (\"user\", \"nice\", \"system\", \"idle\"))\n_FallbackDiskIO = collections.namedtuple(\n    \"_FallbackDiskIO\",\n    (\"read_count\", \"write_count\", \"read_bytes\", \"write_bytes\", \"read_time\", \"write_time\"),\n)\n\n_FALLBACK_CLASSES = {\n    \"virtual_memory\": _FallbackVmem,\n    \"swap_memory\": _FallbackSwap,\n    \"cpu_times\": _FallbackCpuTimes,\n    \"disk_io_counters\": _FallbackDiskIO,\n}\n\n# psutil result namedtuple per wrapped function, resolvable via getattr from\n# the platform module / _common without invoking the failing syscall.\n_PSUTIL_RESULT_CLASSES = {\n    \"virtual_memory\": \"svmem\",\n    \"swap_memory\": \"sswap\",\n    \"cpu_times\": \"scputimes\",\n    \"disk_io_counters\": \"sdiskio\",\n}\n\n\ndef _zeroed(cls):\n    return cls(*([0] * len(cls._fields)))\n\n\ndef _percpu_requested(args, kwargs, positional_index):\n    if \"percpu\" in kwargs:\n        return bool(kwargs[\"percpu\"])\n    return len(args) > positional_index and bool(args[positional_index])\n\n\ndef _degraded_result_factory(psutil, name):\n    # cpu_percent returns a plain float (or a per-CPU list) callers do\n    # arithmetic on.\n    if name == \"cpu_percent\":\n        def _cpu_percent_fallback(*args, **kwargs):\n            # cpu_percent(interval=None, percpu=False)\n            if _percpu_requested(args, kwargs, 1):\n                return []\n            return 0.0\n\n        return _cpu_percent_fallback\n    # The guard-owned class is always shape-correct for this function;\n    # psutil's own result namedtuple is still preferred when resolvable so\n    # type() captures stay identical to real readings on a flapping host.\n    _cls = _FALLBACK_CLASSES.get(name, _DegradedReading)\n    _cls_name = _PSUTIL_RESULT_CLASSES.get(name)\n    if _cls_name is not None:\n        for _mod in (getattr(psutil, \"_psplatform\", None), getattr(psutil, \"_common\", None)):\n            _real = getattr(_mod, _cls_name, None) if _mod is not None else None\n            if _real is not None and getattr(_real, \"_fields\", None):\n                _cls = _real\n                break\n    if name == \"cpu_times\":\n        def _cpu_times_fallback(*args, **kwargs):\n            # cpu_times(percpu=False); the collector child samples per-CPU.\n            if _percpu_requested(args, kwargs, 0):\n                return []\n            return _zeroed(_cls)\n\n        return _cpu_times_fallback\n\n    def _reading_fallback(*_args, **_kwargs):\n        return _zeroed(_cls)\n\n    return _reading_fallback\n\n\ndef _guard_psutil():\n    try:\n        import psutil\n    except Exception:\n        return\n\n    def _wrap(orig, fallback):\n        def wrapper(*args, **kwargs):\n            try:\n                return orig(*args, **kwargs)\n            except Exception as exc:  # noqa: BLE001\n                _fireforge_degraded_notice(exc)\n                try:\n                    return fallback(*args, **kwargs)\n                except Exception:  # noqa: BLE001\n                    return _DegradedReading()\n\n        return wrapper\n\n    for _name in (\"virtual_memory\", \"swap_memory\", \"cpu_percent\", \"cpu_times\", \"disk_io_counters\"):\n        _orig = getattr(psutil, _name, None)\n        if _orig is not None and not getattr(_orig, \"_fireforge_guarded\", False):\n            try:\n                _fallback = _degraded_result_factory(psutil, _name)\n            except Exception:  # noqa: BLE001\n                _fallback = _DegradedReading\n            _wrapped = _wrap(_orig, _fallback)\n            _wrapped._fireforge_guarded = True\n            setattr(psutil, _name, _wrapped)\n\n\n_MONITOR_METHOD_NAMES = (\n    \"start\",\n    \"stop\",\n    \"record_event\",\n    \"record_marker\",\n    \"begin_phase\",\n    \"finish_phase\",\n    \"aggregate_cpu_percent\",\n    \"aggregate_cpu_times\",\n    \"aggregate_io\",\n    \"min_memory_available\",\n    \"as_dict\",\n)\n\n\ndef _fireforge_stop_collector(monitor):\n    # Best-effort: terminate a live collector child and drain the parent end\n    # of the pipe, so a child blocked in send() on a full pipe can never\n    # keep mach's atexit join (os.waitpid) waiting forever. Attribute names\n    # follow upstream resourcemonitor.py (self._process / self._pipe); a\n    # miss on a refactored upstream is harmless \u2014 the shape-correct\n    # fallbacks above still keep the sample stream well-formed.\n    try:\n        proc = getattr(monitor, \"_process\", None)\n        if proc is not None and getattr(proc, \"is_alive\", lambda: False)():\n            proc.terminate()\n            proc.join(1)\n    except Exception:  # noqa: BLE001\n        pass\n    try:\n        pipe = getattr(monitor, \"_pipe\", None)\n        if pipe is not None:\n            while pipe.poll(0):\n                pipe.recv()\n    except Exception:  # noqa: BLE001\n        pass\n\n\ndef _monitor_per_cpu_requested(args, kwargs):\n    # aggregate_cpu_percent/aggregate_cpu_times(start=None, end=None,\n    # phase=None, per_cpu=True) \u2014 self already stripped from args.\n    if \"per_cpu\" in kwargs:\n        return bool(kwargs[\"per_cpu\"])\n    if len(args) > 3:\n        return bool(args[3])\n    return True\n\n\ndef _monitor_degraded_result(name, args, kwargs):\n    # Degraded aggregate methods return zeroed shapes, not None, where\n    # callers subscript the result: mozbuild's log_resource_usage does\n    # usage[\"io\"].read_bytes after a successful compile, so None there fails\n    # the build with complete artifacts already on disk.\n    if name == \"aggregate_io\":\n        return _zeroed(_FallbackDiskIO)\n    if name == \"aggregate_cpu_percent\":\n        return [] if _monitor_per_cpu_requested(args, kwargs) else 0.0\n    if name == \"aggregate_cpu_times\":\n        return [] if _monitor_per_cpu_requested(args, kwargs) else _zeroed(_FallbackCpuTimes)\n    return None\n\n\ndef _patch_monitor_class(cls):\n    if cls is None or getattr(cls, \"_fireforge_guarded\", False):\n        return\n    orig_init = cls.__init__\n\n    def guarded_init(self, *args, **kwargs):\n        # Pre-populate the attributes a partially-constructed instance is\n        # later polled for, so a failing __init__ can never surface\n        # AttributeError: poll_interval.\n        self.poll_interval = kwargs.get(\"poll_interval\") or 1.0\n        self._fireforge_degraded = False\n        try:\n            orig_init(self, *args, **kwargs)\n        except Exception as exc:  # noqa: BLE001\n            self._fireforge_degraded = True\n            _fireforge_degraded_notice(exc)\n        if _fireforge_host_degraded[0] and not self._fireforge_degraded:\n            # Host already degraded once: keep the monitor inert so the\n            # collector child never spawns on a flapping host.\n            self._fireforge_degraded = True\n        if self._fireforge_degraded:\n            _fireforge_stop_collector(self)\n\n    cls.__init__ = guarded_init\n\n    def _wrap_method(name, orig):\n        def wrapper(self, *args, **kwargs):\n            if (\n                name == \"start\"\n                and _fireforge_host_degraded[0]\n                and not getattr(self, \"_fireforge_degraded\", False)\n            ):\n                self._fireforge_degraded = True\n                _fireforge_stop_collector(self)\n            if getattr(self, \"_fireforge_degraded\", False):\n                if name == \"stop\":\n                    _fireforge_stop_collector(self)\n                return _monitor_degraded_result(name, args, kwargs)\n            try:\n                return orig(self, *args, **kwargs)\n            except Exception as exc:  # noqa: BLE001\n                self._fireforge_degraded = True\n                _fireforge_degraded_notice(exc)\n                # A raising stop (or any degraded transition) must still\n                # take the collector child down, or the parent's atexit\n                # join hangs on a child blocked writing to a full pipe.\n                _fireforge_stop_collector(self)\n                return _monitor_degraded_result(name, args, kwargs)\n\n        return wrapper\n\n    def _wrap_unbound(name, func):\n        # Upstream declares record_event/record_marker as @staticmethods (and\n        # may declare others as @classmethods). Those take no receiver, so\n        # they cannot use the per-instance degraded flag and must not have one\n        # threaded in \u2014 see the descriptor dispatch below.\n        def wrapper(*args, **kwargs):\n            if _fireforge_host_degraded[0]:\n                return _monitor_degraded_result(name, args, kwargs)\n            try:\n                return func(*args, **kwargs)\n            except Exception as exc:  # noqa: BLE001\n                _fireforge_degraded_notice(exc)\n                return _monitor_degraded_result(name, args, kwargs)\n\n        return wrapper\n\n    for _name in _MONITOR_METHOD_NAMES:\n        # getattr_static returns the raw class attribute, so a staticmethod\n        # is still a staticmethod object here. Plain getattr would hand back\n        # the underlying function, and re-setting THAT on the class rebinds\n        # it as an instance method: the receiver is then passed through as an\n        # extra leading positional and every call raises\n        # \"takes N positional arguments but N+1 were given\". Re-apply the\n        # descriptor the attribute actually had.\n        try:\n            _raw = inspect.getattr_static(cls, _name)\n        except AttributeError:\n            continue\n        if isinstance(_raw, staticmethod):\n            setattr(cls, _name, staticmethod(_wrap_unbound(_name, _raw.__func__)))\n            continue\n        if isinstance(_raw, classmethod):\n            setattr(cls, _name, classmethod(_wrap_unbound(_name, _raw.__func__)))\n            continue\n        _orig = getattr(cls, _name, None)\n        if _orig is not None:\n            setattr(cls, _name, _wrap_method(_name, _orig))\n    cls._fireforge_guarded = True\n\n\ndef _patch_build_monitor_class(cls):\n    # mozbuild's BuildMonitor is not a SystemResourceMonitor; only\n    # log_resource_usage needs guarding \u2014 end-of-build resource reporting\n    # must never fail a build whose artifacts are complete. No __init__\n    # replacement, no degraded-instance gating.\n    if cls is None or getattr(cls, \"_fireforge_guarded\", False):\n        return\n    _orig = getattr(cls, \"log_resource_usage\", None)\n    if _orig is not None:\n        def _guarded_log_resource_usage(self, *args, **kwargs):\n            try:\n                return _orig(self, *args, **kwargs)\n            except Exception as exc:  # noqa: BLE001\n                _fireforge_degraded_notice(exc)\n                return None\n\n        cls.log_resource_usage = _guarded_log_resource_usage\n    cls._fireforge_guarded = True\n\n\n_MONITOR_CLASS_PATCHES = (\n    (\"mozsystemmonitor.resourcemonitor\", \"SystemResourceMonitor\", _patch_monitor_class),\n    (\"mozbuild.resources\", \"SystemResourceMonitor\", _patch_monitor_class),\n    (\"mozbuild.controller.building\", \"BuildMonitor\", _patch_build_monitor_class),\n)\n\n\ndef _patch_loaded_monitor_modules():\n    for _mod_name, _cls_name, _patcher in _MONITOR_CLASS_PATCHES:\n        _mod = sys.modules.get(_mod_name)\n        if _mod is not None:\n            try:\n                _patcher(getattr(_mod, _cls_name, None))\n            except Exception:  # noqa: BLE001\n                pass\n\n\ndef _install_import_hook():\n    _orig_import = builtins.__import__\n    if getattr(_orig_import, \"_fireforge_guarded\", False):\n        return\n\n    def _guarding_import(name, *args, **kwargs):\n        _module = _orig_import(name, *args, **kwargs)\n        try:\n            _patch_loaded_monitor_modules()\n        except Exception:  # noqa: BLE001\n            pass\n        return _module\n\n    _guarding_import._fireforge_guarded = True\n    builtins.__import__ = _guarding_import\n\n\ntry:\n    _guard_psutil()\n    _patch_loaded_monitor_modules()\n    _install_import_hook()\nexcept Exception:  # noqa: BLE001\n    pass\n";
 /** Result of installing the mach resource guard before a dispatch. */
 export interface MachResourceGuardInstallation {
     /**
@@ -83,12 +83,24 @@ export interface MachResourceGuardInstallation {
     /** site-packages directories the in-venv guard was written into. */
     sitePackagesDirs: string[];
 }
+/**
+ * Refuses a shim directory that is not a private directory of the current
+ * user. `lstat`, not `stat`: a symlink planted at the path would otherwise
+ * be followed and the check would describe its target. On Windows only the
+ * "is a real directory" half applies. There is no POSIX owner or mode bit
+ * to read, and the per-user name is the isolation.
+ *
+ * @param dir - Shim directory that {@link ensureSitecustomizeFallback} created
+ * @throws BuildError when the directory is a symlink/file, owned by another
+ *   uid, or group/world-writable
+ */
+export declare function assertPrivateShimDir(dir: string): Promise<void>;
 /**
  * Installs the resource-monitor degrade guard for a mach dispatch:
  * `fireforge_mach_guard.pth` + `fireforge_mach_guard.py` into every
  * discovered mach virtualenv site-packages (survives mach's venv re-exec),
  * plus the PYTHONPATH sitecustomize fallback for the pre-venv bootstrap
- * phase. Idempotent and re-run before EVERY protected dispatch (including
+ * phase. Idempotent and re-run before every protected dispatch (including
  * each retry) so a venv created by a crashed first attempt is guarded on
  * the next one instead of re-dying on the same wedged state.
  */