@hominis/fireforge 0.49.2 → 0.51.0

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

@@ -0,0 +1,164 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Where the patch history log lives, and who wrote each record.
+ *
+ * The log used to be `patches/.fireforge-history.jsonl`, inside the tracked
+ * patch queue, so it was committed with every export until consumers
+ * gitignored it, and it grew to tens of megabytes. It now defaults to
+ * `.fireforge/history.jsonl` (FireForge's own untracked data directory), or
+ * `fireforge.json#history.path` when a project sets one. A log left at the
+ * old path is moved on the first append.
+ *
+ * Several sessions sharing one checkout all append to the same log, so each
+ * record carries the invocation that wrote it, plus a session hint, letting
+ * a session select its own lines mechanically.
+ */
+import { randomUUID } from 'node:crypto';
+import { appendFile, link, readFile, rename, rm, stat } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { getNodeErrorCode, toError } from '../utils/errors.js';
+import { ensureDir, pathExists } from '../utils/fs.js';
+import { info, verbose } from '../utils/logger.js';
+import { FIREFORGE_DIR } from './config-paths.js';
+import { isValidHistoryPath } from './config-validate-history.js';
+/** Filename of the history log at its pre-0.50 location, inside `patches/`. */
+export const LEGACY_HISTORY_LOG_FILENAME = '.fireforge-history.jsonl';
+/** Default history log location, relative to the project root. */
+export const DEFAULT_HISTORY_LOG_PATH = join(FIREFORGE_DIR, 'history.jsonl');
+/** Environment variable a caller sets to tag every record of its session. */
+export const HISTORY_SESSION_ENV = 'FIREFORGE_SESSION_ID';
+let invocationId;
+/**
+ * Identity fields stamped on every history record: one id per FireForge
+ * process (every record one command writes shares it), the process and its
+ * parent, and the caller's `FIREFORGE_SESSION_ID` when set. The parent PID
+ * is a weak hint (usually the shell); the environment variable is the
+ * reliable way for a session to tag its own lines.
+ */
+export function historyRecordIdentity() {
+    invocationId ??= randomUUID();
+    const session = process.env[HISTORY_SESSION_ENV]?.trim();
+    return {
+        invocationId,
+        ...(session !== undefined && session !== '' ? { sessionId: session } : {}),
+        pid: process.pid,
+        ppid: process.ppid,
+    };
+}
+/**
+ * Reads `history.path` from the project's raw `fireforge.json`.
+ *
+ * Fail-open: the writer runs after a mutation has already committed, so a
+ * missing or unreadable config means "use the default", never an error. An
+ * invalid value is refused by config validation when the command loads its
+ * config; here it also falls back to the default rather than writing
+ * somewhere validation would not allow.
+ */
+async function readConfiguredHistoryPath(projectRoot) {
+    let data;
+    try {
+        data = JSON.parse(await readFile(join(projectRoot, 'fireforge.json'), 'utf-8'));
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof data !== 'object' || data === null)
+        return undefined;
+    const history = data['history'];
+    if (typeof history !== 'object' || history === null)
+        return undefined;
+    const path = history['path'];
+    if (path === undefined)
+        return undefined;
+    if (!isValidHistoryPath(path)) {
+        verbose(`Ignoring invalid history.path in fireforge.json; using ${DEFAULT_HISTORY_LOG_PATH}`);
+        return undefined;
+    }
+    return path;
+}
+/**
+ * Resolves the history log path for a project.
+ *
+ * @param projectRoot - Project root containing `fireforge.json`
+ * @returns Absolute path of the history log
+ */
+export async function resolveHistoryLogPath(projectRoot) {
+    const configured = await readConfiguredHistoryPath(projectRoot);
+    return resolve(projectRoot, configured ?? DEFAULT_HISTORY_LOG_PATH);
+}
+/**
+ * Moves a history log left at the legacy `patches/` path to `target`.
+ *
+ * Records are never dropped, whatever else is happening:
+ * - The legacy file is first claimed by renaming it aside, so of two
+ *   commands migrating at once exactly one does the work and neither
+ *   duplicates it.
+ * - When `target` does not exist yet (the first run), the claimed file is
+ *   hard-linked into place, which cannot overwrite a log another command
+ *   created in the meantime, and keeps a large log a constant-time move.
+ * - When both exist (an older FireForge appended to the legacy path after
+ *   a migration, or `history.path` changed), the legacy records are
+ *   appended to the target in one write. They then follow newer records;
+ *   every record carries its own `ts`.
+ *
+ * A crash between the claim and the move leaves the records in a
+ * `.migrating-*` file next to the legacy path, never deleted.
+ *
+ * @param patchesDir - The patches directory that may hold a legacy log
+ * @param target - Absolute path of the history log
+ */
+export async function migrateLegacyHistoryLog(patchesDir, target) {
+    const legacy = join(patchesDir, LEGACY_HISTORY_LOG_FILENAME);
+    if (resolve(legacy) === resolve(target))
+        return;
+    try {
+        await stat(legacy);
+    }
+    catch {
+        return;
+    }
+    const claimed = `${legacy}.migrating-${process.pid}-${randomUUID()}`;
+    try {
+        await rename(legacy, claimed);
+    }
+    catch (error) {
+        if (getNodeErrorCode(error) === 'ENOENT')
+            return;
+        throw error;
+    }
+    await ensureDir(dirname(target));
+    try {
+        await link(claimed, target);
+    }
+    catch (error) {
+        // Windows can report two racing renames of one file as both
+        // succeeding, the file ending under the other claimant's name. That
+        // claimant holds the records and moves them, so this one stands down.
+        if (getNodeErrorCode(error) === 'ENOENT' && !(await pathExists(claimed))) {
+            verbose('History log migration lost the claim to a concurrent command');
+            return;
+        }
+        // EEXIST: both logs exist. Anything else (a filesystem without hard
+        // links, a target on another device): the append below creates the
+        // target when it is missing, so it covers that case too.
+        verbose(`History log migration falls back to appending (${toError(error).message})`);
+        await appendFile(target, await readFile(claimed));
+    }
+    await rm(claimed, { force: true });
+    info(`Moved the patch history log from ${legacy} to ${target}. ` +
+        'Nothing reads it back; it is an audit trail only.');
+}
+/**
+ * Appends one serialized record to the project's history log, migrating a
+ * legacy log first.
+ *
+ * @param patchesDir - The project's `patches/` directory; the project root is
+ *   its parent, as every caller derives it from `getProjectPaths`
+ * @param line - One JSON record, without the trailing newline
+ */
+export async function appendHistoryLine(patchesDir, line) {
+    const target = await resolveHistoryLogPath(dirname(resolve(patchesDir)));
+    await migrateLegacyHistoryLog(patchesDir, target);
+    await ensureDir(dirname(target));
+    await appendFile(target, `${line}\n`, 'utf-8');
+}

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

@@ -10,7 +10,8 @@ import type { HistoryEntry } from './destructive.js';
  * 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 patchesDir - The project's `patches/` directory (the log itself lives
+ *   under `.fireforge/` or `history.path`; see `history-log-file.ts`).
  * @param entry - The entry to append.
  * @param context - What just committed, rendered into
  *   `History log append failed after <context>: <reason>`, e.g.

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

