@hominis/fireforge 0.44.4 → 0.45.0

package/dist/src/core/config-validate-file-size.js

@@ -0,0 +1,65 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Validation for `patchLint.fileSizeThresholds`.
+ *
+ * Split out of `config-validate.ts`, which is at its per-file line budget.
+ */
+import { ConfigError } from '../errors/config.js';
+import { isObject } from '../utils/validation.js';
+import { DEFAULT_FILE_SIZE_THRESHOLDS } from './patch-lint-file-size.js';
+/**
+ * Parses one `patchLint.fileSizeThresholds.<tier>` triple. Every field is
+ * optional and merges over the built-in default; values must be positive
+ * integers and stay ordered `notice <= warning <= error`, because an
+ * out-of-order triple would silently disable a band instead of failing.
+ */
+function parseFileSizeTier(raw, field) {
+    if (!isObject(raw)) {
+        throw new ConfigError(`Config field "${field}" must be a plain object`);
+    }
+    const out = {};
+    for (const key of ['notice', 'warning', 'error']) {
+        const value = raw[key];
+        if (value === undefined)
+            continue;
+        if (typeof value !== 'number' || !Number.isInteger(value) || value <= 0) {
+            throw new ConfigError(`Config field "${field}.${key}" must be a positive integer`);
+        }
+        out[key] = value;
+    }
+    for (const key of Object.keys(raw)) {
+        if (!['notice', 'warning', 'error'].includes(key)) {
+            throw new ConfigError(`Config field "${field}" has unknown key "${key}"`);
+        }
+    }
+    return out;
+}
+/**
+ * Parses the `patchLint.fileSizeThresholds` block. Ordering is validated
+ * against the MERGED triple (overrides on top of the defaults), so setting
+ * only `warning` cannot land below the default `notice`.
+ */
+export function parsePatchLintFileSizeThresholds(raw) {
+    if (!isObject(raw)) {
+        throw new ConfigError('Config field "patchLint.fileSizeThresholds" must be a plain object');
+    }
+    const out = {};
+    for (const tier of ['general', 'test']) {
+        const value = raw[tier];
+        if (value === undefined)
+            continue;
+        const parsed = parseFileSizeTier(value, `patchLint.fileSizeThresholds.${tier}`);
+        const merged = { ...DEFAULT_FILE_SIZE_THRESHOLDS[tier], ...parsed };
+        if (merged.notice > merged.warning || merged.warning > merged.error) {
+            throw new ConfigError(`Config field "patchLint.fileSizeThresholds.${tier}" must satisfy notice <= warning <= error ` +
+                `(resolved: ${String(merged.notice)}/${String(merged.warning)}/${String(merged.error)})`);
+        }
+        out[tier] = parsed;
+    }
+    for (const key of Object.keys(raw)) {
+        if (key !== 'general' && key !== 'test') {
+            throw new ConfigError(`Config field "patchLint.fileSizeThresholds" has unknown key "${key}"`);
+        }
+    }
+    return out;
+}

package/dist/src/core/config-validate.js

@@ -8,6 +8,7 @@ import { parseObject } from '../utils/parse.js';
 import { isContainedRelativePath, isExplicitAbsolutePath } from '../utils/paths.js';
 import { describeProductVersionIncompatibility, FIREFOX_PRODUCTS, isObject, isValidAppId, isValidFirefoxCandidate, isValidFirefoxProduct, isValidFirefoxVersion, isValidProjectLicense, PROJECT_LICENSES, } from '../utils/validation.js';
 import { SUPPORTED_CONFIG_ROOT_KEYS } from './config-paths.js';
+import { parsePatchLintFileSizeThresholds } from './config-validate-file-size.js';
 import { parsePatchPolicyBlock } from './config-validate-patch-policy.js';
 import { parseExternalToolchainsBlock, parseTestBlock } from './config-validate-test-toolchains.js';
 /**
@@ -323,6 +324,7 @@ function optionalPatchLintBoolean(rec, key) {
 }
 /** Severity-gate fields, each parsed and assigned identically. */
 const PATCH_LINT_SEVERITY_GATE_KEYS = [
+    'prettier',
     'jsdocClassMethods',
     'testAssertionFloor',
     'chromeScriptJsDoc',
@@ -359,6 +361,10 @@ function parsePatchLintBlock(rec) {
         }
         out.rawColorAllowlist = rawColorAllowlist;
     }
