@hominis/fireforge 0.39.0 → 0.41.0

package/dist/src/commands/status.js

@@ -5,15 +5,17 @@ import { getProjectPaths, loadConfig } from '../core/config.js';
 import { collectFurnaceManagedPrefixes } from '../core/furnace-config.js';
 import { getHead, getStatusWithCodes, isGitRepository, isMissingHeadError } from '../core/git.js';
 import { getUntrackedFilesInDir, resolveMaxUntrackedFilesPerDir } from '../core/git-status.js';
-import { buildOwnershipTable, renderOwnershipTable } from '../core/ownership-table.js';
-import { buildPatchQueueContext, collectNewFileCreatorsByPath } from '../core/patch-lint.js';
+import { renderOwnershipTable } from '../core/ownership-table.js';
 import { loadPatchesManifest } from '../core/patch-manifest.js';
-import { classifyFiles, } from '../core/status-classify.js';
-import { CommandError, GeneralError } from '../errors/base.js';
+import { classifyFiles } from '../core/status-classify.js';
+import { CommandError, GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { ExitCode } from '../errors/codes.js';
 import { FIREFORGE_TMP_PATH_PATTERN, pathExists } from '../utils/fs.js';
 import { info, intro, isMachineOutputMode, outro, setMachineOutputMode, warn, } from '../utils/logger.js';
+import { resolveStatusCheckPolicy, runStatusCheck } from './status-check.js';
+import { renderJsonStatus, renderJsonSummaryStatus } from './status-json.js';
 import { renderDefaultStatus, renderTestCoverageStatus, renderUnmanagedOnly, } from './status-output.js';
+import { buildOwnershipJsonBlock, collectOwnershipRows, summarizeOwnership, } from './status-ownership.js';
 /**
  * Renders raw worktree status as machine-parseable porcelain-style output.
  * Each line is: STATUS<tab>FILE
@@ -86,40 +88,52 @@ function filterFireForgeTempFiles(files) {
 /**
  * Renders classified file status as machine-readable JSON to stdout.
  */
-async function renderJsonStatus(files, paths, projectRoot, binaryName) {
+async function classifyStatusFiles(files, paths, projectRoot, binaryName) {
     const furnacePrefixes = await collectFurnaceManagedPrefixes(projectRoot);
-    const classified = await classifyFiles(files, paths.engine, paths.patches, binaryName, furnacePrefixes);
-    const outputFiles = classified.map((f) => {
-        const entry = {
-            file: f.file,
-            status: f.status.trim(),
-            classification: f.classification,
-        };
-        if (f.classification === 'conflict' && f.claimedBy && f.claimedBy.length > 0) {
-            entry.claimedBy = [...f.claimedBy];
-        }
-        return entry;
-    });
-    const byClassification = {
-        unmanaged: 0,
-        'patch-owned-drift': 0,
-        'patch-backed': 0,
-        branding: 0,
-        furnace: 0,
-        conflict: 0,
-    };
-    for (const file of outputFiles) {
-        byClassification[file.classification]++;
+    return classifyFiles(files, paths.engine, paths.patches, binaryName, furnacePrefixes);
+}
+/**
+ * The one worktree scan every classifying mode shares: porcelain status,
+ * collapsed-directory expansion, atomic-temp-file filtering, and the
+ * truncation banner. `--ownership` used to carry its own copy of this
+ * block (FORGE L3); a non-git engine degrades to an empty list there,
+ * which is why the git probe is a parameter rather than a hard guard.
+ * @param engineDir - Path to the engine directory
+ * @param requireGitRepository - When false, a non-git engine yields `[]`
+ *   instead of being probed (the historical `--ownership` behavior)
+ */
+async function scanEngineStatusFiles(engineDir, requireGitRepository) {
+    if (!requireGitRepository && !(await isGitRepository(engineDir))) {
+        return [];
     }
-    const output = {
-        schemaVersion: 1,
-        summary: {
-            total: outputFiles.length,
-            byClassification,
-        },
-        files: outputFiles,
-    };
-    process.stdout.write(JSON.stringify(output, null, 2) + '\n');
+    const { entries, truncations } = await expandDirectoryEntries(await getStatusWithCodes(engineDir), engineDir);
+    renderTruncationBanner(truncations);
+    return filterFireForgeTempFiles(entries);
+}
+/**
+ * Emits the `--json` payload (full or `--summary`) and applies the
+ * `--check` policy, which stays the SOLE exit driver on this path.
+ *
+ * `--include-ownership` (FORGE L3) is a MODIFIER, not a mode: it appends an
+ * ownership block without touching exit semantics, so an ownership conflict
+ * still fails only the human `--ownership` mode.
+ * @param classified - Classified worktree entries
+ * @param files - The same entries pre-classification, for ownership rows
+ * @param paths - Resolved project paths
+ * @param options - Status display options
+ * @param checkPolicy - Resolved `--check`/`--fail-on` policy
+ */
+async function renderJsonMode(classified, files, paths, options, checkPolicy) {
+    const ownership = options.includeOwnership === true
+        ? buildOwnershipJsonBlock(await collectOwnershipRows(paths.patches, (await loadPatchesManifest(paths.patches))?.patches ?? [], files, classified))
+        : undefined;
+    if (options.summary === true) {
+        renderJsonSummaryStatus(classified, checkPolicy, ownership);
+    }
+    else {
+        renderJsonStatus(classified, ownership);
+    }
+    runStatusCheck(classified, checkPolicy);
 }
 /**
  * Detects the "unborn HEAD" aftermath of an interrupted `fireforge download`
@@ -170,149 +184,151 @@ export async function statusCommand(projectRoot, options = {}) {
     if (shouldUseMachineOutput) {
         setMachineOutputMode(true);
     }
-    try {
-        const modeCount = [
-            options.raw,
-            options.unmanaged,
-            options.ownership,
-            options.testCoverage,
-            options.json,
-        ].filter((v) => v === true).length;
-        if (modeCount > 1) {
-            throw new GeneralError('Cannot use --raw, --unmanaged, --ownership, --test-coverage, and --json together. Pick at most one.');
-        }
-        if (!options.raw && !options.json) {
-            intro('FireForge Status');
-        }
-        // Test-coverage mode needs only the project root (the baseline lives
-        // in .fireforge/), so it short-circuits before any engine/git guards.
-        if (options.testCoverage) {
-            renderTestCoverageStatus(await readBuildBaseline(projectRoot));
-            return;
-        }
-        const paths = getProjectPaths(projectRoot);
-        const config = await loadConfig(projectRoot);
-        const emitJsonError = (code, message) => {
-            process.stdout.write(JSON.stringify({ schemaVersion: 1, error: message, code }) + '\n');
-            throw new CommandError(ExitCode.GENERAL_ERROR);
-        };
-        // Ownership mode is a flat file→patch table; sources are the manifest's
-        // filesAffected, any worktree drift, and the cross-patch
-        // duplicate-new-file-creation map produced by walking each patch
-        // body. The latter is the alignment fix between `status --ownership`
-        // and `fireforge verify` — see buildOwnershipTable's header comment.
-        // Runs before the default classify path so we can short-circuit
-        // without computing patch-backed state.
-        if (options.ownership) {
-            if (!(await pathExists(paths.engine))) {
-                throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
-            }
-            const manifest = await loadPatchesManifest(paths.patches);
-            const ownershipExpansion = (await isGitRepository(paths.engine))
-                ? await expandDirectoryEntries(await getStatusWithCodes(paths.engine), paths.engine)
-                : { entries: [], truncations: [] };
-            // Filter atomic-write temp files (Finding #18) so a mid-flight
-            // `.fireforge-tmp-<pid>-<uuid>` artefact never shows up in any
-            // status mode. The pattern is tight enough to let legitimately
-            // similar names through.
-            const rawFilesOwnership = filterFireForgeTempFiles(ownershipExpansion.entries);
-            renderTruncationBanner(ownershipExpansion.truncations);
-            // Only walk the patch bodies when the directory actually exists.
-            // Fresh projects with no patch queue yet pass through with an empty
-            // creators map, which degrades to the old filesAffected-only
-            // behavior for the empty case.
-            const newFileCreatorsByPath = (await pathExists(paths.patches))
-                ? collectNewFileCreatorsByPath(await buildPatchQueueContext(paths.patches))
-                : new Map();
-            const rows = buildOwnershipTable(manifest?.patches ?? [], rawFilesOwnership, newFileCreatorsByPath, new Map((await classifyFiles(rawFilesOwnership, paths.engine, paths.patches, config.binaryName, await collectFurnaceManagedPrefixes(projectRoot))).map((entry) => [entry.file, entry.classification])));
-            renderOwnershipTable(rows);
-            const conflictCount = rows.filter((r) => r.conflict).length;
-            const unmanagedCount = rows.filter((r) => r.unmanaged).length;
-            const managedCount = rows.filter((r) => !r.unmanaged).length;
-            const parts = [`${managedCount} managed`];
-            if (conflictCount > 0)
-                parts.push(`${conflictCount} conflict${conflictCount === 1 ? '' : 's'}`);
-            if (unmanagedCount > 0)
-                parts.push(`${unmanagedCount} unmanaged`);
-            outro(parts.join(', '));
-            if (conflictCount > 0) {
-                throw new GeneralError(`${conflictCount} path(s) are claimed by more than one patch. ` +
-                    'Run "fireforge verify" for full details, then use "re-export --files" or ' +
-                    '"patch delete" to resolve.');
-            }
-            return;
-        }
-        // Check if engine exists
+    // On a throw, machine mode deliberately stays ENGAGED: withErrorHandling
+    // routes the styled error to stderr while the mode is on and resets it
+    // centrally (a mid-throw restore here put the refusal on stdout after the
+    // JSON payload, breaking the 0.40.0 stderr promise).
+    await runStatusCommandBody(projectRoot, options);
+    if (isMachineOutputMode() !== previousMachineOutputMode) {
+        setMachineOutputMode(previousMachineOutputMode);
+    }
+}
+/** The status body proper; the machine-mode lifecycle lives in {@link statusCommand}. */
+async function runStatusCommandBody(projectRoot, options) {
+    const modeCount = [
+        options.raw,
+        options.unmanaged,
+        options.ownership,
+        options.testCoverage,
+        options.json,
+    ].filter((v) => v === true).length;
+    if (modeCount > 1) {
+        throw new GeneralError('Cannot use --raw, --unmanaged, --ownership, --test-coverage, and --json together. Pick at most one.');
+    }
+    // --summary elides the files[] payload for gate consumers (FORGE K8);
+    // it only makes sense on the JSON shape.
+    if (options.summary === true && options.json !== true) {
+        throw new InvalidArgumentError('--summary requires --json.', '--summary');
+    }
+    // --include-ownership adds a block to the JSON payload; it is meaningless
+    // on the human views, where --ownership is the mode that renders the
+    // table (FORGE L3).
+    if (options.includeOwnership === true && options.json !== true) {
+        throw new InvalidArgumentError('--include-ownership requires --json. Use --ownership for the human table.', '--include-ownership');
+    }
+    // --check / --fail-on enforcement policy (FORGE G1). Applies only
+    // where classification runs (the default view and --json).
+    const checkPolicy = resolveStatusCheckPolicy(options);
+    if (!options.raw && !options.json) {
+        intro('FireForge Status');
+    }
+    // Test-coverage mode needs only the project root (the baseline lives
+    // in .fireforge/), so it short-circuits before any engine/git guards.
+    if (options.testCoverage) {
+        renderTestCoverageStatus(await readBuildBaseline(projectRoot));
+        return;
+    }
+    const paths = getProjectPaths(projectRoot);
+    const config = await loadConfig(projectRoot);
+    const emitJsonError = (code, message) => {
+        process.stdout.write(JSON.stringify({ schemaVersion: 1, error: message, code }) + '\n');
+        throw new CommandError(ExitCode.GENERAL_ERROR);
+    };
+    // Ownership mode is a flat file→patch table; sources are the manifest's
+    // filesAffected, any worktree drift, and the cross-patch
+    // duplicate-new-file-creation map produced by walking each patch
+    // body. The latter is the alignment fix between `status --ownership`
+    // and `fireforge verify` — see buildOwnershipTable's header comment.
+    // Runs before the default classify path so we can short-circuit
+    // without computing patch-backed state.
+    if (options.ownership) {
         if (!(await pathExists(paths.engine))) {
-            if (options.json) {
-                emitJsonError('engine-missing', 'Firefox source not found. Run "fireforge download" first.');
-            }
             throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
         }
-        // Check if it's a git repository
-        if (!(await isGitRepository(paths.engine))) {
-            if (options.json) {
-                emitJsonError('engine-not-git', 'Engine directory is not a git repository. Run "fireforge download" to initialize.');
-            }
-            throw new GeneralError('Engine directory is not a git repository. Run "fireforge download" to initialize.');
+        const manifest = await loadPatchesManifest(paths.patches);
+        // Same scan and the SAME classification pass as every other mode
+        // (FORGE L3). This branch keeps its historical guard shape on purpose:
+        // no baseline-commit assertion, and a non-git engine degrades to an
+        // empty table rather than the recovery banner.
+        const rawFilesOwnership = await scanEngineStatusFiles(paths.engine, false);
+        const rows = await collectOwnershipRows(paths.patches, manifest?.patches ?? [], rawFilesOwnership, await classifyStatusFiles(rawFilesOwnership, paths, projectRoot, config.binaryName));
+        renderOwnershipTable(rows);
+        const { managed, unmanaged, conflicts } = summarizeOwnership(rows);
+        const parts = [`${managed} managed`];
+        if (conflicts > 0)
+            parts.push(`${conflicts} conflict${conflicts === 1 ? '' : 's'}`);
+        if (unmanaged > 0)
+            parts.push(`${unmanaged} unmanaged`);
+        outro(parts.join(', '));
+        if (conflicts > 0) {
+            throw new GeneralError(`${conflicts} path(s) are claimed by more than one patch. ` +
+                'Run "fireforge verify" for full details, then use "re-export --files" or ' +
+                '"patch delete" to resolve.');
         }
-        await assertEngineHasBaselineCommit(paths.engine, options);
-        const rawFiles = await getStatusWithCodes(paths.engine);
-        const { entries: expanded, truncations } = await expandDirectoryEntries(rawFiles, paths.engine);
-        // Strip atomic-write temp files (Finding #18) before every mode
-        // branch so raw / unmanaged / default / json all agree.
-        const files = filterFireForgeTempFiles(expanded);
-        renderTruncationBanner(truncations);
-        // `--json` callers expect machine-parseable output on every invocation,
-        // including the clean-tree case. Before this ordering fix a clean tree
-        // printed "No modified files" / "Working tree clean" via the human
-        // branch below and `--json` was silently ignored, so scripts that piped
-        // the output through a JSON parser broke precisely when there was
-        // nothing to report. Emit `[]` here and return before the human fallback.
+        return;
+    }
+    // Check if engine exists
+    if (!(await pathExists(paths.engine))) {
         if (options.json) {
-            await renderJsonStatus(files, paths, projectRoot, config.binaryName);
-            return;
-        }
-        // `--raw` consumers parse the native `git status --porcelain` output
-        // directly. On a clean tree the raw mode should produce nothing on
-        // stdout — the human "Working tree clean" banner would contaminate the
-        // pipe. Short-circuit before the human clean-tree branch below.
-        if (options.raw && files.length === 0) {
-            return;
-        }
-        if (files.length === 0) {
-            info('No modified files');
-            outro('Working tree clean');
-            return;
-        }
-        // Raw mode: existing behavior
-        if (options.raw) {
-            renderRawStatus(files);
-            return;
-        }
-        // Patch-aware classification
-        const furnacePrefixes = await collectFurnaceManagedPrefixes(projectRoot);
-        const classified = await classifyFiles(files, paths.engine, paths.patches, config.binaryName, furnacePrefixes);
-        const buckets = {
-            conflict: classified.filter((f) => f.classification === 'conflict'),
-            unmanaged: classified.filter((f) => f.classification === 'unmanaged'),
-            patchOwnedDrift: classified.filter((f) => f.classification === 'patch-owned-drift'),
-            patchBacked: classified.filter((f) => f.classification === 'patch-backed'),
-            branding: classified.filter((f) => f.classification === 'branding'),
-            furnace: classified.filter((f) => f.classification === 'furnace'),
-        };
-        // --unmanaged mode: only show unmanaged
-        if (options.unmanaged) {
-            await renderUnmanagedOnly(buckets.unmanaged, files.length, projectRoot, config.binaryName);
-            return;
+            emitJsonError('engine-missing', 'Firefox source not found. Run "fireforge download" first.');
         }
-        await renderDefaultStatus(files.length, buckets, projectRoot, config.binaryName);
+        throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
     }
-    finally {
-        if (isMachineOutputMode() !== previousMachineOutputMode) {
-            setMachineOutputMode(previousMachineOutputMode);
+    // Check if it's a git repository
+    if (!(await isGitRepository(paths.engine))) {
+        if (options.json) {
+            emitJsonError('engine-not-git', 'Engine directory is not a git repository. Run "fireforge download" to initialize.');
         }
+        throw new GeneralError('Engine directory is not a git repository. Run "fireforge download" to initialize.');
+    }
+    await assertEngineHasBaselineCommit(paths.engine, options);
+    const files = await scanEngineStatusFiles(paths.engine, true);
+    // `--json` callers expect machine-parseable output on every invocation,
+    // including the clean-tree case. Before this ordering fix a clean tree
+    // printed "No modified files" / "Working tree clean" via the human
+    // branch below and `--json` was silently ignored, so scripts that piped
+    // the output through a JSON parser broke precisely when there was
+    // nothing to report. Emit `[]` here and return before the human fallback.
+    if (options.json) {
+        const classified = await classifyStatusFiles(files, paths, projectRoot, config.binaryName);
+        await renderJsonMode(classified, files, paths, options, checkPolicy);
+        return;
+    }
+    // `--raw` consumers parse the native `git status --porcelain` output
+    // directly. On a clean tree the raw mode should produce nothing on
+    // stdout — the human "Working tree clean" banner would contaminate the
+    // pipe. Short-circuit before the human clean-tree branch below.
+    if (options.raw && files.length === 0) {
+        return;
+    }
+    if (files.length === 0) {
+        info('No modified files');
+        outro('Working tree clean');
+        return;
+    }
+    // Raw mode: existing behavior
+    if (options.raw) {
+        renderRawStatus(files);
+        return;
+    }
+    // Patch-aware classification
+    const classified = await classifyStatusFiles(files, paths, projectRoot, config.binaryName);
+    const buckets = {
+        conflict: classified.filter((f) => f.classification === 'conflict'),
+        unmanaged: classified.filter((f) => f.classification === 'unmanaged'),
+        patchOwnedDrift: classified.filter((f) => f.classification === 'patch-owned-drift'),
+        patchBacked: classified.filter((f) => f.classification === 'patch-backed'),
+        branding: classified.filter((f) => f.classification === 'branding'),
+        furnace: classified.filter((f) => f.classification === 'furnace'),
+        binaryUnsupported: classified.filter((f) => f.classification === 'binary-unsupported'),
+    };
+    // --unmanaged mode: only show unmanaged
+    if (options.unmanaged) {
+        await renderUnmanagedOnly(buckets.unmanaged, files.length, projectRoot, config.binaryName);
+        return;
     }
+    await renderDefaultStatus(files.length, buckets, projectRoot, config.binaryName);
+    runStatusCheck(classified, checkPolicy);
 }
 /** Registers the status command on the CLI program. */
 export function registerStatus(program, { getProjectRoot, withErrorHandling }) {
@@ -324,6 +340,10 @@ export function registerStatus(program, { getProjectRoot, withErrorHandling }) {
         .option('--ownership', 'Show a flat path → owning patch table (flags files claimed by multiple patches)')
         .option('--test-coverage', 'Show what the last recorded build covers for test packaging (full or scoped paths)')
         .option('--json', 'Output classified file status as JSON')
+        .option('--summary', 'With --json: emit only summary counts (plus offending files when --check/--fail-on is active), omitting the per-file files[] payload')
+        .option('--include-ownership', 'With --json (composes with --summary): append an ownership block (path->owning-patch rows plus managed/unmanaged/conflict counts) to the payload, so one scan serves the classification, ownership, and check views. Does not change exit semantics.')
+        .option('--check', 'Exit non-zero when any unmanaged, patch-owned-drift, or conflict file exists (composes with --json; combine with --fail-on for finer policy)')
+        .option('--fail-on <classifications>', 'Comma-separated classification list that fails --check, replacing the default set (implies --check). Valid: patch-backed, patch-owned-drift, unmanaged, branding, furnace, conflict, binary-unsupported')
         .action(withErrorHandling(async (options) => {
         await statusCommand(getProjectRoot(), options);
     }));

package/dist/src/commands/test-build-phase.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Pre-test build phase for `fireforge test`, split out of `test.ts` (at
+ * the per-file line budget): the incremental protected mach build with
+ * its baseline write, and the FORGE J9 `--build-only` union-build shape.
+ */
+import type { getProjectPaths, loadConfig } from '../core/config.js';
+import type { TestOptions } from '../types/commands/index.js';
+import type { HarnessClassification } from './test-modes.js';
+/**
+ * Runs the pre-test build (or the stale-build gate when no build was
+ * requested). Returns `true` when the run is COMPLETE — the `--build-only`
+ * union-build shape (FORGE J9), which packages every requested path
+ * (mixed harnesses legal, nothing dispatches), prints the per-harness
+ * next steps, and emits the run's single `PASS` verdict.
+ */
+export declare function runTestBuildPhase(projectRoot: string, paths: ReturnType<typeof getProjectPaths>, projectConfig: Awaited<ReturnType<typeof loadConfig>>, harnessRetries: number, options: TestOptions, request: {
+    classification: HarnessClassification;
+    normalizedPaths: string[];
+}): Promise<boolean>;

package/dist/src/commands/test-build-phase.js

@@ -0,0 +1,168 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Pre-test build phase for `fireforge test`, split out of `test.ts` (at
+ * the per-file line budget): the incremental protected mach build with
+ * its baseline write, and the FORGE J9 `--build-only` union-build shape.
+ */
+import { readBuildBaseline, writeBuildBaseline } from '../core/build-baseline.js';
+import { prepareBuildEnvironment } from '../core/build-prepare.js';
+import { checkExtendCoverageAnchor, checkExtendMozconfigAnchor, formatExtendCoverageRefusal, unionTestPackagingCoverage, } from '../core/coverage-extend.js';
+import { runProtectedMachBuild, withBuildLock } from '../core/mach.js';
+import { buildHarnessCrashMessage } from '../core/test-harness-crash.js';
+import { GeneralError, InvalidArgumentError } from '../errors/base.js';
+import { BuildError } from '../errors/build.js';
+import { toError } from '../utils/errors.js';
+import { info, spinner, verbose } from '../utils/logger.js';
+import { reportBuildOnlyCompletion } from './test-modes.js';
+import { enforceStaleBuildGate, enforceStaticComponentsGate } from './test-stale-gate.js';
+import { emitPassVerdict } from './test-verdict.js';
+async function runPreTestBuild(projectRoot, paths, projectConfig, harnessRetries, testPackagingCoverage, extend) {
+    await withBuildLock(projectRoot, async () => {
+        // Pass the previous baseline exactly like `fireforge build` does, so
+        // auto-configure runs under the same conditions on both paths. The
+        // pre-test build must never invalidate more of the objdir than a plain
+        // `mach build faster` would (field incident: a failed pre-test build
+        // was followed by a ~64-minute full rebuild where an incremental one
+        // should have sufficed).
+        const previousBaseline = await readBuildBaseline(projectRoot);
+        const preparation = await prepareBuildEnvironment(projectRoot, paths, projectConfig, {
+            previousBaseline,
+        });
+        // The mozconfig half of the --extend-coverage anchor (FORGE L1) can
+        // only be checked once prepareBuildEnvironment has regenerated
+        // engine/mozconfig — that is the file this build will configure with —
+        // and must still be checked before mach, so a refusal costs no build.
+        if (extend !== undefined) {
+            const mozconfigAnchor = await checkExtendMozconfigAnchor(paths.engine, previousBaseline);
+            if (!mozconfigAnchor.ok) {
+                throw new GeneralError(formatExtendCoverageRefusal(mozconfigAnchor));
+            }
+        }
+        const buildKind = preparation.fullBuildRequired ? 'full' : 'faster';
+        if (preparation.fullBuildRequired) {
+            info('A jar.mn registration changed since the last successful build; escalating this pre-test build to a full mach build so new install-manifest destinations are created.');
+        }
+        const s = spinner(preparation.fullBuildRequired
+            ? 'Running required full build...'
+            : 'Running incremental build...');
+        // The pre-test build routes through the same protected mach dispatch as
+        // `fireforge build` / `build --ui`: in-venv resource-monitor guard plus
+        // the uniform recognized-crash retry budget, with a fresh mach process
+        // (and fresh guard install) per attempt. prepareBuildEnvironment runs
+        // ONCE, outside the retry loop — retries never re-run mach configure.
+        const result = await runProtectedMachBuild(buildKind, paths.engine, {
+            retries: harnessRetries,
+            onRetry: (signature, nextAttempt, maxAttempts) => {
+                s.message(`Pre-test build hit a harness crash (${signature.reason}); ` +
+                    `retrying (attempt ${nextAttempt} of ${maxAttempts})...`);
+            },
+        });
+        if (result.exitCode === 0) {
+            s.stop('Build complete');
+            // Same record, same failure tolerance as `fireforge build` /
+            // `build --ui` (build.ts): a green pre-test build refreshes the
+            // stale-build baseline so a later plain `fireforge test` over the
+            // same files — in any invocation shape — is not refused. A failed
+            // write never fails the run. The coverage claim is scoped to the
+            // requested test paths, since a file-scoped `test --build` only
+            // guarantees packaging for those manifests. The previous baseline is
+            // passed through so a scoped write carries the static-components
+            // anchor forward (a `mach build faster` does not rebake
+            // components.conf into the compiled table).
+            try {
+                // Under --extend-coverage the claim is the UNION of the previous
+                // record and this build's paths, and the static-components anchor
+                // is always carried forward: that union can evaluate to 'full'
+                // while the build behind it was a scoped `mach build faster` that
+                // did not rebake the compiled table.
+                const recordedCoverage = extend !== undefined
+                    ? unionTestPackagingCoverage(previousBaseline?.testPackagingCoverage, extend.requestedPaths)
+                    : testPackagingCoverage;
+                await writeBuildBaseline(projectRoot, paths.engine, projectConfig.binaryName, recordedCoverage, previousBaseline, describeBuildInvocation(extend !== undefined, testPackagingCoverage), preparation.fullBuildRequired
+                    ? 'refresh'
+                    : extend !== undefined
+                        ? 'carry-forward'
+                        : 'auto');
+            }
+            catch (baselineError) {
+                verbose(`Could not persist build baseline: ${toError(baselineError).message}`);
+            }
+            return;
+        }
+        s.error('Pre-test build failed');
+        throw new BuildError(result.crashSignature
+            ? buildHarnessCrashMessage(result.crashSignature, result.attempts, 'mach build faster')
+            : 'Pre-test build failed', preparation.fullBuildRequired ? 'mach build' : 'mach build faster');
+    });
+}
+/**
+ * `--extend-coverage` only means something for a SCOPED build: it unions
+ * this build's paths onto the recorded claim. Without `--build`/
+ * `--build-only` there is no build to extend from, and a path-less build
+ * records `'full'`, which already covers everything — refusing both is more
+ * honest than silently ignoring the flag.
+ */
+function assertExtendCoverageUsage(options, normalizedPaths) {
+    if (options.build !== true && options.buildOnly !== true) {
+        throw new InvalidArgumentError('--extend-coverage requires --build or --build-only: it unions the paths a build packages onto the recorded coverage claim.', '--extend-coverage');
+    }
+    if (normalizedPaths.length === 0) {
+        throw new InvalidArgumentError('--extend-coverage requires explicit test paths: a path-less build records full coverage, which already covers every path.', '--extend-coverage');
+    }
+}
+/** Renders the `recordedBy` invocation string surfaced by `status --test-coverage`. */
+function describeBuildInvocation(extending, coverage) {
+    const extendFlag = extending ? ' --extend-coverage' : '';
+    return coverage === 'full'
+        ? `fireforge test --build${extendFlag}`
+        : `fireforge test --build${extendFlag} ${coverage.join(' ')}`;
+}
+/**
+ * Runs the pre-test build (or the stale-build gate when no build was
+ * requested). Returns `true` when the run is COMPLETE — the `--build-only`
+ * union-build shape (FORGE J9), which packages every requested path
+ * (mixed harnesses legal, nothing dispatches), prints the per-harness
+ * next steps, and emits the run's single `PASS` verdict.
+ */
+export async function runTestBuildPhase(projectRoot, paths, projectConfig, harnessRetries, options, request) {
+    const { classification, normalizedPaths } = request;
+    const extending = options.extendCoverage === true;
+    if (extending) {
+        assertExtendCoverageUsage(options, normalizedPaths);
+    }
+    if (options.build || options.buildOnly) {
+        // A path-less `test --build` runs (and packages for) the full suite;
+        // a scoped invocation only vouches for the requested paths. A SCOPED
+        // rebuild also cannot regenerate the compiled StaticComponents table,
+        // so it runs the components.conf gate up-front (the path-less shape
+        // refreshes the anchor itself and skips it).
+        const coverage = normalizedPaths.length === 0 ? 'full' : normalizedPaths;
+        if (normalizedPaths.length > 0) {
+            const previousBaseline = await readBuildBaseline(projectRoot);
+            await enforceStaticComponentsGate(paths.engine, previousBaseline, options);
+            if (extending) {
+                // Head/fingerprint half of the anchor, before the build lock: a
+                // refusal here costs neither build time nor the lock.
+                const anchor = await checkExtendCoverageAnchor(paths.engine, previousBaseline);
+                if (!anchor.ok) {
+                    throw new GeneralError(formatExtendCoverageRefusal(anchor));
+                }
+            }
+        }
+        await runPreTestBuild(projectRoot, paths, projectConfig, harnessRetries, coverage, extending ? { requestedPaths: normalizedPaths } : undefined);
+        info('');
+        if (options.buildOnly) {
+            // Union build for mixed harnesses (FORGE J9): the coverage claim
+            // above lists every requested path, so each harness half can run
+            // build-less against this packaging. Nothing dispatches here; the
+            // run still ends with exactly one verdict line.
+            reportBuildOnlyCompletion(classification, normalizedPaths);
+            emitPassVerdict();
+            return true;
+        }
+    }
+    else {
+        await enforceStaleBuildGate(projectRoot, paths.engine, options, normalizedPaths);
+    }
+    return false;
+}