@@ -13,7 +13,8 @@ import { appendHistory } from './destructive.js';
  * 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 patchesDir - The project's `patches/` directory (the log itself lives
+ *   under `.fireforge/` or `history.path`; see `history-log-file.ts`).
  * @param entry - The entry to append.
  * @param context - What just committed, rendered into
  *   `History log append failed after <context>: <reason>`, e.g.

package/dist/src/core/json-preserving-edit.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Format-preserving rewrites of a JSON document.
+ *
+ * `fireforge source set`, `fireforge config` and `furnace init` change a
+ * few keys of `fireforge.json`. Re-serializing the whole document with
+ * `JSON.stringify` expands every compact object and array the project keeps
+ * on one line, so a one-key change becomes a diff across unrelated policy
+ * sections. This module diffs the document on disk against the wanted one
+ * and edits only the values that differ, in place, keeping every other byte
+ * (indentation, compact containers, key order, trailing newline).
+ *
+ * Inserted values follow the style of the container they land in: one line
+ * inside a one-line container, the container's own indentation otherwise.
+ */
+import type { JsonObject } from '../types/json.js';
+/**
+ * Rewrites `text` so it parses to `next`, editing only the values that
+ * differ. Returns `undefined` when `text` is not a JSON object or the edit
+ * cannot be proven equivalent, so the caller can fall back to a full
+ * re-serialization.
+ */
+export declare function rewriteJsonPreservingFormat(text: string, next: JsonObject): string | undefined;

