@hominis/fireforge 0.38.0 → 0.40.0

package/dist/src/commands/test-modes.js

@@ -1,5 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { loadConfig } from '../core/config.js';
+import { findNearestXpcshellManifest } from '../core/xpcshell-appdir.js';
 import { GeneralError } from '../errors/base.js';
 import { success } from '../utils/logger.js';
 /** Rejects pathless `fireforge test` unless the operator selected a pathless mode. */
@@ -59,3 +60,44 @@ function buildPathlessTestMessage() {
         '  - `fireforge test --doctor` to run the Marionette preflight only\n' +
         '  - `fireforge test --canary` to run the configured short harness canary');
 }
+async function classifyTestHarnesses(engineDir, normalizedPaths) {
+    const result = { xpcshell: [], nonXpcshell: [] };
+    for (const testPath of normalizedPaths) {
+        const manifest = await findNearestXpcshellManifest(engineDir, testPath);
+        if (manifest) {
+            result.xpcshell.push(testPath);
+        }
+        else {
+            result.nonXpcshell.push(testPath);
+        }
+    }
+    return result;
+}
+function buildMixedHarnessMessage(classification) {
+    return ('FireForge cannot run xpcshell and browser/mochitest paths in the same mach invocation.\n\n' +
+        'Split this into separate `fireforge test` commands so each manifest selects its own harness:\n' +
+        `  - xpcshell: ${classification.xpcshell.join(', ')}\n` +
+        `  - browser/mochitest: ${classification.nonXpcshell.join(', ')}`);
+}
+/**
+ * Harness classification is a pure path→manifest lookup and must precede
+ * the build dispatch: a mixed xpcshell+mochitest request can never
+ * dispatch, so refusing it before spending minutes in a pre-test build
+ * is strictly better (FORGE F7). A nonexistent path classifies as
+ * nonXpcshell (findNearestXpcshellManifest returns null), so classifying
+ * before assertTestPathsExist is harmless — existence is still asserted
+ * after the stale/coverage gates, preserving their precedence over
+ * missing-path errors. `xpcshellOnly` (non-empty request, zero
+ * nonXpcshell paths) gates the Marionette preflight and the mochitest
+ * client flags (FORGE F10); pathless runs keep the full-suite behavior.
+ */
+export async function classifyBeforeDispatch(engineDir, normalizedPaths) {
+    const classification = await classifyTestHarnesses(engineDir, normalizedPaths);
+    if (classification.xpcshell.length > 0 && classification.nonXpcshell.length > 0) {
+        throw new GeneralError(buildMixedHarnessMessage(classification));
+    }
+    return {
+        classification,
+        xpcshellOnly: normalizedPaths.length > 0 && classification.nonXpcshell.length === 0,
+    };
+}

package/dist/src/commands/test-run.d.ts

@@ -36,6 +36,8 @@ export interface TestRunContext {
     baseExtraArgs: readonly string[];
     /** Bounded harness-crash retry budget (0 disables retries). */
     harnessRetries: number;
+    /** Whether --headless was requested (crash-hint copy only). */
+    headless: boolean;
     /** Extra environment variables for the mach process. */
     env?: Record<string, string>;
 }

package/dist/src/commands/test-run.js

@@ -12,10 +12,12 @@
  * combined invocation stays available via `--no-shard`.
  */
 import { mochitestWithOutput, testWithOutput, xpcshellTestWithOutput, } from '../core/mach.js';
-import { buildHarnessCrashMessage, classifyHarnessRun, } from '../core/test-harness-crash.js';
+import { buildHarnessCrashMessage, classifyHarnessRun, headedNoOutputTimeoutHint, } from '../core/test-harness-crash.js';
 import { retryAfterXpcshellSymlinkRepair } from '../core/test-xpcshell-retry.js';
+import { withXpcshellProfileDir } from '../core/xpcshell-profile-dir.js';
 import { BuildError } from '../errors/build.js';
 import { info, note, warn } from '../utils/logger.js';
+import { getPlatform } from '../utils/platform.js';
 import { maybeInjectAppdirArg } from './test-appdir.js';
 /** Default bounded retry budget for recognized harness crashes. */
 export const DEFAULT_HARNESS_RETRIES = 2;
