@hominis/fireforge 0.38.0 → 0.40.0

package/dist/src/commands/re-export-options.js

@@ -77,6 +77,9 @@ export function validateReExportOptionCombinations(patches, options) {
             throw new InvalidArgumentError('--scan-files selects patches from its manifest and cannot be combined with positional patches or --all.', '--scan-files');
         }
     }
+    if (options.refuseAdjacentUnmanaged === true && (options.scan || options.files !== undefined)) {
+        throw new InvalidArgumentError('--refuse-adjacent-unmanaged applies to the scan-less path only and cannot be combined with --scan or --files (those set filesAffected explicitly).', '--refuse-adjacent-unmanaged');
+    }
     const usingTierFlag = options.tier !== undefined;
     const usingLintIgnoreFlag = options.lintIgnore !== undefined && options.lintIgnore.length > 0;
     if (options.all && (usingTierFlag || usingLintIgnoreFlag)) {

package/dist/src/commands/re-export.js

@@ -1,81 +1,52 @@
 // SPDX-License-Identifier: EUPL-1.2
 /* eslint-disable max-lines -- Re-export is at the guardrail; splitting register plumbing is unrelated to this fix. */
-import { dirname, join } from 'node:path';
 import { multiselect } from '@clack/prompts';
 import { Command, Option } from 'commander';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { withEngineSessionLock } from '../core/engine-session-lock.js';
+import { collectFurnaceManagedPrefixes } from '../core/furnace-config.js';
 import { enforceFreshFurnaceSources } from '../core/furnace-stale-export.js';
 import { isGitRepository } from '../core/git.js';
 import { getDiffForFilesAgainstHead } from '../core/git-diff.js';
-import { getModifiedFilesInDir, getUntrackedFilesInDir } from '../core/git-status.js';
 import { updatePatchAndMetadata } from '../core/patch-export.js';
 import { buildPatchQueueContext } from '../core/patch-lint.js';
-import { getClaimedFiles, loadPatchesManifest, resolvePatchIdentifier, stampPatchVersions, } from '../core/patch-manifest.js';
+import { loadPatchesManifest, resolvePatchIdentifier, stampPatchVersions, } from '../core/patch-manifest.js';
 import { buildProjectedManifest, enforcePatchPolicy } from '../core/patch-policy.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
+import { isGitIndexLockConflict } from '../errors/git.js';
 import { elapsedSince } from '../utils/elapsed.js';
 import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { cancel, info, intro, isCancel, outro, spinner, success, warn } from '../utils/logger.js';
 import { addWaitLockOption, pickDefined, resolveWaitLockSeconds } from '../utils/options.js';
 import { runPatchLint } from './export-shared.js';
+import { findMissingFiles, reportAdjacentUnmanagedFiles } from './re-export-adjacent.js';
 import { loadScanFilesAssignments, withDryRunReExportLock } from './re-export-bulk-scan.js';
 import { reExportFilesInPlace } from './re-export-files.js';
 import { applyReExportFilesPositionalFolding, validateReExportOptionCombinations, } from './re-export-options.js';
 import { assertScanAdoptionsHaveNoForwardImports, assertScanFileAdditionsHaveDiffHunks, confirmBroadScanAdditions, normalizeScanFiles, scanPatchFilesForReExport, } from './re-export-scan.js';
-async function findMissingFiles(engineDir, files) {
-    const missingFiles = [];
-    for (const file of files) {
-        if (!(await pathExists(join(engineDir, file))))
-            missingFiles.push(file);
+const GIT_INDEX_LOCK_RETRY_MS = 300;
+/**
+ * Retries a single patch re-export exactly once when the failure is
+ * transient git `index.lock` contention (an external git process holding
+ * the engine repo's index). The retry re-enters `reExportSinglePatch`
+ * from the top, so it re-reads clean state; a second lock failure
+ * propagates to the loop's honest "N of M" accounting.
+ */
+async function reExportSinglePatchWithIndexLockRetry(patch, paths, manifest, options, isDryRun, config, adjacentCtx) {
+    try {
+        return await reExportSinglePatch(patch, paths, manifest, options, isDryRun, config, adjacentCtx);
     }
-    return missingFiles;
-}
-async function findLikelyNewSiblingFiles(args) {
-    const { currentFilesAffected, engineDir, manifest, patchFilename } = args;
-    const parentDirs = [...new Set(currentFilesAffected.map((file) => dirname(file)))];
-    const currentSet = new Set(currentFilesAffected);
-    const claimedByOthers = getClaimedFiles(manifest, patchFilename);
-    const candidates = new Set();
-    for (const dir of parentDirs) {
-        const [modifiedFiles, untrackedFiles] = await Promise.all([
-            getModifiedFilesInDir(engineDir, dir),
-            getUntrackedFilesInDir(engineDir, dir),
-        ]);
-        for (const file of [...modifiedFiles, ...untrackedFiles]) {
-            if (currentSet.has(file) || claimedByOthers.has(file))
-                continue;
-            candidates.add(file);
+    catch (error) {
+        if (!isGitIndexLockConflict(error)) {
+            throw error;
         }
+        warn(`${patch.filename}: git index.lock contention detected — retrying once after ${String(GIT_INDEX_LOCK_RETRY_MS)} ms...`);
+        await new Promise((resolve) => setTimeout(resolve, GIT_INDEX_LOCK_RETRY_MS));
+        return await reExportSinglePatch(patch, paths, manifest, options, isDryRun, config, adjacentCtx);
     }
-    return [...candidates].sort();
 }
-async function warnPlainReExportFileDrift(args) {
-    const { patch, paths, manifest, currentFilesAffected } = args;
-    const missingFiles = await findMissingFiles(paths.engine, currentFilesAffected);
-    if (missingFiles.length > 0) {
-        warn(`${patch.filename}: some files in patches.json no longer exist on disk ` +
-            `(${missingFiles.join(', ')}). Without --scan, re-export keeps the manifest's ` +
-            `filesAffected unchanged and the missing entries will be preserved — ` +
-            `\`fireforge verify\` may flag manifest inconsistency after this run.\n` +
-            `  Re-run with --scan to reconcile filesAffected with the current worktree, ` +
-            `or pass --files <paths> to set the list explicitly.`);
-    }
-    const likelyNewFiles = await findLikelyNewSiblingFiles({
-        currentFilesAffected,
-        engineDir: paths.engine,
-        manifest,
-        patchFilename: patch.filename,
-    });
-    if (likelyNewFiles.length === 0)
-        return;
-    warn(`${patch.filename}: found ${likelyNewFiles.length} unowned changed sibling file${likelyNewFiles.length === 1 ? '' : 's'} near this patch. Plain re-export keeps filesAffected unchanged; add reviewed files explicitly with --scan-file.`);
-    for (const file of likelyNewFiles) {
-        info(`  ${file} — fireforge re-export ${patch.filename} --scan --scan-file ${file}`);
-    }
-}
-async function reExportSinglePatch(patch, paths, manifest, options, isDryRun, config) {
+async function reExportSinglePatch(patch, paths, manifest, options, isDryRun, config, adjacentCtx) {
     let currentFilesAffected = [...patch.filesAffected];
     // --- Scan for new/removed files ---
     if (options.scan) {
@@ -123,7 +94,9 @@ async function reExportSinglePatch(patch, paths, manifest, options, isDryRun, co
         // warning up-front when we can detect the drift cheaply, so the
         // operator has a chance to re-run with `--scan` or `--files`
         // before the stale filesAffected lands in patches.json.
-        await warnPlainReExportFileDrift({ patch, paths, manifest, currentFilesAffected });
+        const args = { patch, paths, manifest, currentFilesAffected, ctx: adjacentCtx };
+        if (await reportAdjacentUnmanagedFiles(args))
+            return false;
     }
     // --- Explicit file-subset path ---
     // When --files is given, the target filesAffected is authoritative — drop
@@ -359,6 +332,14 @@ export async function reExportCommand(projectRoot, patches, options) {
         return;
     }
     const config = await loadConfig(projectRoot);
+    // Classification inputs for the scan-less adjacency advisory, computed
+    // once for the whole run (FORGE G2).
+    const adjacentCtx = {
+        binaryName: config.binaryName,
+        furnacePrefixes: await collectFurnaceManagedPrefixes(paths.root),
+        refuseAdjacentUnmanaged: options.refuseAdjacentUnmanaged === true,
+        refusals: [],
+    };
     let reExported = 0;
     const reExportedFilenames = [];
     const progress = spinner('Preparing re-export...');
@@ -369,7 +350,7 @@ export async function reExportCommand(projectRoot, patches, options) {
             const patchOptions = assignedScanFiles !== undefined ? { ...options, scanFiles: assignedScanFiles } : options;
             progress.message(`Re-exporting ${index + 1}/${selectedPatches.length}: ${patch.filename} (${patch.filesAffected.length} file(s), ${elapsedSince(startedAt)} elapsed)...`);
             try {
-                const exported = await reExportSinglePatch(patch, paths, manifest, patchOptions, isDryRun, config);
+                const exported = await reExportSinglePatchWithIndexLockRetry(patch, paths, manifest, patchOptions, isDryRun, config, adjacentCtx);
                 if (exported) {
                     reExported++;
                     reExportedFilenames.push(patch.filename);
@@ -381,6 +362,13 @@ export async function reExportCommand(projectRoot, patches, options) {
             }
         }
     });
+    if (adjacentCtx.refusals.length > 0) {
+        progress.error('Re-export refused');
+        const names = adjacentCtx.refusals.map((r) => r.patchFilename).join(', ');
+        throw new GeneralError(`Refused ${String(adjacentCtx.refusals.length)} patch(es) with adjacent unmanaged files ` +
+            `(--refuse-adjacent-unmanaged): ${names}. Adopt reviewed files with --scan --scan-file, ` +
+            `or export them as a new patch.`);
+    }
     if (reExported === 0 && selectedPatches.length > 0) {
         progress.error('Re-export failed');
         throw new GeneralError('All selected patches failed to re-export. Check the errors above.');
@@ -431,6 +419,7 @@ export function registerReExport(program, { getProjectRoot, withErrorHandling })
         .split(',')
         .map((v) => v.trim())
         .filter((v) => v.length > 0))
+        .option('--refuse-adjacent-unmanaged', 'Refuse a scan-less re-export (non-zero exit, patch not written) when unmanaged files exist adjacent to the patch ownership, instead of warning. Mutually exclusive with --scan and --files.')
         .option('--dry-run', 'Show what would change without writing')
         .option('--skip-lint', 'Skip patch lint checks (downgrade errors to warnings)')
         .option('--allow-stale-furnace', 'Export the deployed engine copy even when the components/ source changed since the last furnace apply')

package/dist/src/commands/reset.js

@@ -5,6 +5,7 @@ import { getProjectPaths } from '../core/config.js';
 import { clearAppliedFurnaceState } from '../core/furnace-config.js';
 import { getHead, hasChanges, isGitRepository, isMissingHeadError, resetChanges, } from '../core/git.js';
 import { expandUntrackedDirectoryEntries, getWorkingTreeStatus } from '../core/git-status.js';
+import { warnIfStaticComponentsStale } from '../core/test-stale-check.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { pathExists } from '../utils/fs.js';
 import { cancel, info, intro, isCancel, outro, spinner, warn } from '../utils/logger.js';
@@ -86,6 +87,10 @@ export async function resetCommand(projectRoot, options) {
         // tree, not the engine checkout, so reset must not silently forget them.
         await clearAppliedFurnaceState(projectRoot);
         s.stop('Changes reset');
+        // The reset may have moved components.conf away from what the last full
+        // build compiled in — surface that now instead of at the next test
+        // refusal (FORGE F13).
+        await warnIfStaticComponentsStale(projectRoot, paths.engine);
         outro('Working tree restored to clean state');
     }
     catch (error) {

package/dist/src/commands/run.js

@@ -6,7 +6,7 @@ import { Command } from 'commander';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { warnIfFurnaceStale } from '../core/furnace-staleness.js';
 import { buildArtifactMismatchMessage, hasBuildArtifacts, hasRunnableBundle, run, runMachSmoke, } from '../core/mach.js';
-import { compileAllowlistFromFile, compileAllowlistFromStrings, matchesAllowlist, matchesSmokeError, } from '../core/smoke-patterns.js';
+import { compileAllowlistFromFile, compileAllowlistFromStrings, matchAllowlist, matchesSmokeError, } from '../core/smoke-patterns.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
 import { ExitCode } from '../errors/codes.js';
@@ -186,6 +186,7 @@ async function runSmokeExit(engineDir, options) {
     const findings = [];
     let allowlistedErrorHits = 0;
     let allowlistedTotalHits = 0;
+    const allowlistHits = new Array(allowlist.length).fill(0);
     const handleLine = (stream, line) => {
         // Mirror raw output to the terminal so operators watching the smoke
         // run still see what the browser is printing. Stream selection on the
@@ -201,9 +202,11 @@ async function runSmokeExit(engineDir, options) {
         // total set of allowlisted lines (what the operator sees in the
         // console) and the subset that were error-class (what the smoke
         // exit contract cares about). The exit contract itself is unchanged.
-        const isAllowlisted = allowlist.length > 0 && matchesAllowlist(line, allowlist);
+        const matchIndex = allowlist.length > 0 ? matchAllowlist(line, allowlist) : -1;
+        const isAllowlisted = matchIndex !== -1;
         if (isAllowlisted) {
             allowlistedTotalHits += 1;
+            allowlistHits[matchIndex] = (allowlistHits[matchIndex] ?? 0) + 1;
         }
         if (!matchesSmokeError(line))
             return;
@@ -249,6 +252,8 @@ async function runSmokeExit(engineDir, options) {
         timedOut: result.timedOut,
         allowlistedErrorHits,
         allowlistedTotalHits,
+        allowlist,
+        allowlistHits,
         findings,
         exitCode: result.exitCode,
     });
@@ -314,6 +319,17 @@ function reportSmokeSummary(args) {
     info(`  Allowlisted error hits (suppressed): ${String(args.allowlistedErrorHits)}`);
     info(`  Allowlisted lines total: ${String(args.allowlistedTotalHits)}`);
     info(`  Child exit code:  ${String(args.exitCode)}`);
+    // Per-entry attribution (FORGE G8): first-match credit per line, with
+    // zero-hit entries always visible — an allowlist entry whose suppressed
+    // shape changed upstream is only detectable as a 0× row.
+    if (args.allowlist.length > 0) {
+        info('  Allowlist attribution (first matching entry per line):');
+        args.allowlist.forEach((entry, index) => {
+            const hits = args.allowlistHits[index] ?? 0;
+            const zeroSuffix = hits === 0 ? '  (never matched — candidate for removal)' : '';
+            info(`    ${String(hits)}×  ${entry.origin}  ${entry.source}${zeroSuffix}`);
+        });
+    }
     if (args.findings.length === 0)
         return;
     warn('');

package/dist/src/commands/status-check.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `status --check` enforcement policy (FORGE G1). Turns the classified
+ * status view into a CI-enforceable non-zero exit: the default policy
+ * fails on any classification outside {patch-backed, branding, furnace},
+ * and `--fail-on <class,...>` replaces that set for finer control.
+ *
+ * Helper module consumed by status.ts (which sits at the max-lines
+ * budget); no top-level registrar is exported and none is wanted.
+ */
+import type { ClassifiedFile, FileClassification } from '../core/status-classify.js';
+/** Resolved `--check`/`--fail-on` policy for one status invocation. */
+export interface StatusCheckPolicy {
+    checkEnabled: boolean;
+    failOn: readonly FileClassification[];
+}
+/**
+ * Resolves the enforcement policy from the raw flags: `--fail-on` implies
+ * `--check` and replaces the default set; both are refused alongside the
+ * modes that skip (or elide) classification.
+ */
+export declare function resolveStatusCheckPolicy(options: {
+    check?: boolean;
+    failOn?: string;
+    raw?: boolean;
+    unmanaged?: boolean;
+    ownership?: boolean;
+    testCoverage?: boolean;
+}): StatusCheckPolicy;
+/**
+ * Throws a GeneralError (exit 1) when the policy is enabled and any of
+ * its classifications is non-empty, naming each offending classification
+ * with its first few files. A disabled policy or a fully tool-covered
+ * tree passes silently.
+ */
+export declare function runStatusCheck(classified: readonly ClassifiedFile[], policy: StatusCheckPolicy): void;

package/dist/src/commands/status-check.js

@@ -0,0 +1,88 @@
+import { GeneralError, InvalidArgumentError } from '../errors/base.js';
+const ALL_CLASSIFICATIONS = [
+    'patch-backed',
+    'patch-owned-drift',
+    'unmanaged',
+    'branding',
+    'furnace',
+    'conflict',
+];
+/** Default `--check` policy: everything outside {patch-backed, branding, furnace} fails. */
+const DEFAULT_FAIL_CLASSIFICATIONS = [
+    'unmanaged',
+    'patch-owned-drift',
+    'conflict',
+];
+/**
+ * Resolves the enforcement policy from the raw flags: `--fail-on` implies
+ * `--check` and replaces the default set; both are refused alongside the
+ * modes that skip (or elide) classification.
+ */
+export function resolveStatusCheckPolicy(options) {
+    const failOnList = parseFailOnClassifications(options.failOn);
+    const checkEnabled = options.check === true || failOnList !== undefined;
+    if (checkEnabled &&
+        (options.raw === true ||
+            options.unmanaged === true ||
+            options.ownership === true ||
+            options.testCoverage === true)) {
+        throw new InvalidArgumentError('--check cannot be combined with --raw, --unmanaged, --ownership, or --test-coverage. Use the default view or --json.', '--check');
+    }
+    return { checkEnabled, failOn: failOnList ?? DEFAULT_FAIL_CLASSIFICATIONS };
+}
+function isClassification(value) {
+    return ALL_CLASSIFICATIONS.includes(value);
+}
+/**
+ * Parses a comma-separated `--fail-on` value into a classification list.
+ * Returns undefined when the flag was not given (the caller then applies
+ * the default policy only under `--check`).
+ */
+function parseFailOnClassifications(raw) {
+    if (raw === undefined)
+        return undefined;
+    const parts = raw
+        .split(',')
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0);
+    if (parts.length === 0) {
+        throw new InvalidArgumentError(`--fail-on requires at least one classification. Valid: ${ALL_CLASSIFICATIONS.join(', ')}.`, '--fail-on');
+    }
+    const classifications = [];
+    for (const part of parts) {
+        if (!isClassification(part)) {
+            throw new InvalidArgumentError(`Unknown --fail-on classification "${part}". Valid: ${ALL_CLASSIFICATIONS.join(', ')}.`, '--fail-on');
+        }
+        if (!classifications.includes(part))
+            classifications.push(part);
+    }
+    return classifications;
+}
+const CHECK_FILE_PREVIEW_MAX = 3;
+/**
+ * Throws a GeneralError (exit 1) when the policy is enabled and any of
+ * its classifications is non-empty, naming each offending classification
+ * with its first few files. A disabled policy or a fully tool-covered
+ * tree passes silently.
+ */
+export function runStatusCheck(classified, policy) {
+    if (!policy.checkEnabled)
+        return;
+    const offending = [];
+    for (const classification of policy.failOn) {
+        const files = classified
+            .filter((entry) => entry.classification === classification)
+            .map((entry) => entry.file);
+        if (files.length === 0)
+            continue;
+        const preview = files.slice(0, CHECK_FILE_PREVIEW_MAX).join(', ');
+        const more = files.length > CHECK_FILE_PREVIEW_MAX
+            ? `, +${String(files.length - CHECK_FILE_PREVIEW_MAX)} more`
+            : '';
+        offending.push(`${String(files.length)} ${classification} (${preview}${more})`);
+    }
+    if (offending.length === 0)
+        return;
+    throw new GeneralError(`status --check failed: ${offending.join(', ')}. Export or adopt unmanaged files, ` +
+        `re-export drifted patches, and run "fireforge verify" for conflict details.`);
+}

package/dist/src/commands/status-output.d.ts

@@ -1,3 +1,4 @@
+import type { BuildBaseline } from '../core/build-baseline-types.js';
 import type { ClassifiedFile } from '../core/status-classify.js';
 export interface ClassifiedBuckets {
     conflict: ClassifiedFile[];
@@ -11,3 +12,11 @@ export interface ClassifiedBuckets {
 export declare function renderUnmanagedOnly(unmanagedFiles: ClassifiedFile[], totalModified: number, projectRoot: string, binaryName: string): Promise<void>;
 /** Renders the default classified status buckets. */
 export declare function renderDefaultStatus(totalModified: number, buckets: ClassifiedBuckets, projectRoot: string, binaryName: string): Promise<void>;
+/**
+ * Renders `fireforge status --test-coverage` (FORGE F11): a READ-ONLY view
+ * of the last build baseline's test-packaging coverage. Before this
+ * existed, the only way to learn the recorded coverage scope — which
+ * concurrent sessions sharing one engine tree overwrite constantly — was
+ * to trip the out-of-coverage refusal on a real test run.
+ */
+export declare function renderTestCoverageStatus(baseline: BuildBaseline | undefined): void;

package/dist/src/commands/status-output.js

@@ -1,4 +1,3 @@
-// SPDX-License-Identifier: EUPL-1.2
 import { isFileRegistered, matchesRegistrablePattern } from '../core/manifest-rules.js';
 import { getPrimaryStatusCode } from '../core/status-classify.js';
 import { GeneralError } from '../errors/base.js';
@@ -182,3 +181,36 @@ export async function renderDefaultStatus(totalModified, buckets, projectRoot, b
         .map((section) => `${section.files.length} ${section.label}`);
     outro(parts.join(', '));
 }
+/**
+ * Renders `fireforge status --test-coverage` (FORGE F11): a READ-ONLY view
+ * of the last build baseline's test-packaging coverage. Before this
+ * existed, the only way to learn the recorded coverage scope — which
+ * concurrent sessions sharing one engine tree overwrite constantly — was
+ * to trip the out-of-coverage refusal on a real test run.
+ */
+export function renderTestCoverageStatus(baseline) {
+    if (baseline === undefined) {
+        info('No build baseline recorded (.fireforge/last-build.json missing or unreadable).\n' +
+            'Run "fireforge build" to record one.');
+        outro('No test-packaging coverage recorded');
+        return;
+    }
+    info(`Last build: ${baseline.builtAt}  (binary: ${baseline.binaryName}, ` +
+        `engine HEAD: ${baseline.engineHeadSha || '(unborn)'})`);
+    info(`Recorded by: ${baseline.recordedBy ?? 'unknown'}`);
+    const coverage = baseline.testPackagingCoverage;
+    if (coverage === undefined) {
+        info('Test packaging coverage: full (implicit — baseline predates coverage recording)');
+        outro('Coverage: full');
+        return;
+    }
+    if (coverage === 'full') {
+        info('Test packaging coverage: full');
+        outro('Coverage: full');
+        return;
+    }
+    const list = coverage.map((path) => `  - ${path}`).join('\n');
+    info(`Test packaging coverage: scoped to ${String(coverage.length)} path(s):\n${list}\n` +
+        'A "fireforge test" over paths outside this list will be refused as uncovered.');
+    outro(`Coverage: scoped (${String(coverage.length)} paths)`);
+}

package/dist/src/commands/status.js

@@ -1,5 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { Command } from 'commander';
+import { readBuildBaseline } from '../core/build-baseline.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { collectFurnaceManagedPrefixes } from '../core/furnace-config.js';
 import { getHead, getStatusWithCodes, isGitRepository, isMissingHeadError } from '../core/git.js';
@@ -12,7 +13,8 @@ import { CommandError, GeneralError } 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 { renderDefaultStatus, renderUnmanagedOnly, } from './status-output.js';
+import { resolveStatusCheckPolicy, runStatusCheck } from './status-check.js';
+import { renderDefaultStatus, renderTestCoverageStatus, renderUnmanagedOnly, } from './status-output.js';
 /**
  * Renders raw worktree status as machine-parseable porcelain-style output.
  * Each line is: STATUS<tab>FILE
@@ -85,14 +87,17 @@ 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);
+    return classifyFiles(files, paths.engine, paths.patches, binaryName, furnacePrefixes);
+}
+function renderJsonStatus(classified) {
     const outputFiles = classified.map((f) => {
         const entry = {
             file: f.file,
             status: f.status.trim(),
             classification: f.classification,
+            patch: f.owner ?? null,
         };
         if (f.classification === 'conflict' && f.claimedBy && f.claimedBy.length > 0) {
             entry.claimedBy = [...f.claimedBy];
@@ -170,13 +175,28 @@ export async function statusCommand(projectRoot, options = {}) {
         setMachineOutputMode(true);
     }
     try {
-        const modeCount = [options.raw, options.unmanaged, options.ownership, options.json].filter((v) => v === true).length;
+        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, and --json together. Pick at most one.');
+            throw new GeneralError('Cannot use --raw, --unmanaged, --ownership, --test-coverage, and --json together. Pick at most one.');
         }
+        // --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) => {
@@ -257,7 +277,9 @@ export async function statusCommand(projectRoot, options = {}) {
         // 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) {
-            await renderJsonStatus(files, paths, projectRoot, config.binaryName);
+            const classified = await classifyStatusFiles(files, paths, projectRoot, config.binaryName);
+            renderJsonStatus(classified);
+            runStatusCheck(classified, checkPolicy);
             return;
         }
         // `--raw` consumers parse the native `git status --porcelain` output
@@ -278,8 +300,7 @@ export async function statusCommand(projectRoot, options = {}) {
             return;
         }
         // Patch-aware classification
-        const furnacePrefixes = await collectFurnaceManagedPrefixes(projectRoot);
-        const classified = await classifyFiles(files, paths.engine, paths.patches, config.binaryName, furnacePrefixes);
+        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'),
@@ -294,6 +315,7 @@ export async function statusCommand(projectRoot, options = {}) {
             return;
         }
         await renderDefaultStatus(files.length, buckets, projectRoot, config.binaryName);
+        runStatusCheck(classified, checkPolicy);
     }
     finally {
         if (isMachineOutputMode() !== previousMachineOutputMode) {
@@ -309,7 +331,10 @@ export function registerStatus(program, { getProjectRoot, withErrorHandling }) {
         .option('--raw', 'Show raw worktree status without patch classification')
         .option('--unmanaged', 'Show only unmanaged changes (not covered by patches or tools)')
         .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('--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')
         .action(withErrorHandling(async (options) => {
         await statusCommand(getProjectRoot(), options);
     }));

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

@@ -14,7 +14,7 @@ import type { TestRunOutcome } from './test-run.js';
  * harness problems with their own messages; everything else flows into
  * the regular non-zero-exit diagnosis chain.
  */
-export declare function finalizeSingleRunOutcome(outcome: TestRunOutcome, normalizedPaths: string[], binaryName: string, postRebuildContext: PostRebuildFailureContext | undefined): void;
+export declare function finalizeSingleRunOutcome(outcome: TestRunOutcome, normalizedPaths: string[], binaryName: string, postRebuildContext: PostRebuildFailureContext | undefined, headless?: boolean): void;
 /**
  * Shard-mode adapter over {@link handleNonZeroTestExit}: produces the
  * diagnosis text as a string (to warn per shard) instead of throwing, so

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

@@ -7,11 +7,12 @@
  * `test-harness-crash.ts` for single and sharded invocations. Split out of
  * `test.ts` to keep both files within the per-file line budget.
  */
-import { buildGreenSummaryRejectedMessage, buildHarnessCrashMessage, buildNoTestsRanMessage, } from '../core/test-harness-crash.js';
+import { buildGreenSummaryRejectedMessage, buildHarnessCrashMessage, buildNoTestsRanMessage, headedNoOutputTimeoutHint, } from '../core/test-harness-crash.js';
 import { buildHarnessEarlyExitMessage, classifyHarnessEarlyExit, completePostRebuildFailureContext, prependPostRebuildFailureContext, } from '../core/test-harness-output.js';
 import { GeneralError } from '../errors/base.js';
 import { BuildError } from '../errors/build.js';
 import { info } from '../utils/logger.js';
+import { getPlatform } from '../utils/platform.js';
 function buildUnknownTestMessage(testPaths) {
     return (`mach could not discover the requested test path${testPaths.length === 1 ? '' : 's'}: ${testPaths.join(', ')}\n\n` +
         'The file may exist, but Firefox does not currently resolve it as a runnable test.\n\n' +
@@ -179,9 +180,14 @@ function handleNonZeroTestExit(result, normalizedPaths, appdirInjectionAttempted
  * harness problems with their own messages; everything else flows into
  * the regular non-zero-exit diagnosis chain.
  */
-export function finalizeSingleRunOutcome(outcome, normalizedPaths, binaryName, postRebuildContext) {
+export function finalizeSingleRunOutcome(outcome, normalizedPaths, binaryName, postRebuildContext, headless = false) {
     if (outcome.verdict.kind === 'harness-crash' && outcome.verdict.signature) {
-        throw new GeneralError(buildHarnessCrashMessage(outcome.verdict.signature, outcome.attempts));
+        const base = buildHarnessCrashMessage(outcome.verdict.signature, outcome.attempts);
+        const hint = headedNoOutputTimeoutHint(outcome.verdict.signature, {
+            headless,
+            platform: getPlatform(),
+        });
+        throw new GeneralError(hint ? `${base}\n\n${hint}` : base);
     }
     if (outcome.verdict.kind === 'tests-ran-ok') {
         // The verdict is authoritative over the raw exit code: a completed

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

@@ -12,4 +12,25 @@ export declare function resolveCanaryPath(options: TestOptions, projectConfig: P
 export declare function canaryTimeoutSeconds(projectConfig: ProjectConfig): number;
 /** Emits or throws the one-word canary verdict. */
 export declare function reportCanaryOutcome(outcome: TestRunOutcome): void;
+/** Per-harness bucketing of the requested test paths. */
+export interface HarnessClassification {
+    xpcshell: string[];
+    nonXpcshell: string[];
+}
+/**
+ * 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 declare function classifyBeforeDispatch(engineDir: string, normalizedPaths: string[]): Promise<{
+    classification: HarnessClassification;
+    xpcshellOnly: boolean;
+}>;
 export {};