package/dist/src/core/json-preserving-edit.js

@@ -0,0 +1,199 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Format-preserving rewrites of a JSON document.
+ *
+ * `fireforge source set`, `fireforge config` and `furnace init` change a
+ * few keys of `fireforge.json`. Re-serializing the whole document with
+ * `JSON.stringify` expands every compact object and array the project keeps
+ * on one line, so a one-key change becomes a diff across unrelated policy
+ * sections. This module diffs the document on disk against the wanted one
+ * and edits only the values that differ, in place, keeping every other byte
+ * (indentation, compact containers, key order, trailing newline).
+ *
+ * Inserted values follow the style of the container they land in: one line
+ * inside a one-line container, the container's own indentation otherwise.
+ */
+import { applyEdits, findNodeAtLocation, modify, parseTree } from 'jsonc-parser';
+import { isJsonObject } from '../utils/validation.js';
+/** The same reviver `readJson` uses, so both sides of the diff agree. */
+function parseJsonDocument(text) {
+    return JSON.parse(text, (key, value) => key === '__proto__' || key === 'constructor' || key === 'prototype' ? undefined : value);
+}
+function jsonEqual(a, b) {
+    if (a === b)
+        return true;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((value, index) => jsonEqual(value, b[index]));
+    }
+    if (!isJsonObject(a) || !isJsonObject(b))
+        return false;
+    const keysA = definedKeys(a);
+    const keysB = definedKeys(b);
+    return keysA.length === keysB.length && keysA.every((key) => jsonEqual(a[key], b[key]));
+}
+/** Keys whose value survives `JSON.stringify` (an `undefined` value is an absent key). */
+function definedKeys(object) {
+    return Object.keys(object).filter((key) => object[key] !== undefined);
+}
+function collectChanges(path, before, after, changes) {
+    if (jsonEqual(before, after))
+        return;
+    if (isJsonObject(before) && isJsonObject(after)) {
+        for (const key of definedKeys(before)) {
+            if (after[key] === undefined)
+                changes.push({ kind: 'remove', path: [...path, key] });
+        }
+        for (const key of definedKeys(after)) {
+            const next = after[key];
+            const previous = before[key];
+            if (previous === undefined) {
+                changes.push({ kind: 'set', path: [...path, key], value: next });
+            }
+            else {
+                collectChanges([...path, key], previous, next, changes);
+            }
+        }
+        return;
+    }
+    if (Array.isArray(before) && Array.isArray(after)) {
+        const isAppend = after.length > before.length &&
+            before.every((value, index) => jsonEqual(value, after[index]));
+        if (isAppend) {
+            for (const value of after.slice(before.length))
+                changes.push({ kind: 'append', path, value });
+            return;
+        }
+        if (after.length === before.length) {
+            before.forEach((value, index) => {
+                collectChanges([...path, index], value, after[index], changes);
+            });
+            return;
+        }
+    }
+    changes.push({ kind: 'set', path, value: after });
+}
+function detectStyle(text) {
+    const indent = /^([ \t]+)\S/m.exec(text)?.[1];
+    return {
+        eol: text.includes('\r\n') ? '\r\n' : '\n',
+        indentUnit: indent === undefined ? '  ' : indent.startsWith('\t') ? '\t' : indent,
+    };
+}
+function isMultiline(text, node) {
+    return node !== undefined && text.slice(node.offset, node.offset + node.length).includes('\n');
+}
+/** The object or array holding `node` (skipping the property node of an object member). */
+function containerOf(node) {
+    const parent = node.parent;
+    return parent?.type === 'property' ? parent.parent : parent;
+}
+/** Leading whitespace of the line `offset` sits on. */
+function lineIndent(text, offset) {
+    const lineStart = text.lastIndexOf('\n', offset - 1) + 1;
+    return /^[ \t]*/.exec(text.slice(lineStart))?.[0] ?? '';
+}
+function renderCompact(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map(renderCompact).join(', ')}]`;
+    }
+    if (isJsonObject(value)) {
+        const entries = definedKeys(value).map((key) => `${JSON.stringify(key)}: ${renderCompact(value[key])}`);
+        return entries.length === 0 ? '{}' : `{ ${entries.join(', ')} }`;
+    }
+    return JSON.stringify(value);
+}
+function renderValue(value, multiline, indent, style) {
+    if (!multiline)
+        return renderCompact(value);
+    return JSON.stringify(value, null, style.indentUnit)
+        .split('\n')
+        .join(style.eol + indent);
+}
+function replaceRange(text, offset, length, content) {
+    return text.slice(0, offset) + content + text.slice(offset + length);
+}
+/** Replaces an existing value, keeping a container's one-line or multi-line shape. */
+function replaceNode(text, node, value, style) {
+    const isContainer = node.type === 'object' || node.type === 'array';
+    const multiline = isContainer ? isMultiline(text, node) : isMultiline(text, containerOf(node));
+    const rendered = renderValue(value, multiline, lineIndent(text, node.offset), style);
+    return replaceRange(text, node.offset, node.length, rendered);
+}
+/** Appends `entry` (a property or an array element) after the container's last child. */
+function appendEntry(text, container, renderEntry, style) {
+    const children = container.children ?? [];
+    const last = children[children.length - 1];
+    const containerIndent = lineIndent(text, container.offset);
+    if (last === undefined) {
+        // Empty container: open it up the way its parent is laid out.
+        const multiline = isMultiline(text, containerOf(container));
+        const [open, close] = container.type === 'array' ? ['[', ']'] : ['{', '}'];
+        const childIndent = containerIndent + style.indentUnit;
+        const body = multiline
+            ? `${open}${style.eol}${childIndent}${renderEntry(true, childIndent)}${style.eol}${containerIndent}${close}`
+            : container.type === 'array'
+                ? `${open}${renderEntry(false, childIndent)}${close}`
+                : `${open} ${renderEntry(false, childIndent)} ${close}`;
+        return replaceRange(text, container.offset, container.length, body);
+    }
+    const multiline = isMultiline(text, container);
+    const indent = multiline ? lineIndent(text, last.offset) : containerIndent;
+    const separator = multiline ? `,${style.eol}${indent}` : ', ';
+    return replaceRange(text, last.offset + last.length, 0, separator + renderEntry(multiline, indent));
+}
+function applyChange(text, change, style) {
+    const root = parseTree(text);
+    if (root === undefined) {
+        throw new Error('document is not valid JSON');
+    }
+    if (change.kind === 'remove') {
+        return applyEdits(text, modify(text, change.path, undefined, {}));
+    }
+    const target = findNodeAtLocation(root, change.path);
+    if (change.kind === 'append') {
+        if (target?.type !== 'array')
+            throw new Error('append target is not an array');
+        return appendEntry(text, target, (multiline, indent) => renderValue(change.value, multiline, indent, style), style);
+    }
+    if (target !== undefined) {
+        return replaceNode(text, target, change.value, style);
+    }
+    const parent = findNodeAtLocation(root, change.path.slice(0, -1));
+    const key = change.path[change.path.length - 1];
+    if (parent?.type !== 'object' || typeof key !== 'string') {
+        throw new Error('insertion parent is not an object');
+    }
+    return appendEntry(text, parent, (multiline, indent) => `${JSON.stringify(key)}: ${renderValue(change.value, multiline, indent, style)}`, style);
+}
+/**
+ * Rewrites `text` so it parses to `next`, editing only the values that
+ * differ. Returns `undefined` when `text` is not a JSON object or the edit
+ * cannot be proven equivalent, so the caller can fall back to a full
+ * re-serialization.
+ */
+export function rewriteJsonPreservingFormat(text, next) {
+    let current;
+    try {
+        current = parseJsonDocument(text);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isJsonObject(current))
+        return undefined;
+    const changes = [];
+    collectChanges([], current, next, changes);
+    const style = detectStyle(text);
+    try {
+        let edited = text;
+        for (const change of changes)
+            edited = applyChange(edited, change, style);
+        // The edits are structural; prove the result before trusting it.
+        return jsonEqual(parseJsonDocument(edited), next) ? edited : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/src/core/line-prefixer.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Prefixes every line of a chunked stream, for output from several
+ * concurrent harness instances (`fireforge test --jobs`) that share one
+ * terminal and one run log. Without a prefix, interleaved lines from two
+ * browsers cannot be attributed after the fact.
+ */
+/** A stateful line prefixer for one stream. */
+export interface LinePrefixer {
+    /** Returns `chunk` with the prefix inserted at the start of each line. */
+    transform(chunk: string): string;
+}
+/**
+ * Creates a prefixer. Line state carries across chunks, so a line split
+ * between two chunks gets the prefix exactly once.
+ *
+ * @param prefix - Text to insert, e.g. `[job 2] `
+ */
+export declare function createLinePrefixer(prefix: string): LinePrefixer;

package/dist/src/core/line-prefixer.js

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Prefixes every line of a chunked stream, for output from several
+ * concurrent harness instances (`fireforge test --jobs`) that share one
+ * terminal and one run log. Without a prefix, interleaved lines from two
+ * browsers cannot be attributed after the fact.
+ */
+/**
+ * Creates a prefixer. Line state carries across chunks, so a line split
+ * between two chunks gets the prefix exactly once.
+ *
+ * @param prefix - Text to insert, e.g. `[job 2] `
+ */
+export function createLinePrefixer(prefix) {
+    let atLineStart = true;
+    return {
+        transform(chunk) {
+            if (chunk.length === 0)
+                return chunk;
+            let out = '';
+            let start = 0;
+            for (let index = chunk.indexOf('\n'); index !== -1; index = chunk.indexOf('\n', start)) {
+                out += `${atLineStart ? prefix : ''}${chunk.slice(start, index + 1)}`;
+                atLineStart = true;
+                start = index + 1;
+            }
+            if (start < chunk.length) {
+                out += `${atLineStart ? prefix : ''}${chunk.slice(start)}`;
+                atLineStart = false;
+            }
+            return out;
+        },
+    };
+}

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

@@ -47,6 +47,11 @@ export interface MachOptions {
     onProcessGroup?: (pgid: number) => void;
     /** Exec-layer hook, see {@link ProcessGroupOptions.postCloseSweep}. Capture-only. */
     postCloseSweep?: () => Promise<void>;
+    /**
+     * Prefix for every echoed and logged line (concurrent `test --jobs`
+     * instances). The capture and `onOutputChunk` stay raw. Capture-only.
+     */
+    outputPrefix?: string | undefined;
 }
 /**
  * Result of running a mach command while capturing streamed output.
@@ -263,6 +268,8 @@ export interface MachTestSuiteOptions {
      * the harness launched. See {@link MachOptions}.
      */
     teardown?: Pick<MachOptions, 'onOutputChunk' | 'onProcessGroup' | 'postCloseSweep'> | undefined;
+    /** Line prefix for echo and run log, see {@link MachOptions.outputPrefix}. */
+    outputPrefix?: string | undefined;
 }
 /**
  * Runs one mach test command (`mach test` / `mach xpcshell-test` / `mach