@@ -33,6 +35,20 @@ function dispatchForSuite(suite) {
  * stale-xpcshell-symlink repair path the single-run flow already used.
  */
 export async function runTestsWithRetries(ctx, paths) {
+    // Pure mochitest dispatches keep their env byte-identical — the profile
+    // variable is xpcshell-harness-specific (FORGE G15b). Generic `mach
+    // test` runs may include xpcshell paths, so they get the isolation too.
+    if (ctx.suite === 'mochitest') {
+        return runTestsWithRetriesInner(ctx, paths, ctx.env);
+    }
+    // Fresh profile dir per harness invocation: shards isolate from each
+    // other and from concurrent `fireforge test` processes; the crash /
+    // symlink-repair retries inside one invocation deliberately REUSE the
+    // same directory (they are the same logical run and the harness
+    // re-initialises the profile contents itself).
+    return withXpcshellProfileDir(ctx.env, (env) => runTestsWithRetriesInner(ctx, paths, env));
+}
+async function runTestsWithRetriesInner(ctx, paths, env) {
     const extraArgs = [...ctx.baseExtraArgs];
     const appdirInjectionAttempted = await maybeInjectAppdirArg(ctx.engineDir, paths, ctx.objDir, extraArgs);
     const dispatch = dispatchForSuite(ctx.suite);
@@ -42,10 +58,10 @@ export async function runTestsWithRetries(ctx, paths) {
     let verdict;
     for (;;) {
         attempts += 1;
-        result = ctx.env
-            ? await dispatch(ctx.engineDir, paths, extraArgs, ctx.env)
+        result = env
+            ? await dispatch(ctx.engineDir, paths, extraArgs, env)
             : await dispatch(ctx.engineDir, paths, extraArgs);
-        result = await retryAfterXpcshellSymlinkRepair(ctx.engineDir, ctx.objDir, result, ctx.classification, paths, extraArgs, ctx.env, dispatch);
+        result = await retryAfterXpcshellSymlinkRepair(ctx.engineDir, ctx.objDir, result, ctx.classification, paths, extraArgs, env, dispatch);
         const combined = `${result.stdout}\n${result.stderr}`;
         verdict = classifyHarnessRun(result.exitCode, combined, paths);
         if (verdict.kind !== 'harness-crash' || attempts >= maxAttempts)
@@ -78,7 +94,12 @@ export async function runShardedTests(ctx, groups, diagnoseShardFailure) {
         const outcome = await runTestsWithRetries(ctx, group.paths);
         shards.push({ label: group.label, outcome });
         if (outcome.verdict.kind === 'harness-crash' && outcome.verdict.signature) {
-            warn(buildHarnessCrashMessage(outcome.verdict.signature, outcome.attempts));
+            const base = buildHarnessCrashMessage(outcome.verdict.signature, outcome.attempts);
+            const hint = headedNoOutputTimeoutHint(outcome.verdict.signature, {
+                headless: ctx.headless,
+                platform: getPlatform(),
+            });
+            warn(hint ? `${base}\n\n${hint}` : base);
         }
         else if (outcome.verdict.kind !== 'tests-ran-ok') {
             const diagnosis = diagnoseShardFailure(outcome, group.label);

package/dist/src/commands/test.js

@@ -10,7 +10,6 @@ import { formatMarionettePreflightLine, reportMarionettePreflight, runMarionette
 import { buildHarnessCrashMessage } from '../core/test-harness-crash.js';
 import { createPostRebuildFailureContext } from '../core/test-harness-output.js';
 import { analyzeTestPathScopes, formatScopeNotice, } from '../core/test-path-scope.js';
-import { findNearestXpcshellManifest } from '../core/xpcshell-appdir.js';
 import { GeneralError } from '../errors/base.js';
 import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
 import { toError } from '../utils/errors.js';
@@ -18,7 +17,7 @@ import { pathExists } from '../utils/fs.js';
 import { info, intro, outro, spinner, success, verbose } from '../utils/logger.js';
 import { stripEnginePrefix } from '../utils/paths.js';
 import { diagnoseShardOutcome, finalizeSingleRunOutcome } from './test-diagnose.js';
-import { assertPathlessTestMode, assertTestModeCombinations, canaryTimeoutSeconds, reportCanaryOutcome, resolveCanaryPath, } from './test-modes.js';
+import { assertPathlessTestMode, assertTestModeCombinations, canaryTimeoutSeconds, classifyBeforeDispatch, reportCanaryOutcome, resolveCanaryPath, } from './test-modes.js';
 import { DEFAULT_HARNESS_RETRIES, runShardedTests, runTestsWithRetries, } from './test-run.js';
 import { enforceStaleBuildGate, enforceStaticComponentsGate } from './test-stale-gate.js';
 async function assertTestPathsExist(engineDir, testPaths) {
@@ -34,19 +33,6 @@ async function assertTestPathsExist(engineDir, testPaths) {
     throw new GeneralError(`Test path${missingPaths.length === 1 ? '' : 's'} not found under engine/: ${missingPaths.join(', ')}\n\n` +
         'If you expected these files to come from your patch stack, run "fireforge import" first.');
 }
-async function classifyTestHarnesses(engineDir, normalizedPaths) {
-    const result = { xpcshell: [], nonXpcshell: [] };
-    for (const testPath of normalizedPaths) {
-        const manifest = await findNearestXpcshellManifest(engineDir, testPath);
-        if (manifest) {
-            result.xpcshell.push(testPath);
-        }
-        else {
-            result.nonXpcshell.push(testPath);
-        }
-    }
-    return result;
-}
 /**
  * Picks the mach dispatch target for a (non-mixed) run. A single-suite run
  * auto-routes to the suite-specific command (`mach xpcshell-test` /
@@ -66,12 +52,6 @@ function resolveTestSuite(classification, forceGeneric) {
     }
     return 'generic';
 }
-function buildMixedHarnessMessage(classification) {
-    return ('FireForge cannot run xpcshell and browser/mochitest paths in the same mach invocation.\n\n' +
-        'Split this into separate `fireforge test` commands so each manifest selects its own harness:\n' +
-        `  - xpcshell: ${classification.xpcshell.join(', ')}\n` +
-        `  - browser/mochitest: ${classification.nonXpcshell.join(', ')}`);
-}
 function filterRedundantXpcshellFlavorArgs(machArgs, classification) {
     if (classification.xpcshell.length === 0 || classification.nonXpcshell.length > 0) {
         return [...machArgs];
@@ -140,7 +120,9 @@ async function runPreTestBuild(projectRoot, paths, projectConfig, harnessRetries
             // anchor forward (a `mach build faster` does not rebake
             // components.conf into the compiled table).
             try {
-                await writeBuildBaseline(projectRoot, paths.engine, projectConfig.binaryName, testPackagingCoverage, previousBaseline);
+                await writeBuildBaseline(projectRoot, paths.engine, projectConfig.binaryName, testPackagingCoverage, previousBaseline, testPackagingCoverage === 'full'
+                    ? 'fireforge test --build'
+                    : `fireforge test --build ${testPackagingCoverage.join(' ')}`);
             }
             catch (baselineError) {
                 verbose(`Could not persist build baseline: ${toError(baselineError).message}`);
@@ -239,7 +221,7 @@ async function runDoctorPreflight(args) {
  * `--mach-arg` and the xpcshell flavor that ignores the pref entirely.
  * Mutates `extraArgs` in place.
  */
-function appendMarionetteForwardingArgs(extraArgs, options, forwardedPort) {
+function appendMarionetteForwardingArgs(extraArgs, options, forwardedPort, xpcshellOnly = false) {
     // Auto-forward the Marionette port to mach when `--marionette-port` is
     // set. `--setpref=marionette.port=<n>` configures where the browser
     // listener binds; `--marionette=127.0.0.1:<n>` tells the mochitest harness
@@ -258,6 +240,14 @@ function appendMarionetteForwardingArgs(extraArgs, options, forwardedPort) {
     // `--marionette=...` (or two-token `--marionette host:port`).
     if (options.marionettePort === undefined)
         return;
+    if (xpcshellOnly) {
+        // Manifest classification says every requested path is xpcshell —
+        // xpcshell ignores the browser Marionette path entirely, and the
+        // mochitest client flags previously forwarded here made mach reject
+        // the dispatch (FORGE F10).
+        info(`--marionette-port=${options.marionettePort} applied to the preflight probe only: the requested paths are xpcshell-only, and xpcshell ignores the browser Marionette port. Not forwarding --setpref=marionette.port or --marionette to mach.`);
+        return;
+    }
     {
         const operatorAlreadyForwarded = forwardedPort !== undefined;
         const machArgs = options.machArg ?? [];
@@ -276,8 +266,23 @@ function appendMarionetteForwardingArgs(extraArgs, options, forwardedPort) {
         }
     }
 }
-async function ensureTestMarionettePortAvailable(port, binaryName, killStaleBrowser) {
-    if (killStaleBrowser) {
+async function ensureTestMarionettePortAvailable(port, binaryName, options, skip) {
+    if (skip.xpcshellOnly && !skip.doctor) {
+        // xpcshell does not bind the browser Marionette port, so a developer's
+        // interactive browser holding 2828 must not kill an xpcshell run
+        // (FORGE F10). --doctor keeps the preflight: its probe launches a
+        // Marionette browser regardless of the requested harness.
+        const message = 'Skipping the Marionette stale-port preflight: all requested paths are xpcshell ' +
+            '(xpcshell does not bind the browser Marionette port).';
+        if (options.marionettePort !== undefined || options.killStaleMarionette === true) {
+            info(message);
+        }
+        else {
+            verbose(message);
+        }
+        return;
+    }
+    if (options.killStaleMarionette === true) {
         await ensureMarionettePortAvailable(port, { binaryName, killStaleBrowser: true });
         return;
     }
@@ -321,6 +326,7 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     // stale/coverage refusals keep precedence over missing-path errors.)
     const requestedPaths = canaryPath !== undefined ? [canaryPath] : testPaths;
     const normalizedPaths = requestedPaths.map((p) => stripEnginePrefix(p).trim());
+    const { classification, xpcshellOnly } = await classifyBeforeDispatch(paths.engine, normalizedPaths);
     // Run incremental build if requested
     if (options.build) {
         // A path-less `test --build` runs (and packages for) the full suite;
@@ -361,7 +367,10 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     // generic bind failure. 2026-04-21 eval (Finding #20): a stale
     // `-marionette` process from `fresh/` poisoned a later test run in
     // the sibling `mybrowser/` workspace.
-    await ensureTestMarionettePortAvailable(effectivePort, projectConfig.binaryName, options.killStaleMarionette === true);
+    await ensureTestMarionettePortAvailable(effectivePort, projectConfig.binaryName, options, {
+        xpcshellOnly,
+        doctor: options.doctor === true,
+    });
     if (options.doctor) {
         const doctorOutcome = await runDoctorPreflight({
             engineDir: paths.engine,
@@ -375,10 +384,6 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
             return;
     }
     await assertTestPathsExist(paths.engine, normalizedPaths);
-    const classification = await classifyTestHarnesses(paths.engine, normalizedPaths);
-    if (classification.xpcshell.length > 0 && classification.nonXpcshell.length > 0) {
-        throw new GeneralError(buildMixedHarnessMessage(classification));
-    }
     const suite = resolveTestSuite(classification, options.genericMachTest === true);
     const forwardedMachArgs = options.machArg && options.machArg.length > 0
         ? filterRedundantXpcshellFlavorArgs(options.machArg, classification)
@@ -401,7 +406,7 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     if (forwardedMachArgs.length > 0) {
         extraArgs.push(...forwardedMachArgs);
     }
-    appendMarionetteForwardingArgs(extraArgs, options, forwardedPort);
+    appendMarionetteForwardingArgs(extraArgs, options, forwardedPort, xpcshellOnly);
     // Directory arguments mean EXACTLY that directory: mozbuild's test
     // resolver matches paths by string prefix, so a bare directory arg
     // silently swept in prefix-named siblings (152.0b7 → 153.0b8 drill:
@@ -437,6 +442,7 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
         suite,
         baseExtraArgs: extraArgs,
         harnessRetries,
+        headless: options.headless === true,
         ...(perfSampleEnv ? { env: perfSampleEnv } : {}),
     };
     const postRebuildContext = options.build
@@ -482,7 +488,7 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
         reportCanaryOutcome(outcome);
         return;
     }
-    finalizeSingleRunOutcome(outcome, normalizedPaths, projectConfig.binaryName, postRebuildContext);
+    finalizeSingleRunOutcome(outcome, normalizedPaths, projectConfig.binaryName, postRebuildContext, options.headless === true);
 }
 /**
  * Builds the perf-sample env contract for the harness run (field report

package/dist/src/commands/token.js

@@ -105,7 +105,10 @@ export async function tokenAddCommand(projectRoot, tokenName, value, options) {
         ...(options.variant !== undefined ? { variant: options.variant } : {}),
     });
     if (result.skipped) {
-        info(`Token ${tokenName} already exists (skipped)`);
+        const where = result.skippedExisting
+            ? ` in category "${result.skippedExisting.category ?? options.category}" (line ${String(result.skippedExisting.line)})`
+            : '';
+        info(`Token ${tokenName} already exists${where} (skipped)`);
     }
     else {
         const forgeConfig = await loadConfig(projectRoot);

package/dist/src/commands/tree.d.ts

@@ -0,0 +1,16 @@
+import { Command } from 'commander';
+import type { CommandContext } from '../types/cli.js';
+/** Creates a verification tree under `.fireforge/trees/<name>`. */
+export declare function treeCreateCommand(projectRoot: string, name: string, options?: {
+    forceCopy?: boolean;
+}): Promise<void>;
+/** Prints the tree list with staleness against the current primary state. */
+export declare function treeListCommand(projectRoot: string, options?: {
+    json?: boolean;
+}): Promise<void>;
+/** Removes one tree (or all of them with `--all`). */
+export declare function treeRemoveCommand(projectRoot: string, name: string | undefined, options?: {
+    all?: boolean;
+}): Promise<void>;
+/** Registers the tree command group on the CLI program. */
+export declare function registerTree(program: Command, context: CommandContext): void;

package/dist/src/commands/tree.js

@@ -0,0 +1,174 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge tree` — copy-on-write verification clones (FORGE G15).
+ *
+ * Trees enable concurrent READ-MOSTLY verification (lint, typecheck,
+ * status, verify, doctor, export dry-runs) beside a busy primary tree.
+ * Exports and every other mutation stay strictly serial in the primary —
+ * a tree's patches/components are snapshots with no merge model, and the
+ * tree guard (cli.ts preAction + core/tree-guard.ts) refuses mutating
+ * commands inside a tree. In-tree `test` and objdir cloning are deferred:
+ * mach objdirs embed absolute source paths, so a cloned objdir would
+ * silently operate against the primary tree.
+ */
+import { spawn } from 'node:child_process';
+import { join } from 'node:path';
+import { Command } from 'commander';
+import { withEngineSessionLock } from '../core/engine-session-lock.js';
+import { detectCowSupport } from '../core/tree-cow.js';
+import { cloneTree, listTrees, removeTree } from '../core/tree-store.js';
+import { assertValidTreeName, computePrimaryFingerprint, getTreesDir, readTreeMarker, withTreeLifecycleLock, } from '../core/tree-store.js';
+import { GeneralError } from '../errors/base.js';
+import { pathExists } from '../utils/fs.js';
+import { info, intro, outro, success, warn } from '../utils/logger.js';
+function assertPosix() {
+    if (process.platform === 'win32') {
+        throw new GeneralError('fireforge tree is POSIX-only; copy-on-write cloning relies on clonefile/reflink, which are not available on Windows.');
+    }
+}
+/** Creates a verification tree under `.fireforge/trees/<name>`. */
+export async function treeCreateCommand(projectRoot, name, options = {}) {
+    assertPosix();
+    intro('FireForge Tree Create');
+    assertValidTreeName(name);
+    if (await readTreeMarker(projectRoot)) {
+        throw new GeneralError('Verification trees cannot be nested: run tree create in the primary tree.');
+    }
+    const treesDir = getTreesDir(projectRoot);
+    const treeRoot = join(treesDir, name);
+    await withTreeLifecycleLock(projectRoot, async () => {
+        if (await pathExists(treeRoot)) {
+            throw new GeneralError(`A tree named "${name}" already exists. Remove it first (fireforge tree remove ${name}) — refresh is remove + create.`);
+        }
+        const { mkdir } = await import('node:fs/promises');
+        await mkdir(treesDir, { recursive: true });
+        const capability = await detectCowSupport(treesDir);
+        if (capability === 'none' && options.forceCopy !== true) {
+            throw new GeneralError('This filesystem cannot copy-on-write (APFS clonefile or btrfs/XFS reflink required), so a tree ' +
+                'would be a full physical copy of the applied engine tree — potentially tens of gigabytes. ' +
+                'Re-run with --force-copy to accept that explicitly.');
+        }
+        if (capability === 'none') {
+            warn('No copy-on-write support detected — performing a full physical copy (--force-copy).');
+        }
+        // Snapshot under the PRIMARY engine-session lock so a mid-mutation
+        // state (half-applied export, furnace deploy) is never captured.
+        const marker = await withEngineSessionLock(projectRoot, 'tree create', () => cloneTree({
+            primaryRoot: projectRoot,
+            treeRoot,
+            name,
+            capability,
+            createdAt: new Date().toISOString(),
+        }));
+        success(`Created verification tree "${name}" at ${treeRoot}`);
+        info(`  Engine HEAD: ${marker.engineHead ?? '(no engine)'}`);
+        info('  Read-only: status, lint, typecheck, verify, doctor, and export --dry-run run inside it; mutation commands are refused.');
+    });
+    outro('Tree created');
+}
+/** Prints the tree list with staleness against the current primary state. */
+export async function treeListCommand(projectRoot, options = {}) {
+    const trees = await listTrees(projectRoot);
+    if (options.json === true) {
+        process.stdout.write(`${JSON.stringify({ schemaVersion: 1, trees }, null, 2)}\n`);
+        return;
+    }
+    intro('FireForge Trees');
+    if (trees.length === 0) {
+        info('No verification trees. Create one with: fireforge tree create <name>');
+        outro('Done');
+        return;
+    }
+    for (const tree of trees) {
+        info(`${tree.name.padEnd(20)} ${tree.staleness.padEnd(24)} created ${tree.createdAt}`);
+    }
+    outro(`${trees.length} tree(s)`);
+}
+/** Removes one tree (or all of them with `--all`). */
+export async function treeRemoveCommand(projectRoot, name, options = {}) {
+    assertPosix();
+    intro('FireForge Tree Remove');
+    if (options.all !== true && name === undefined) {
+        throw new GeneralError('Pass a tree name, or --all to remove every tree.');
+    }
+    await withTreeLifecycleLock(projectRoot, async () => {
+        const targets = options.all === true ? (await listTrees(projectRoot)).map((t) => t.name) : [name ?? ''];
+        if (targets.length === 0) {
+            info('No verification trees to remove.');
+            return;
+        }
+        for (const target of targets) {
+            await removeTree(projectRoot, target);
+            success(`Removed verification tree "${target}"`);
+        }
+    });
+    outro('Tree removal complete');
+}
+/** Spawns `fireforge <args>` with the tree as its working directory. */
+async function treeExecCommand(projectRoot, name, args) {
+    assertPosix();
+    assertValidTreeName(name);
+    const treeRoot = join(getTreesDir(projectRoot), name);
+    const marker = await readTreeMarker(treeRoot);
+    if (!marker) {
+        throw new GeneralError(`No verification tree named "${name}". List trees with: fireforge tree list`);
+    }
+    const current = await computePrimaryFingerprint(projectRoot);
+    if (marker.engineHead !== current.engineHead) {
+        warn(`Tree "${name}" is stale (primary engine advanced since the snapshot).`);
+    }
+    else if (marker.patchesFingerprint !== current.patchesFingerprint) {
+        warn(`Tree "${name}" is stale (primary patches changed since the snapshot).`);
+    }
+    const cliEntry = process.argv[1];
+    if (cliEntry === undefined) {
+        throw new GeneralError('Cannot resolve the fireforge CLI entry point for tree exec.');
+    }
+    const exitCode = await new Promise((resolvePromise, rejectPromise) => {
+        const child = spawn(process.execPath, [cliEntry, ...args], {
+            cwd: treeRoot,
+            stdio: 'inherit',
+        });
+        child.on('error', rejectPromise);
+        child.on('exit', (code) => {
+            resolvePromise(code ?? 1);
+        });
+    });
+    if (exitCode !== 0) {
+        throw new GeneralError(`tree exec: fireforge ${args.join(' ')} exited with code ${String(exitCode)}.`);
+    }
+}
+/** Registers the tree command group on the CLI program. */
+export function registerTree(program, context) {
+    const { getProjectRoot, withErrorHandling } = context;
+    const tree = program
+        .command('tree')
+        .description('Manage copy-on-write verification clones of this project for concurrent read-mostly work (lint, typecheck, status, verify, export --dry-run). Mutation commands are refused inside a tree.');
+    tree
+        .command('create <name>')
+        .description('Clone the project (engine included, obj-* excluded) into .fireforge/trees/<name> using filesystem copy-on-write (APFS clonefile / btrfs-XFS reflink). Refuses on filesystems without CoW support unless --force-copy explicitly accepts a full physical copy.')
+        .option('--force-copy', 'Allow a full physical copy when the filesystem cannot copy-on-write. This can copy tens of GB; never implied.')
+        .action(withErrorHandling(async (name, options) => {
+        await treeCreateCommand(getProjectRoot(), name, options);
+    }));
+    tree
+        .command('list')
+        .description('List verification trees with creation time and staleness vs the primary tree (engine HEAD and patches.json fingerprint).')
+        .option('--json', 'Output the tree list as JSON')
+        .action(withErrorHandling(async (options) => {
+        await treeListCommand(getProjectRoot(), options);
+    }));
+    tree
+        .command('remove [name]')
+        .description("Delete a verification tree. Refuses while a live process holds the tree's build or engine-session lock.")
+        .option('--all', 'Remove every verification tree')
+        .action(withErrorHandling(async (name, options) => {
+        await treeRemoveCommand(getProjectRoot(), name, options);
+    }));
+    tree
+        .command('exec <name> [args...]')
+        .description('Run a fireforge command inside the named tree (equivalent to cd-ing into it). Example: fireforge tree exec shard-a -- lint --per-patch')
+        .action(withErrorHandling(async (name, args) => {
+        await treeExecCommand(getProjectRoot(), name, args);
+    }));
+}

package/dist/src/core/build-baseline-types.d.ts

@@ -76,6 +76,13 @@ export interface BuildBaseline {
      * static-components stale check degrades to "fresh" in that case.
      */
     staticComponentsBaseline?: StaticComponentsBaseline;
+    /**
+     * Invocation shape that recorded this baseline (`'fireforge build'`,
+     * `'fireforge build --ui'`, `'fireforge test --build [paths]'`).
+     * Informational — surfaced by `fireforge status --test-coverage`.
+     * Missing on pre-0.39.0 baselines; render as "unknown".
+     */
+    recordedBy?: string;
 }
 /**
  * State of the engine at the last FULL build, as far as compiled-in XPCOM

package/dist/src/core/build-baseline.d.ts

@@ -48,4 +48,4 @@ export declare function readBuildBaseline(projectRoot: string): Promise<BuildBas
  *   does not rebake `components.conf` registrations, so the last FULL
  *   build stays the honest anchor for the compiled StaticComponents table.
  */
-export declare function writeBuildBaseline(projectRoot: string, engineDir: string, binaryName: string, testPackagingCoverage?: TestPackagingCoverage, previousBaseline?: BuildBaseline): Promise<void>;
+export declare function writeBuildBaseline(projectRoot: string, engineDir: string, binaryName: string, testPackagingCoverage?: TestPackagingCoverage, previousBaseline?: BuildBaseline, recordedBy?: string): Promise<void>;

package/dist/src/core/build-baseline.js

@@ -74,7 +74,7 @@ export async function readBuildBaseline(projectRoot) {
  *   does not rebake `components.conf` registrations, so the last FULL
  *   build stays the honest anchor for the compiled StaticComponents table.
  */
-export async function writeBuildBaseline(projectRoot, engineDir, binaryName, testPackagingCoverage, previousBaseline) {
+export async function writeBuildBaseline(projectRoot, engineDir, binaryName, testPackagingCoverage, previousBaseline, recordedBy) {
     let engineHeadSha = '';
     try {
         engineHeadSha = await getHead(engineDir);
@@ -103,6 +103,7 @@ export async function writeBuildBaseline(projectRoot, engineDir, binaryName, tes
         ...(packageableFingerprints !== undefined ? { packageableFingerprints } : {}),
         ...(testPackagingCoverage !== undefined ? { testPackagingCoverage } : {}),
         ...(staticComponentsBaseline !== undefined ? { staticComponentsBaseline } : {}),
+        ...(recordedBy !== undefined ? { recordedBy } : {}),
     };
     await writeJson(getBuildBaselinePath(projectRoot), baseline);
 }

package/dist/src/core/build-prepare.d.ts

@@ -24,6 +24,15 @@ export interface PrepareBuildOptions {
      */
     previousBaseline?: BuildBaseline | undefined;
 }
+/**
+ * Describes an exit code in the shell's 128+N signal convention. Truncated
+ * configure/build logs with a signal-shaped exit (e.g. 144 = 128+16, SIGURG
+ * on macOS) are environmental interruptions, not compiler failures — naming
+ * that in the failure text saves the operator a fruitless log hunt
+ * (FORGE F16). Returns undefined for codes <= 128 (regular failures) and
+ * for codes past the conventional signal range, so callers append nothing.
+ */
+export declare function describeSignalShapedExit(exitCode: number): string | undefined;
 /**
  * Returns true when the file path matches a pattern that forces
  * `mach configure` to regenerate the backend. Exported for testing.

package/dist/src/core/build-prepare.js

@@ -3,6 +3,7 @@
  * Shared pre-flight logic for build and package commands:
  * story cleanup, branding setup, Furnace component application, and mozconfig generation.
  */
+import { constants as osConstants } from 'node:os';
 import { BuildError } from '../errors/build.js';
 import { FurnaceError } from '../errors/furnace.js';
 import { toError } from '../utils/errors.js';
@@ -33,6 +34,27 @@ function extractMachConfigureError(result) {
         return '';
     return combined.split('\n').slice(-40).join('\n').trim();
 }
+/**
+ * Describes an exit code in the shell's 128+N signal convention. Truncated
+ * configure/build logs with a signal-shaped exit (e.g. 144 = 128+16, SIGURG
+ * on macOS) are environmental interruptions, not compiler failures — naming
+ * that in the failure text saves the operator a fruitless log hunt
+ * (FORGE F16). Returns undefined for codes <= 128 (regular failures) and
+ * for codes past the conventional signal range, so callers append nothing.
+ */
+export function describeSignalShapedExit(exitCode) {
+    if (exitCode <= 128 || exitCode > 192)
+        return undefined;
+    const signalNumber = exitCode - 128;
+    const names = Object.entries(osConstants.signals)
+        .filter(([, value]) => value === signalNumber)
+        .map(([name]) => name);
+    const label = names.length > 0 ? names.join('/') : `signal ${signalNumber}`;
+    return (`Exit ${exitCode} is signal-shaped (${exitCode} - 128 = ${signalNumber}, ${label} on this host): ` +
+        'the process was likely interrupted externally (OOM-killer, terminal disconnect, ' +
+        'display/session teardown) rather than failing on its own, and the log may be ' +
+        'truncated mid-step.');
+}
 /**
  * Builds the `BuildError` for a non-zero auto-configure exit: the output
  * tail (so the underlying mozbuild failure survives), any matched
@@ -43,8 +65,10 @@ function extractMachConfigureError(result) {
 function buildConfigureFailureError(captured) {
     const detail = extractMachConfigureError(captured);
     const hints = explainMachError(`${captured.stderr}\n${captured.stdout}`);
+    const signalNote = describeSignalShapedExit(captured.exitCode);
     return new BuildError(`Backend regeneration failed: mach configure exited with code ${captured.exitCode}.` +
         (detail ? `\n\nmach configure output (tail):\n${detail}` : '') +
+        (signalNote ? `\n\n${signalNote}` : '') +
         (hints.length > 0 ? `\n\n${hints.map((hint) => `Hint: ${hint}`).join('\n')}` : '') +
         '\n\nBuild stopped because continuing would hide the real configure failure.', 'mach configure');
 }

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

@@ -328,6 +328,17 @@ function parsePatchLintBlock(rec) {
     if (checkJsExtraShim !== undefined) {
         out.checkJsExtraShim = parseShimPath(checkJsExtraShim, 'patchLint.checkJsExtraShim');
     }
+    const checkJsTestFiles = rec.raw('checkJsTestFiles');
+    if (checkJsTestFiles !== undefined) {
+        if (typeof checkJsTestFiles !== 'boolean') {
+            throw new ConfigError('Config field "patchLint.checkJsTestFiles" must be a boolean');
+        }
+        out.checkJsTestFiles = checkJsTestFiles;
+    }
+    const checkJsTestShim = rec.raw('checkJsTestShim');
+    if (checkJsTestShim !== undefined) {
+        out.checkJsTestShim = parseShimPath(checkJsTestShim, 'patchLint.checkJsTestShim');
+    }
     const rawColorAllowlist = rec.raw('rawColorAllowlist');
     if (rawColorAllowlist !== undefined) {
         if (!Array.isArray(rawColorAllowlist) ||
@@ -348,12 +359,22 @@ function parsePatchLintBlock(rec) {
     if (chromeScriptJsDoc !== undefined) {
         out.chromeScriptJsDoc = chromeScriptJsDoc;
     }
+    const undefinedIdentifiers = parseSeverityGate(rec.raw('undefinedIdentifiers'), 'patchLint.undefinedIdentifiers');
+    if (undefinedIdentifiers !== undefined) {
+        out.undefinedIdentifiers = undefinedIdentifiers;
+    }
     if (out.checkJsStrict === true && out.checkJs !== true) {
         throw new ConfigError('Config field "patchLint.checkJsStrict" requires "patchLint.checkJs": true');
     }
     if (out.checkJsCompilerOptions !== undefined && out.checkJsStrict !== true) {
         throw new ConfigError('Config field "patchLint.checkJsCompilerOptions" requires "patchLint.checkJsStrict": true');
     }
+    if (out.checkJsTestFiles === true && out.checkJs !== true) {
+        throw new ConfigError('Config field "patchLint.checkJsTestFiles" requires "patchLint.checkJs": true');
+    }
+    if (out.checkJsTestShim !== undefined && out.checkJsTestFiles !== true) {
+        throw new ConfigError('Config field "patchLint.checkJsTestShim" requires "patchLint.checkJsTestFiles": true');
+    }
     return out;
 }
 /**
@@ -413,6 +434,10 @@ function parseTypecheckBlock(rec) {
     if (overrides) {
         out.projectOverrides = overrides;
     }
+    const undefinedIdentifiers = parseSeverityGate(rec.raw('undefinedIdentifiers'), 'typecheck.undefinedIdentifiers');
+    if (undefinedIdentifiers !== undefined) {
+        out.undefinedIdentifiers = undefinedIdentifiers;
+    }
     return out;
 }
 /**