+    const fileSizeThresholds = rec.raw('fileSizeThresholds');
+    if (fileSizeThresholds !== undefined) {
+        out.fileSizeThresholds = parsePatchLintFileSizeThresholds(fileSizeThresholds);
+    }
     for (const key of PATCH_LINT_SEVERITY_GATE_KEYS) {
         const gate = parseSeverityGate(rec.raw(key), `patchLint.${key}`);
         if (gate !== undefined)

package/dist/src/core/harness-orphans.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Preflight census of ORPHANED test-harness helper processes.
+ *
+ * Stopping a long mochitest run mid-flight does not necessarily take its
+ * helpers with it. A downstream incident left `xpcshell` (the harness
+ * httpd, pegged at 100% CPU), `pywebsocket`, `ssltunnel` and `moz-http2`
+ * alive for an hour. Every subsequent run crawled — a three-second suite
+ * took six minutes of wall clock and audio-start waits timed out — and
+ * nothing in FireForge's output connected the slowness to the survivors.
+ * The hour was spent mis-attributing it to the change under test.
+ *
+ * Visibility alone would have collapsed that hour, which is why the census
+ * runs by default and the kill does not. Two rules keep it honest:
+ *
+ *  - The census runs at PREFLIGHT, before this run spawns anything, so
+ *    every matching process is by construction a survivor of an earlier
+ *    run. No age heuristic is needed, and none is used.
+ *  - A match must be anchored to a Firefox OBJDIR. `xpcshell` and
+ *    `server.js` are far too generic on their own; the same rule
+ *    `mochitest-server-port.ts` applies to the httpd holder applies here,
+ *    for the same reason — FireForge has no business reporting, let alone
+ *    terminating, a process it cannot attribute to the harness.
+ *
+ * `--reap-orphans` opts into termination. Without it the census is
+ * report-only, exactly like the `Orphaned harness workers` doctor check
+ * (which covers a DIFFERENT shape: reparented Python multiprocessing
+ * workers, matched on PPID 1 and accumulated CPU time).
+ */
+/** One surviving harness helper process. */
+export interface OrphanedHarnessProcess {
+    pid: number;
+    ppid: number;
+    /** Raw `ps` ELAPSED column. */
+    elapsed: string;
+    /** Parsed elapsed seconds since the process started. */
+    elapsedSeconds: number;
+    command: string;
+}
+/**
+ * Scans `ps -axo pid=,ppid=,etime=,command=` output for surviving harness
+ * helpers. Pure — fixture-testable without spawning anything.
+ *
+ * @param psOutput - Raw `ps` output
+ * @param objDir - Absolute objdir of this project, when known; widens the
+ *   provenance test beyond the generic `obj-…` path segment
+ * @param selfPid - This process's pid, excluded so FireForge cannot report
+ *   itself
+ */
+export declare function findOrphanedHarnessProcesses(psOutput: string, objDir?: string, selfPid?: number): OrphanedHarnessProcess[];
+/**
+ * Renders the census. Names every process with its elapsed time, because
+ * "a leftover harness process exists" and "a leftover harness process has
+ * been burning a core for 58 minutes" are different findings.
+ */
+export declare function formatOrphanReport(orphans: readonly OrphanedHarnessProcess[]): string;
+/**
+ * Preflight census of surviving harness helpers, run before a test
+ * dispatch.
+ *
+ * Best-effort by construction: a host without a usable `ps` (Windows, a
+ * locked-down container) logs at verbose and runs exactly as before. It
+ * never refuses a run — unlike the server-port preflight, a survivor here
+ * degrades performance rather than making the run dispatch against the
+ * wrong server, so the correct response is to say so loudly, not to stop.
+ *
+ * @param objDir - Absolute objdir of this project, when known
+ * @param options - `reap` terminates each recognized survivor (SIGTERM,
+ *   then SIGKILL for anything that stays)
+ * @returns The census, empty when nothing was found or nothing could be probed
+ */
+export declare function reportOrphanedHarnessProcesses(objDir: string | undefined, options?: {
+    reap?: boolean;
+}): Promise<OrphanedHarnessProcess[]>;

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

@@ -0,0 +1,186 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Preflight census of ORPHANED test-harness helper processes.
+ *
+ * Stopping a long mochitest run mid-flight does not necessarily take its
+ * helpers with it. A downstream incident left `xpcshell` (the harness
+ * httpd, pegged at 100% CPU), `pywebsocket`, `ssltunnel` and `moz-http2`
+ * alive for an hour. Every subsequent run crawled — a three-second suite
+ * took six minutes of wall clock and audio-start waits timed out — and
+ * nothing in FireForge's output connected the slowness to the survivors.
+ * The hour was spent mis-attributing it to the change under test.
+ *
+ * Visibility alone would have collapsed that hour, which is why the census
+ * runs by default and the kill does not. Two rules keep it honest:
+ *
+ *  - The census runs at PREFLIGHT, before this run spawns anything, so
+ *    every matching process is by construction a survivor of an earlier
+ *    run. No age heuristic is needed, and none is used.
+ *  - A match must be anchored to a Firefox OBJDIR. `xpcshell` and
+ *    `server.js` are far too generic on their own; the same rule
+ *    `mochitest-server-port.ts` applies to the httpd holder applies here,
+ *    for the same reason — FireForge has no business reporting, let alone
+ *    terminating, a process it cannot attribute to the harness.
+ *
+ * `--reap-orphans` opts into termination. Without it the census is
+ * report-only, exactly like the `Orphaned harness workers` doctor check
+ * (which covers a DIFFERENT shape: reparented Python multiprocessing
+ * workers, matched on PPID 1 and accumulated CPU time).
+ */
+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';
+/**
+ * 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
+ * is a thing a developer runs by hand.
+ */
+const HARNESS_HELPER_PATTERN = /\b(?:xpcshell|pywebsocket\w*|websocket_server\.py|ssltunnel|moz-http2|http2_server|httpd\.js|server\.js|runtests\.py|runxpcshelltests\.py)\b/;
+/** Objdir provenance: an explicit objdir path, a `obj-…` path segment, or `_tests/`. */
+function isObjdirAnchored(command, objDir) {
+    if (objDir !== undefined && objDir.length > 0 && command.includes(objDir))
+        return true;
+    if (/[/\\]obj-[^/\\\s]*[/\\]/.test(command))
+        return true;
+    return /[/\\]_tests[/\\]/.test(command);
+}
+/**
+ * Scans `ps -axo pid=,ppid=,etime=,command=` output for surviving harness
+ * helpers. Pure — fixture-testable without spawning anything.
+ *
+ * @param psOutput - Raw `ps` output
+ * @param objDir - Absolute objdir of this project, when known; widens the
+ *   provenance test beyond the generic `obj-…` path segment
+ * @param selfPid - This process's pid, excluded so FireForge cannot report
+ *   itself
+ */
+export function findOrphanedHarnessProcesses(psOutput, objDir, selfPid = process.pid) {
+    const found = [];
+    for (const line of psOutput.split('\n')) {
+        const match = /^\s*(\d+)\s+(\d+)\s+(\S+)\s+(.+)$/.exec(line);
+        if (!match)
+            continue;
+        const pid = Number(match[1]);
+        const ppid = Number(match[2]);
+        const elapsed = match[3] ?? '';
+        const command = (match[4] ?? '').trim();
+        if (pid === selfPid || ppid === selfPid)
+            continue;
+        if (!HARNESS_HELPER_PATTERN.test(command))
+            continue;
+        if (!isObjdirAnchored(command, objDir))
+            continue;
+        const elapsedSeconds = parsePsDuration(elapsed);
+        found.push({
+            pid,
+            ppid,
+            elapsed,
+            elapsedSeconds: Number.isNaN(elapsedSeconds) ? 0 : elapsedSeconds,
+            command,
+        });
+    }
+    return found;
+}
+/** Grace period between SIGTERM and SIGKILL when reaping. */
+const REAP_GRACE_MS = 500;
+/** Longest command excerpt carried into the report line. */
+const COMMAND_EXCERPT_LIMIT = 160;
+/**
+ * Renders the census. Names every process with its elapsed time, because
+ * "a leftover harness process exists" and "a leftover harness process has
+ * been burning a core for 58 minutes" are different findings.
+ */
+export function formatOrphanReport(orphans) {
+    const rows = orphans
+        .map((p) => `  PID ${String(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 ` +
+        `(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 ` +
+        `three-second suite taking minutes of wall clock is the usual symptom. Terminate them with ` +
+        `"kill ${pids}", or re-run with --reap-orphans to have FireForge do it.`);
+}
+/** Thin exec wrapper for the process listing (tests mock `exec` instead). */
+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)}`);
+    }
+    return result.stdout;
+}
+/**
+ * Preflight census of surviving harness helpers, run before a test
+ * dispatch.
+ *
+ * Best-effort by construction: a host without a usable `ps` (Windows, a
+ * locked-down container) logs at verbose and runs exactly as before. It
+ * never refuses a run — unlike the server-port preflight, a survivor here
+ * degrades performance rather than making the run dispatch against the
+ * wrong server, so the correct response is to say so loudly, not to stop.
+ *
+ * @param objDir - Absolute objdir of this project, when known
+ * @param options - `reap` terminates each recognized survivor (SIGTERM,
+ *   then SIGKILL for anything that stays)
+ * @returns The census, empty when nothing was found or nothing could be probed
+ */
+export async function reportOrphanedHarnessProcesses(objDir, options = {}) {
+    if (process.platform === 'win32')
+        return [];
+    let psOutput;
+    try {
+        psOutput = await listSystemProcesses();
+    }
+    catch (error) {
+        verbose(`Orphan preflight: could not scan processes (${toError(error).message}); skipping.`);
+        return [];
+    }
+    const orphans = findOrphanedHarnessProcesses(psOutput, objDir);
+    if (orphans.length === 0) {
+        verbose('Orphan preflight: no surviving harness helper processes.');
+        return [];
+    }
+    warn(formatOrphanReport(orphans));
+    if (options.reap === true) {
+        await reapOrphanedHarnessProcesses(orphans);
+    }
+    return orphans;
+}
+/**
+ * Terminates each census entry: SIGTERM first, then SIGKILL for anything
+ * still alive. Failures are reported, never thrown — a process that exited
+ * between the census and the signal is the common case, not an error.
+ */
+async function reapOrphanedHarnessProcesses(orphans) {
+    for (const orphan of orphans) {
+        try {
+            process.kill(orphan.pid, 'SIGTERM');
+        }
+        catch (error) {
+            verbose(`--reap-orphans: SIGTERM to ${String(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));
+        let alive = true;
+        try {
+            process.kill(orphan.pid, 0);
+        }
+        catch {
+            alive = false;
+        }
+        if (alive) {
+            try {
+                process.kill(orphan.pid, 'SIGKILL');
+            }
+            catch (error) {
+                verbose(`--reap-orphans: SIGKILL to ${String(orphan.pid)} failed (${toError(error).message}).`);
+            }
+        }
+        info(`--reap-orphans: terminated PID ${String(orphan.pid)}.`);
+    }
+}

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