package/dist/src/core/mach.js

@@ -1,11 +1,13 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { basename, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 import { MachNotFoundError } from '../errors/build.js';
 import { pathExists } from '../utils/fs.js';
 import { info, warn } from '../utils/logger.js';
 import { exec, execInherit, execInheritCapture, execSmokeRun, execStream, } from '../utils/process.js';
+import { withBuildRunRecord } from './build-run-record.js';
 import { createSiblingLockPath, withFileLock } from './file-lock.js';
 import { ensureFirefoxIgnorefileCompatibility } from './firefox-ignorefile.js';
+import { createLinePrefixer } from './line-prefixer.js';
 import { explainMachError } from './mach-error-hints.js';
 import { createKnownTeardownNoiseFilter, createTeardownNoiseContext, hasKnownTeardownNoise, KNOWN_TEARDOWN_NOISE_BUILD_NOTE, } from './mach-known-noise-filter.js';
 import { getPython } from './mach-python.js';
@@ -88,6 +90,15 @@ export async function runMachCapture(args, engineDir, options = {}) {
     const noiseContext = options.annotateKnownTeardownNoise === true ? createTeardownNoiseContext() : undefined;
     const stdoutFilter = noiseContext && createKnownTeardownNoiseFilter(noiseContext);
     const stderrFilter = noiseContext && createKnownTeardownNoiseFilter(noiseContext);
+    const prefix = options.outputPrefix;
+    const prefixers = prefix === undefined
+        ? undefined
+        : {
+            stdoutLog: createLinePrefixer(prefix),
+            stdoutEcho: createLinePrefixer(prefix),
+            stderrLog: createLinePrefixer(prefix),
+            stderrEcho: createLinePrefixer(prefix),
+        };
     const exitCode = await execStream(python, [machPath, ...args], {
         cwd: engineDir,
         ...(options.env ? { env: options.env } : {}),
@@ -109,8 +120,9 @@ export async function runMachCapture(args, engineDir, options = {}) {
             // echo filter only exists to shorten what a human scrolls past.
             // Collapsing a traceback in the artifact would reintroduce the loss
             // this log exists to prevent.
-            writeToActiveRunLog(data);
-            process.stdout.write(stdoutFilter ? stdoutFilter.transform(data) : data);
+            writeToActiveRunLog(prefixers ? prefixers.stdoutLog.transform(data) : data);
+            const echo = stdoutFilter ? stdoutFilter.transform(data) : data;
+            process.stdout.write(prefixers ? prefixers.stdoutEcho.transform(echo) : echo);
         },
         onStderr: (data) => {
             options.onOutputChunk?.('stderr', data);
@@ -118,19 +130,22 @@ export async function runMachCapture(args, engineDir, options = {}) {
             if (stderr.length > CAPTURE_TAIL_LIMIT) {
                 stderr = stderr.slice(-CAPTURE_TAIL_LIMIT);
             }
-            writeToActiveRunLog(data);
-            process.stderr.write(stderrFilter ? stderrFilter.transform(data) : data);
+            writeToActiveRunLog(prefixers ? prefixers.stderrLog.transform(data) : data);
+            const echo = stderrFilter ? stderrFilter.transform(data) : data;
+            process.stderr.write(prefixers ? prefixers.stderrEcho.transform(echo) : echo);
         },
     });
     if (stdoutFilter) {
         const residue = stdoutFilter.flush();
-        if (residue.length > 0)
-            process.stdout.write(residue);
+        if (residue.length > 0) {
+            process.stdout.write(prefixers ? prefixers.stdoutEcho.transform(residue) : residue);
+        }
     }
     if (stderrFilter) {
         const residue = stderrFilter.flush();
-        if (residue.length > 0)
-            process.stderr.write(residue);
+        if (residue.length > 0) {
+            process.stderr.write(prefixers ? prefixers.stderrEcho.transform(residue) : residue);
+        }
     }
     return { stdout, stderr, exitCode };
 }
@@ -227,6 +242,12 @@ export async function runProtectedMachBuild(kind, engineDir, options = {}) {
     if (kind === 'full' && options.jobs !== undefined) {
         args.push('-j', String(options.jobs));
     }
+    // The run record lets any session see why a bundle is missing after this
+    // build dies part-way (see build-run-record.ts). The engine directory is
+    // always `<projectRoot>/engine`.
+    return withBuildRunRecord(dirname(engineDir), `mach ${args.join(' ')}`, () => runProtectedMachBuildAttempts(args, kind, engineDir, options));
+}
+async function runProtectedMachBuildAttempts(args, kind, engineDir, options) {
     const maxAttempts = Math.max(1, (options.retries ?? DEFAULT_BUILD_CRASH_RETRIES) + 1);
     for (let attempt = 1;; attempt += 1) {
         const { env } = await installMachResourceGuard(engineDir);
@@ -411,13 +432,14 @@ function testVerbosityEnvUnset(fullOutput) {
  * @param options - Engine checkout, test paths, extra args, env, verbosity
  */
 export async function runMachTestSuite(kind, options) {
-    const { engineDir, testPaths = [], args = [], env, fullOutput, teardown } = options;
+    const { engineDir, testPaths = [], args = [], env, fullOutput, teardown, outputPrefix } = options;
     const guard = await installMachResourceGuard(engineDir);
     const envUnset = testVerbosityEnvUnset(fullOutput);
     return runMachCapture([kind, ...testPaths, ...args], engineDir, {
         env: { ...guard.env, ...env },
         ...(envUnset ? { envUnset } : {}),
         ...teardown,
+        ...(outputPrefix === undefined ? {} : { outputPrefix }),
         annotateKnownTeardownNoise: true,
     });
 }

package/dist/src/core/module-resolution-preflight.d.ts

@@ -18,6 +18,12 @@
  * no owned file is an upstream Firefox module, which FireForge does not
  * police and cannot cheaply enumerate. Policing only what the fork owns is
  * both the actionable set and the one that produces real incidents.
+ *
+ * An unscoped `verify` widens that set with the engine worktree: changed
+ * files import, and untracked files are targets. A chrome script's lazy
+ * getter for a new, not yet exported `.sys.mjs` with no moz.build line
+ * SIGSEGVed every start of a shared objdir, and neither file was in the
+ * queue yet, so the queue-only scan could not see it.
  */
 /** Why a queue-owned module import does not resolve to a packaged module. */
 export type UnresolvedModuleReason = 'missing-file' | 'unregistered';
@@ -31,16 +37,26 @@ export interface UnresolvedModuleImport {
     importers: string[];
     reason: UnresolvedModuleReason;
 }
+/** Engine worktree files the preflight also judges, beside the queue's. */
+export interface WorktreeModuleFiles {
+    /** Changed or untracked files: scanned for imports. */
+    changed: readonly string[];
+    /** Untracked files: new modules the fork has not exported yet. */
+    untracked: readonly string[];
+}
+/** Lists the engine's changed and untracked files for the worktree scan. */
+export declare function collectWorktreeModuleFiles(engineDir: string): Promise<WorktreeModuleFiles>;
 /**
  * Resolves every `resource://` system-module import made by the
- * queue-owned files and reports the ones a packaged browser could not
- * load.
+ * queue-owned files (and, given `worktree`, by changed engine files) and
+ * reports the ones a packaged browser could not load.
  *
  * @param engineDir - Path to the engine checkout
  * @param ownedFiles - Engine-relative paths the patch queue owns
+ * @param worktree - Changed and untracked engine files to judge as well
  * @returns Findings sorted by module path. Empty when everything resolves
  */
-export declare function findUnresolvedSystemModuleImports(engineDir: string, ownedFiles: readonly string[]): Promise<UnresolvedModuleImport[]>;
+export declare function findUnresolvedSystemModuleImports(engineDir: string, ownedFiles: readonly string[], worktree?: WorktreeModuleFiles): Promise<UnresolvedModuleImport[]>;
 /**
  * Renders findings as operator-facing lines, naming the unregistered or
  * unresolvable module, so the failure is a sentence instead of a bare