@hominis/fireforge 0.45.0 → 0.46.0

package/dist/src/core/git.js

@@ -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');
@@ -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

package/dist/src/core/harness-orphans.js

@@ -31,6 +31,7 @@ import { toError } from '../utils/errors.js';
 import { info, verbose, warn } from '../utils/logger.js';
 import { exec } from '../utils/process.js';
 import { parsePsDuration } from '../utils/ps-duration.js';
+import { sleep } from '../utils/sleep.js';
 /**
  * Harness helper executables/scripts. Every one of these is started by the
  * mochitest/xpcshell harness and is expected to die with it; none of them
@@ -93,10 +94,10 @@ const COMMAND_EXCERPT_LIMIT = 160;
  */
 export function formatOrphanReport(orphans) {
     const rows = orphans
-        .map((p) => `  PID ${String(p.pid)} (up ${p.elapsed}): ${p.command.slice(0, COMMAND_EXCERPT_LIMIT)}`)
+        .map((p) => `  PID ${p.pid} (up ${p.elapsed}): ${p.command.slice(0, COMMAND_EXCERPT_LIMIT)}`)
         .join('\n');
     const pids = orphans.map((p) => String(p.pid)).join(' ');
-    return (`${String(orphans.length)} harness helper process(es) from an EARLIER run are still alive ` +
+    return (`${orphans.length} harness helper process(es) from an EARLIER run are still alive ` +
         `(this preflight runs before the current run spawns anything, so none of these belong to ` +
         `it):\n${rows}\n` +
         `Survivors like these slow every later run without appearing anywhere in its output — a ` +
@@ -107,7 +108,7 @@ export function formatOrphanReport(orphans) {
 async function listSystemProcesses() {
     const result = await exec('ps', ['-axo', 'pid=,ppid=,etime=,command='], { timeout: 10000 });
     if (result.exitCode !== 0) {
-        throw new Error(`ps exited ${String(result.exitCode)}`);
+        throw new Error(`ps exited ${result.exitCode}`);
     }
     return result.stdout;
 }
@@ -159,13 +160,13 @@ async function reapOrphanedHarnessProcesses(orphans) {
             process.kill(orphan.pid, 'SIGTERM');
         }
         catch (error) {
-            verbose(`--reap-orphans: SIGTERM to ${String(orphan.pid)} failed (${toError(error).message}).`);
+            verbose(`--reap-orphans: SIGTERM to ${orphan.pid} failed (${toError(error).message}).`);
             continue;
         }
         // Grace period before escalating: the httpd shape in the field
         // incident ignored SIGTERM while spinning, but an ordinary helper exits
         // promptly and must not be SIGKILLed for being slow by a millisecond.
-        await new Promise((resolve) => setTimeout(resolve, REAP_GRACE_MS));
+        await sleep(REAP_GRACE_MS);
         let alive = true;
         try {
             process.kill(orphan.pid, 0);
@@ -178,9 +179,9 @@ async function reapOrphanedHarnessProcesses(orphans) {
                 process.kill(orphan.pid, 'SIGKILL');
             }
             catch (error) {
-                verbose(`--reap-orphans: SIGKILL to ${String(orphan.pid)} failed (${toError(error).message}).`);
+                verbose(`--reap-orphans: SIGKILL to ${orphan.pid} failed (${toError(error).message}).`);
             }
         }
-        info(`--reap-orphans: terminated PID ${String(orphan.pid)}.`);
+        info(`--reap-orphans: terminated PID ${orphan.pid}.`);
     }
 }

package/dist/src/core/history-log.d.ts

@@ -0,0 +1,19 @@
+import type { HistoryEntry } from './destructive.js';
+/**
+ * Appends a history entry for a mutation that has ALREADY committed, degrading
+ * to a warning when the log cannot be written.
+ *
+ * Eleven call sites across `export-flow` and the `patch` subcommands had each
+ * grown the same `try { await appendHistory(...) } catch { warn(...) }` block.
+ * The swallow is deliberate and load-bearing: the patch files and the manifest
+ * are already on disk by the time this runs, so letting a failed log write
+ * reject would report a completed, irreversible mutation as a failure and send
+ * the operator looking for damage that is not there. Because that reasoning is
+ * easy to lose in a copy, it now lives in one place.
+ * @param patchesDir - The `patches/` directory holding the history log.
+ * @param entry - The entry to append.
+ * @param context - What just committed, rendered into
+ *   `History log append failed after <context>: <reason>` — e.g.
+ *   `patch tier committed (007-foo.patch)`.
+ */
+export declare function appendHistoryBestEffort(patchesDir: string, entry: HistoryEntry, context: string): Promise<void>;

package/dist/src/core/history-log.js

@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { toError } from '../utils/errors.js';
+import { warn } from '../utils/logger.js';
+import { appendHistory } from './destructive.js';
+/**
+ * Appends a history entry for a mutation that has ALREADY committed, degrading
+ * to a warning when the log cannot be written.
+ *
+ * Eleven call sites across `export-flow` and the `patch` subcommands had each
+ * grown the same `try { await appendHistory(...) } catch { warn(...) }` block.
+ * The swallow is deliberate and load-bearing: the patch files and the manifest
+ * are already on disk by the time this runs, so letting a failed log write
+ * reject would report a completed, irreversible mutation as a failure and send
+ * the operator looking for damage that is not there. Because that reasoning is
+ * easy to lose in a copy, it now lives in one place.
+ * @param patchesDir - The `patches/` directory holding the history log.
+ * @param entry - The entry to append.
+ * @param context - What just committed, rendered into
+ *   `History log append failed after <context>: <reason>` — e.g.
+ *   `patch tier committed (007-foo.patch)`.
+ */
+export async function appendHistoryBestEffort(patchesDir, entry, context) {
+    try {
+        await appendHistory(patchesDir, entry);
+    }
+    catch (historyError) {
+        warn(`History log append failed after ${context}: ${toError(historyError).message}`);
+    }
+}

package/dist/src/core/mach-error-hints.d.ts

@@ -15,11 +15,6 @@ export interface MachErrorHint {
     /** Actionable, one-line hint to surface alongside the raw mach output. */
     hint: string;
 }
-/**
- * Registered hint patterns. Order-sensitive: the first match wins per
- * pattern, but multiple distinct patterns may fire for the same stderr.
- */
-export declare const MACH_ERROR_HINTS: MachErrorHint[];
 /**
  * Scans captured stderr for known mach errors and returns matching hints.
  * Pure function — safe to call on any string; never throws.

package/dist/src/core/mach-error-hints.js

@@ -13,7 +13,7 @@
  * Registered hint patterns. Order-sensitive: the first match wins per
  * pattern, but multiple distinct patterns may fire for the same stderr.
  */
-export const MACH_ERROR_HINTS = [
+const MACH_ERROR_HINTS = [
     {
         pattern: /mozbuild\.preprocessor\.Preprocessor\.Error[\s\S]*?no preprocessor directives found/,
         hint: 'A file registered under JS_PREFERENCE_PP_FILES contains no preprocessor directives. ' +

package/dist/src/core/mach-known-noise-filter.d.ts

@@ -41,10 +41,11 @@
  * `runProtectedMachBuild`.
  */
 /**
- * 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

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

@@ -57,15 +57,12 @@ const RESOURCEMONITOR_FRAME_PATTERN = /mozsystemmonitor[/\\]resourcemonitor\.py/
  * there; 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
@@ -82,7 +79,8 @@ function isRecognizedTeardownNoise(block) {
  * @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
@@ -159,7 +157,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;
     };

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';
 /**
@@ -96,7 +97,7 @@ export async function assertBrandingMozconfigAgreement(engineDir, mozconfigPath,
     // 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');
     }

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

@@ -1,5 +1,7 @@
 /**
  * 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,11 @@ 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 +92,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 +105,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 +123,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

@@ -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,6 +83,18 @@ 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

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

@@ -63,13 +63,20 @@
  *    warn-and-continue on any exception, so end-of-build resource reporting
  *    can never fail a build whose artifacts are complete.
  */
-import { readdir } from 'node:fs/promises';
-import { homedir, tmpdir } from 'node:os';
+import { lstat, mkdir, readdir } from 'node:fs/promises';
+import { homedir, tmpdir, userInfo } from 'node:os';
 import { delimiter, join } from 'node:path';
+import { BuildError } from '../errors/build.js';
 import { toError } from '../utils/errors.js';
-import { ensureDir, pathExists, writeText } from '../utils/fs.js';
+import { pathExists, writeText } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
-/** Directory name (under the OS temp dir) holding the PYTHONPATH fallback. */
+/**
+ * Prefix of the per-user directory (under the OS temp dir) holding the
+ * PYTHONPATH fallback. The uid (or, on Windows, the username) is appended:
+ * a FIXED name under a shared `/tmp` lets any other local account pre-create
+ * the directory and own the `sitecustomize.py` that every mach dispatch
+ * then imports.
+ */
 const RESOURCE_SHIM_DIRNAME = 'fireforge-mach-resource-shim';
 /** Basename (sans extension) of the in-venv guard module. */
 const GUARD_MODULE_NAME = 'fireforge_mach_guard';
@@ -89,6 +96,7 @@ export const GUARD_PYTHON_SOURCE = `# Generated by FireForge - do not edit.
 # (survives mach's venv re-exec, which drops PYTHONPATH).
 import builtins
 import collections
+import inspect
 import sys
 import warnings
 
@@ -369,7 +377,40 @@ def _patch_monitor_class(cls):
 
         return wrapper
 
+    def _wrap_unbound(name, func):
+        # Upstream declares record_event/record_marker as @staticmethods (and
+        # may declare others as @classmethods). Those take no receiver, so
+        # they cannot use the per-instance degraded flag and must not have one
+        # threaded in — see the descriptor dispatch below.
+        def wrapper(*args, **kwargs):
+            if _fireforge_host_degraded[0]:
+                return _monitor_degraded_result(name, args, kwargs)
+            try:
+                return func(*args, **kwargs)
+            except Exception as exc:  # noqa: BLE001
+                _fireforge_degraded_notice(exc)
+                return _monitor_degraded_result(name, args, kwargs)
+
+        return wrapper
+
     for _name in _MONITOR_METHOD_NAMES:
+        # getattr_static returns the raw class attribute, so a staticmethod
+        # is still a staticmethod object here. Plain getattr would hand back
+        # the underlying function, and re-setting THAT on the class rebinds
+        # it as an instance method: the receiver is then passed through as an
+        # extra leading positional and every call raises
+        # "takes N positional arguments but N+1 were given". Re-apply the
+        # descriptor the attribute actually had.
+        try:
+            _raw = inspect.getattr_static(cls, _name)
+        except AttributeError:
+            continue
+        if isinstance(_raw, staticmethod):
+            setattr(cls, _name, staticmethod(_wrap_unbound(_name, _raw.__func__)))
+            continue
+        if isinstance(_raw, classmethod):
+            setattr(cls, _name, classmethod(_wrap_unbound(_name, _raw.__func__)))
+            continue
         _orig = getattr(cls, _name, None)
         if _orig is not None:
             setattr(cls, _name, _wrap_method(_name, _orig))
@@ -488,13 +529,75 @@ async function discoverMachSitePackages(engineDir) {
     return found;
 }
 /**
- * Writes the PYTHONPATH `sitecustomize.py` fallback into a stable
- * FireForge-owned temp directory and returns that directory. Idempotent —
- * overwriting each call keeps it in sync with this source across upgrades.
+ * Per-user discriminator for the shim directory name. The numeric uid on
+ * POSIX, read via `process.getuid` rather than `os.userInfo()`: the latter
+ * resolves the passwd entry and THROWS (`ERR_SYSTEM_ERROR`) for a uid that
+ * has none — `docker --user 1001:1001`, OpenShift's random uids, many CI
+ * agents — which would take every build and test dispatch down with a raw
+ * system error. On Windows there is no uid; the username is the
+ * discriminator, with `userInfo()` still guarded because the same lookup
+ * can fail there for a service account, falling back to the environment.
+ */
+function shimDirOwner() {
+    const uid = process.getuid?.();
+    if (uid !== undefined)
+        return String(uid);
+    let username;
+    try {
+        username = userInfo().username;
+    }
+    catch {
+        username = process.env['USERNAME'] ?? process.env['USER'];
+    }
+    return (username ?? 'unknown-user').replace(/[^A-Za-z0-9_.-]/g, '_');
+}
+/** Per-user shim directory: `<tmpdir>/fireforge-mach-resource-shim-<uid>`. */
+function resourceShimDir() {
+    return join(tmpdir(), `${RESOURCE_SHIM_DIRNAME}-${shimDirOwner()}`);
+}
+/**
+ * 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 async function assertPrivateShimDir(dir) {
+    const stats = await lstat(dir);
+    const refuse = (reason) => {
+        throw new BuildError(`Refusing to use mach resource shim directory ${dir}: ${reason}. ` +
+            'Another local account may have planted it; remove or fix it and retry.');
+    };
+    if (!stats.isDirectory()) {
+        refuse('not a directory (symlink or file)');
+    }
+    if (process.platform === 'win32')
+        return;
+    const uid = process.getuid?.();
+    if (uid !== undefined && stats.uid !== uid) {
+        refuse(`owned by uid ${stats.uid}, not the current user (uid ${uid})`);
+    }
+    if ((stats.mode & 0o022) !== 0) {
+        refuse(`mode ${(stats.mode & 0o777).toString(8)} is group/world-writable`);
+    }
+}
+/**
+ * Writes the PYTHONPATH `sitecustomize.py` fallback into a per-user,
+ * mode-0700 FireForge-owned temp directory, verified private before the
+ * write, and returns that directory. Idempotent — overwriting each call
+ * keeps it in sync with this source across upgrades.
  */
 async function ensureSitecustomizeFallback() {
-    const dir = join(tmpdir(), RESOURCE_SHIM_DIRNAME);
-    await ensureDir(dir);
+    const dir = resourceShimDir();
+    // `mode` only applies when mkdir creates the directory (and is masked by
+    // the umask); a pre-existing one keeps whatever it had, which is exactly
+    // what the assertion below refuses if it is not private.
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    await assertPrivateShimDir(dir);
     await writeText(join(dir, 'sitecustomize.py'), GUARD_PYTHON_SOURCE);
     return dir;
 }