@@ -25,6 +25,20 @@
  *     echoed verbatim, always.
  *   - 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:
+ *   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
+ *      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
+ * `runProtectedMachBuild`.
  */
 /**
  * True when CAPTURED output carries the documented mozsystemmonitor
@@ -76,6 +90,13 @@ export interface TeardownNoiseContext {
 }
 /** Fresh per-run context — hand the same instance to both stream filters. */
 export declare function createTeardownNoiseContext(): TeardownNoiseContext;
+/**
+ * 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.
+ */
+export declare const KNOWN_TEARDOWN_NOISE_BUILD_NOTE: string;
 /** One line replaces the whole recognized traceback block in the echo. */
 export declare const KNOWN_TEARDOWN_NOISE_ANNOTATION: string;
 /** Chunk-safe, line-buffered echo filter. See module doc. */

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

@@ -26,6 +26,20 @@
  *     echoed verbatim, always.
  *   - 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:
+ *   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
+ *      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
+ * `runProtectedMachBuild`.
  */
 const TRACEBACK_HEADER_PATTERN = /^Traceback \(most recent call last\)/;
 const CHAINED_EXCEPTION_CONNECTOR_PATTERN = /^(?:During handling of the above exception, another exception occurred:|The above exception was the direct cause of the following exception:)\s*$/;
@@ -93,9 +107,18 @@ export function isKnownTeardownNoiseLine(line) {
 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
+ * 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.
+ */
+export const KNOWN_TEARDOWN_NOISE_BUILD_NOTE = '[FireForge] The mozsystemmonitor traceback above is the known upstream ' +
+    'SystemResourceMonitor AttributeError — cosmetic, and not a build failure. It is left ' +
+    'verbatim here (unlike a test run, which collapses it); see docs/testing.md.';
 /** One line replaces the whole recognized traceback block in the echo. */
 export const KNOWN_TEARDOWN_NOISE_ANNOTATION = '[FireForge] Known upstream mozsystemmonitor teardown noise (SystemResourceMonitor ' +
-    'AttributeError at harness shutdown) — not a test failure. See FireForge docs.\n';
+    'AttributeError at harness shutdown) — not a test failure. See docs/testing.md.\n';
 /** Bounds on the held traceback block before flushing verbatim. */
 const HOLD_LINE_LIMIT = 100;
 const HOLD_BYTE_LIMIT = 16 * 1024;

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

@@ -23,6 +23,13 @@ export interface MachOptions {
      * stdout/stderr stay raw — the harness classifier depends on the raw
      * traceback. Unrecognized tracebacks always echo verbatim. Opted into by
      * the test dispatchers only.
+     *
+     * Consumed by {@link runMachCapture} ALONE. `runMachInheritCapture` accepts
+     * it in the type and ignores it — the inherit path has no per-chunk hook,
+     * only a mirror stream that feeds the terminal and the run log the same
+     * string, so filtering there would strip the traceback from the raw log
+     * too. The build path uses the recognition NOTE instead; see
+     * `mach-known-noise-filter.ts`.
      */
     annotateKnownTeardownNoise?: boolean;
     /**

package/dist/src/core/mach.js

@@ -2,12 +2,12 @@
 import { basename, join } from 'node:path';
 import { MachNotFoundError } from '../errors/build.js';
 import { pathExists } from '../utils/fs.js';
-import { warn } from '../utils/logger.js';
+import { info, warn } from '../utils/logger.js';
 import { exec, execInherit, execInheritCapture, execSmokeRun, execStream, } from '../utils/process.js';
 import { createSiblingLockPath, withFileLock } from './file-lock.js';
 import { ensureFirefoxIgnorefileCompatibility } from './firefox-ignorefile.js';
 import { explainMachError } from './mach-error-hints.js';
-import { createKnownTeardownNoiseFilter, createTeardownNoiseContext, } from './mach-known-noise-filter.js';
+import { createKnownTeardownNoiseFilter, createTeardownNoiseContext, hasKnownTeardownNoise, KNOWN_TEARDOWN_NOISE_BUILD_NOTE, } from './mach-known-noise-filter.js';
 import { getPython } from './mach-python.js';
 import { installMachResourceGuard } from './mach-resource-shim.js';
 import { teeToRunLog, writeToActiveRunLog } from './run-log.js';
@@ -193,6 +193,20 @@ function surfaceMachErrorHints(result) {
  * the same crash family the same number of times.
  */
 const DEFAULT_BUILD_CRASH_RETRIES = 2;
+/**
+ * Names the known mozsystemmonitor teardown traceback when a BUILD carried
+ * it. The test path collapses this signature in the echo; a build cannot
+ * (see `mach-known-noise-filter.ts`), so it reached operators as an
+ * unexplained traceback in a build log — a recognized, documented upstream
+ * defect wearing the appearance of a new one. The output is left verbatim
+ * and this one line is added beside it, so the same signature reads the same
+ * in both phases.
+ */
+function noteKnownTeardownNoiseInBuild(result) {
+    if (!hasKnownTeardownNoise(`${result.stdout}\n${result.stderr}`))
+        return;
+    info(KNOWN_TEARDOWN_NOISE_BUILD_NOTE);
+}
 /**
  * The single protected path every FireForge mach build dispatch routes
  * through — `build`, `build --ui`, and the pre-test `--build` step all use
@@ -222,6 +236,7 @@ export async function runProtectedMachBuild(kind, engineDir, options = {}) {
         const { env } = await installMachResourceGuard(engineDir);
         const result = await runMachInheritCapture(args, engineDir, { env });
         if (result.exitCode === 0) {
+            noteKnownTeardownNoiseInBuild(result);
             return { ...result, attempts: attempt };
         }
         const signature = detectHarnessCrashSignature(`${result.stdout}\n${result.stderr}`);
@@ -233,6 +248,7 @@ export async function runProtectedMachBuild(kind, engineDir, options = {}) {
             continue;
         }
         surfaceMachErrorHints(result);
+        noteKnownTeardownNoiseInBuild(result);
         return { ...result, attempts: attempt, ...(signature ? { crashSignature: signature } : {}) };
     }
 }

package/dist/src/core/patch-apply.js

@@ -3,19 +3,19 @@
  * Patch orchestration — coordinates patch discovery, application, and validation.
  * Pure parsing, content transformation, and lock management are in separate modules.
  */
-import { lstat, readlink, realpath } from 'node:fs/promises';
+import { lstat, readFile, readlink, realpath, rm } from 'node:fs/promises';
 import { basename, dirname, join, resolve, sep } from 'node:path';
 import { PatchError } from '../errors/patch.js';
 import { toError } from '../utils/errors.js';
-import { pathExists, readText, writeText } from '../utils/fs.js';
+import { pathExists, readText, writeFileAtomic, writeText } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
 import { isContainedRelativePath } from '../utils/paths.js';
 import { applyPatchIdempotent, reversePatch } from './git.js';
 import { getFileContentFromHead } from './git-file-ops.js';
 import { discoverPatches } from './patch-files.js';
 import { loadPatchesManifest } from './patch-manifest.js';
-import { extractAffectedFiles, extractConflictingFiles, isNewFileInPatch } from './patch-parse.js';
-import { applyPatchTextToContent, extractNewFileContent } from './patch-transform.js';
+import { extractAffectedFiles, extractConflictingFiles, isNewFileInPatch, parseDiffSections, } from './patch-parse.js';
+import { applyPatchTextToContent, extractNewFileContentFromDiff } from './patch-transform.js';
 // Re-export from split modules so existing import sites continue working
 export { PatchError } from '../errors/patch.js';
 export { countPatches, discoverPatches, getAllTargetFilesFromPatch, getTargetFileFromPatch, isNewFilePatch, } from './patch-files.js';
@@ -53,28 +53,57 @@ async function applySinglePatch(patch, engineDir, protectedFiles) {
         const applyError = toError(error);
         // Check if this is a resolvable "new file" conflict
         let resolvedNewFiles = false;
-        // Save original content for files we might overwrite, so we can restore on failure
+        // Save original BYTES of files we might overwrite, so we can restore on
+        // failure. Raw buffers rather than decoded text: the same snapshot has to
+        // restore a binary target byte-for-byte, and a Buffer round-trips text
+        // losslessly where a utf-8 decode of a binary file does not.
         const savedContents = new Map();
+        // New-file sections keyed by target, so the binary discrimination below
+        // reads the ALREADY-parsed section instead of re-scanning the body per
+        // file.
+        const newFileSections = new Map(parseDiffSections(patchContent)
+            .filter((section) => section.isNewFile)
+            .map((section) => [section.targetPath, section]));
         try {
             for (const file of affectedFiles) {
-                if (isNewFileInPatch(patchContent, file)) {
-                    const targetPath = join(engineDir, file);
-                    if (await pathExists(targetPath)) {
-                        savedContents.set(file, await readText(targetPath));
-                        const content = await extractNewFileContent(patch.path, file);
-                        await writeText(targetPath, content);
-                        resolvedNewFiles = true;
+                if (!isNewFileInPatch(patchContent, file))
+                    continue;
+                const targetPath = join(engineDir, file);
+                if (!(await pathExists(targetPath)))
+                    continue;
+                savedContents.set(file, await readFile(targetPath));
+                const section = newFileSections.get(file);
+                if (section?.isBinary === true) {
+                    // A binary new file cannot be resolved by writing extracted text —
+                    // the payload is base85, whose alphabet includes '+'. It does not
+                    // need to be: `git apply` decodes a `GIT binary patch` itself. So
+                    // the resolution is to REMOVE the blocking file and let the retry
+                    // below create it from the payload, which is exactly what the
+                    // text branch achieves by overwriting.
+                    if (!section.hasBinaryDelta) {
+                        // `Binary files … differ` records THAT the bytes changed and
+                        // carries none of them, so nothing can recreate the file. Fail
+                        // honestly rather than deleting a file we cannot put back.
+                        throw new PatchError(`Cannot resolve the new-file conflict for ${file}: the patch's binary section ` +
+                            'carries no replayable payload (`Binary files … differ` rather than `GIT binary ' +
+                            'patch`), so the file cannot be recreated. Re-export the patch with a binary-aware ' +
+                            'diff.', file);
                     }
+                    await rm(targetPath, { force: true });
                 }
+                else {
+                    await writeText(targetPath, extractNewFileContentFromDiff(patchContent, file));
+                }
+                resolvedNewFiles = true;
             }
         }
         catch (extractError) {
-            // extractNewFileContent threw for a LATER target (e.g. a binary
-            // section) after earlier targets were already overwritten — restore
-            // them before reporting failure, instead of letting the exception
-            // skip the restore loop entirely and crash the whole import.
+            // Resolution threw for a LATER target after earlier targets were
+            // already overwritten or removed — restore them before reporting
+            // failure, instead of letting the exception skip the restore loop
+            // entirely and crash the whole import.
             for (const [file, originalContent] of savedContents) {
-                await writeText(join(engineDir, file), originalContent);
+                await writeFileAtomic(join(engineDir, file), originalContent);
             }
             return { patch, success: false, error: toError(extractError).message };
         }
@@ -91,9 +120,9 @@ async function applySinglePatch(patch, engineDir, protectedFiles) {
             }
             catch (retryError) {
                 verbose(`Auto-resolved new-file retry failed for ${patch.filename}: ${toError(retryError).message}`);
-                // Restore original file content before falling through to --reject
+                // Restore original file bytes before falling through to --reject
                 for (const [file, originalContent] of savedContents) {
-                    await writeText(join(engineDir, file), originalContent);
+                    await writeFileAtomic(join(engineDir, file), originalContent);
                 }
             }
         }
@@ -138,7 +167,7 @@ async function rollbackPatches(results, engineDir) {
         if (result.autoResolvedOriginals) {
             for (const [file, originalContent] of result.autoResolvedOriginals) {
                 try {
-                    await writeText(join(engineDir, file), originalContent);
+                    await writeFileAtomic(join(engineDir, file), originalContent);
                     verbose(`Restored pre-existing content of ${file} after rollback`);
                 }
                 catch (restoreError) {

package/dist/src/core/patch-lint-checkjs.js

@@ -30,6 +30,7 @@ import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
 import { normalizePathSlashes } from '../utils/paths.js';
+import { collectUnmanagedCompanions, retargetUnmanagedCompanionHints, } from './patch-lint-unmanaged-companion.js';
 import { composeShimSource, SHIM_FILENAME, SUPPRESSED_DIAGNOSTIC_CODES, TEST_HARNESS_SHIM, UNDEFINED_IDENTIFIER_CODES, UNDEFINED_IDENTIFIER_HINT, } from './typecheck-shim.js';
 // ---------------------------------------------------------------------------
 // Public API
@@ -464,6 +465,7 @@ export async function runCheckJsTestFilesGrouped(repoDir, testFiles, patchLint,
     const mode = modeFromPatchLintConfig(patchLint);
     const seenGlobal = new Set();
     const files = [...testFiles].sort((a, b) => a.localeCompare(b));
+    const companions = await collectUnmanagedCompanions(repoDir, files, testFiles);
     for (const file of files) {
         // Under a rootScope only the scoped files get their own program, but
         // head.js helper discovery still spans the full owned set so a scoped
@@ -483,7 +485,10 @@ export async function runCheckJsTestFilesGrouped(repoDir, testFiles, patchLint,
         const result = await runCheckJsGrouped(repoDir, roots, patchLint.checkJsTestShim, projectRoot, mode, TEST_HARNESS_SHIM);
         const own = result.byFile.get(file);
         if (own && own.length > 0) {
-            merged.byFile.set(file, [...(merged.byFile.get(file) ?? []), ...own]);
+            merged.byFile.set(file, [
+                ...(merged.byFile.get(file) ?? []),
+                ...retargetUnmanagedCompanionHints(own, companions),
+            ]);
         }
         for (const globalIssue of result.global) {
             if (seenGlobal.has(globalIssue.message))