@hominis/fireforge 0.38.0 → 0.39.0

package/dist/src/commands/patch/move-files-into.js

@@ -0,0 +1,245 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Transactional file-ownership move into an EXISTING patch (FORGE F4).
+ *
+ * Before 0.39.0, `patch move-files <from> <to>` with an existing target was
+ * preview-only: it printed two `re-export --files` commands whose real
+ * execution cost three further refusals (`--allow-shrink`, `--yes`, and a
+ * projected `duplicate-new-file-creation` unless the SHRINK landed first —
+ * while the printed plan listed the grow first). This module performs the
+ * same shrink→grow as one transaction under the patch-directory lock with
+ * rollback, mirroring `patch split` / `move-files --create`.
+ *
+ * Preconditions match `re-export`: the engine worktree must currently
+ * reflect both patches' content, because both bodies are regenerated from
+ * the worktree.
+ */
+import { join } from 'node:path';
+import { appendHistory, confirmDestructive } from '../../core/destructive.js';
+import { computeProjectedLintRegressions } from '../../core/lint-projection.js';
+import { normalizePatchArtifact } from '../../core/patch-artifact-normalize.js';
+import { buildModifiedFileAdditionsFromDiff, buildPatchQueueContext, collectForwardImportEdges, detectNewFilesInDiff, lintPatchQueue, } from '../../core/patch-lint.js';
+import { withPatchDirectoryLock } from '../../core/patch-lock.js';
+import { loadPatchesManifest, savePatchesManifest, validatePatchesManifest, } from '../../core/patch-manifest.js';
+import { extractNewFileContentFromDiff } from '../../core/patch-transform.js';
+import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
+import { toError } from '../../utils/errors.js';
+import { readText, writeText } from '../../utils/fs.js';
+import { info, outro, success, warn } from '../../utils/logger.js';
+import { runPatchLint } from '../export-shared.js';
+import { buildSplitDiff, findOwnerRewriteHolders, mergeStagedForwardImports, rewriteSplitOwners, } from './split-plan.js';
+function projectEntryBody(diff) {
+    const newFiles = new Map();
+    for (const path of detectNewFilesInDiff(diff)) {
+        newFiles.set(path, extractNewFileContentFromDiff(diff, path));
+    }
+    return { diff, newFiles, modifiedFileAdditions: buildModifiedFileAdditionsFromDiff(diff) };
+}
+/**
+ * Projects the post-move queue through cross-patch lint, auto-declaring the
+ * forward edges the move introduces into the target (an importer that used
+ * to live in the same patch as the moved file gains a forward edge when the
+ * target is later-ordered). Reports only regressions the move itself adds.
+ */
+async function runProjectedMoveLint(patchesDir, plan) {
+    const movedSet = new Set(plan.movedFiles);
+    const baseCtx = await buildPatchQueueContext(patchesDir);
+    const entries = baseCtx.entries.map((entry) => {
+        let metadata = entry.metadata;
+        if (metadata) {
+            metadata = rewriteSplitOwners(metadata, plan.source.filename, movedSet, plan.target.filename);
+        }
+        if (entry.filename === plan.source.filename) {
+            return { ...entry, metadata, ...projectEntryBody(plan.sourceDiff) };
+        }
+        if (entry.filename === plan.target.filename) {
+            return { ...entry, metadata, ...projectEntryBody(plan.targetDiff) };
+        }
+        return { ...entry, metadata };
+    });
+    const stagedDependencyAdditions = new Map();
+    for (const edge of collectForwardImportEdges({ entries })) {
+        if (edge.owner !== plan.target.filename || !movedSet.has(edge.creates))
+            continue;
+        const decl = {
+            file: edge.sitePath,
+            specifier: edge.specifier,
+            creates: edge.creates,
+            owner: plan.target.filename,
+        };
+        const list = stagedDependencyAdditions.get(edge.entry) ?? [];
+        if (!list.some((d) => d.file === decl.file && d.specifier === decl.specifier && d.creates === decl.creates)) {
+            list.push(decl);
+        }
+        stagedDependencyAdditions.set(edge.entry, list);
+    }
+    for (const entry of entries) {
+        const decls = stagedDependencyAdditions.get(entry.filename);
+        if (decls?.length && entry.metadata) {
+            entry.metadata = mergeStagedForwardImports(entry.metadata, decls);
+        }
+    }
+    const baselineIssues = lintPatchQueue(baseCtx).filter((i) => i.severity === 'error');
+    const projectedIssues = lintPatchQueue({
+        entries,
+        ...(baseCtx.patchPolicy ? { patchPolicy: baseCtx.patchPolicy } : {}),
+    }).filter((i) => i.severity === 'error');
+    const regressions = computeProjectedLintRegressions(baselineIssues, projectedIssues);
+    if (baselineIssues.length > 0 && regressions.length === 0) {
+        warn(`Note: projected queue still has ${baselineIssues.length} pre-existing cross-patch ` +
+            'error(s) unrelated to this move. Run "fireforge verify" to list them.');
+    }
+    const conflicts = regressions.length === 0
+        ? null
+        : {
+            reason: `move would introduce ${regressions.length} cross-patch lint error(s)`,
+            details: regressions.map((i) => `[${i.check}] ${i.file}: ${i.message}`),
+        };
+    return { conflicts, stagedDependencyAdditions };
+}
+/**
+ * Commits a confirmed move under the patch-directory lock: write both
+ * rewritten bodies, then one manifest rewrite (filesAffected on both rows +
+ * owner rewrites + auto-declared forward imports). Rolled back in reverse
+ * order on any failure.
+ */
+async function commitMoveInto(patchesDir, plan) {
+    await withPatchDirectoryLock(patchesDir, async () => {
+        const manifest = await loadPatchesManifest(patchesDir);
+        if (!manifest)
+            throw new GeneralError('Manifest disappeared while waiting for lock.');
+        const currentSource = manifest.patches.find((p) => p.filename === plan.source.filename);
+        const currentTarget = manifest.patches.find((p) => p.filename === plan.target.filename);
+        if (!currentSource ||
+            !currentTarget ||
+            currentSource.filesAffected.join('\n') !== plan.source.filesAffected.join('\n') ||
+            currentTarget.filesAffected.join('\n') !== plan.target.filesAffected.join('\n')) {
+            throw new InvalidArgumentError('Patch queue changed while waiting for move confirmation. Re-run the command.', 'patch move-files');
+        }
+        const movedSet = new Set(plan.movedFiles);
+        const sourcePath = join(patchesDir, plan.source.filename);
+        const targetPath = join(patchesDir, plan.target.filename);
+        const originalSourceBody = await readText(sourcePath);
+        const originalTargetBody = await readText(targetPath);
+        let sourceWritten = false;
+        let targetWritten = false;
+        try {
+            await writeText(sourcePath, normalizePatchArtifact(plan.sourceDiff));
+            sourceWritten = true;
+            await writeText(targetPath, normalizePatchArtifact(plan.targetDiff));
+            targetWritten = true;
+            const updatedPatches = manifest.patches.map((patch) => {
+                let updated = rewriteSplitOwners(patch, plan.source.filename, movedSet, plan.target.filename);
+                const decls = plan.stagedDependencyAdditions.get(updated.filename);
+                if (decls?.length)
+                    updated = mergeStagedForwardImports(updated, decls);
+                if (updated.filename === plan.source.filename) {
+                    return { ...updated, filesAffected: plan.sourceAfter };
+                }
+                if (updated.filename === plan.target.filename) {
+                    return { ...updated, filesAffected: plan.targetAfter };
+                }
+                return updated;
+            });
+            const updated = validatePatchesManifest({ ...manifest, patches: updatedPatches });
+            await savePatchesManifest(patchesDir, updated);
+            try {
+                await appendHistory(patchesDir, {
+                    operation: 'patch-move-files',
+                    args: {
+                        source: plan.source.filename,
+                        target: plan.target.filename,
+                        files: plan.movedFiles,
+                        ownerRewrites: plan.ownerRewrites,
+                    },
+                    result: 'ok',
+                });
+            }
+            catch (historyError) {
+                warn(`History log append failed after patch move-files committed: ${toError(historyError).message}`);
+            }
+        }
+        catch (error) {
+            if (targetWritten) {
+                try {
+                    await writeText(targetPath, originalTargetBody);
+                }
+                catch (rollbackError) {
+                    warn(`Rollback warning: could not restore target body: ${toError(rollbackError).message}`);
+                }
+            }
+            if (sourceWritten) {
+                try {
+                    await writeText(sourcePath, originalSourceBody);
+                }
+                catch (rollbackError) {
+                    warn(`Rollback warning: could not restore source body: ${toError(rollbackError).message}`);
+                }
+            }
+            try {
+                await savePatchesManifest(patchesDir, manifest);
+            }
+            catch (rollbackError) {
+                warn(`Rollback warning: could not restore manifest: ${toError(rollbackError).message}`);
+            }
+            throw error;
+        }
+    });
+}
+/**
+ * Plans, lints, confirms, and commits a file-ownership move into an
+ * existing patch. Called by `patchMoveFilesCommand` after its ownership
+ * pre-checks resolved and validated both patches.
+ */
+export async function runMoveFilesInto(args) {
+    const { enginePath, patchesDir, source, target, files, sourceAfter, targetAfter, options } = args;
+    const sourceDiff = await buildSplitDiff(enginePath, sourceAfter, 'remaining', source.filename);
+    const targetDiff = await buildSplitDiff(enginePath, targetAfter, 'moved', target.filename);
+    // Per-patch lint both projected bodies with each patch's own waivers.
+    await runPatchLint(enginePath, sourceAfter, sourceDiff, args.config, options.skipLint, undefined, source.lintIgnore ? new Set(source.lintIgnore) : undefined, source.tier);
+    await runPatchLint(enginePath, targetAfter, targetDiff, args.config, options.skipLint, undefined, target.lintIgnore ? new Set(target.lintIgnore) : undefined, target.tier);
+    const manifest = await loadPatchesManifest(patchesDir);
+    const plan = {
+        source,
+        target,
+        movedFiles: files,
+        sourceAfter,
+        targetAfter,
+        sourceDiff,
+        targetDiff,
+        ownerRewrites: findOwnerRewriteHolders(manifest?.patches ?? [], source.filename, new Set(files)),
+        stagedDependencyAdditions: new Map(),
+    };
+    const { conflicts, stagedDependencyAdditions } = await runProjectedMoveLint(patchesDir, plan);
+    plan.stagedDependencyAdditions = stagedDependencyAdditions;
+    const decision = await confirmDestructive({
+        operation: 'patch-move-files',
+        title: `Move ${files.length} file(s) from ${source.filename} to ${target.filename}`,
+        summary: [
+            `moved files (${files.length}): ${files.join(', ')}`,
+            `${source.filename} keeps (${sourceAfter.length}): ${sourceAfter.join(', ')}`,
+            `${target.filename} grows to (${targetAfter.length}): ${targetAfter.join(', ')}`,
+            ...(plan.ownerRewrites.length > 0
+                ? [`staged-dependency owners re-pointed in: ${plan.ownerRewrites.join(', ')}`]
+                : []),
+        ],
+        yes: options.yes === true,
+        dryRun: options.dryRun === true,
+        unsafeOverride: options.forceUnsafe === true,
+        conflicts,
+    });
+    if (decision === 'dry-run') {
+        outro('Dry run complete — no changes made');
+        return;
+    }
+    if (decision === 'cancelled') {
+        outro('Move cancelled');
+        return;
+    }
+    await commitMoveInto(patchesDir, plan);
+    success(`Moved ${files.length} file(s) from ${source.filename} to ${target.filename}`);
+    if (plan.ownerRewrites.length > 0) {
+        info(`Re-pointed staged-dependency owners in: ${plan.ownerRewrites.join(', ')}`);
+    }
+    outro('Move complete');
+}

package/dist/src/commands/patch/move-files.js

@@ -7,14 +7,15 @@
  */
 import { relative } from 'node:path';
 import { Command } from 'commander';
-import { getProjectPaths } from '../../core/config.js';
+import { getProjectPaths, loadConfig } from '../../core/config.js';
 import { formatPatchNotFoundError } from '../../core/patch-identifier-suggest.js';
 import { loadPatchesManifest, resolvePatchIdentifier } from '../../core/patch-manifest.js';
 import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
 import { pathExists } from '../../utils/fs.js';
-import { info, intro, note, outro, warn } from '../../utils/logger.js';
+import { info, intro, note, warn } from '../../utils/logger.js';
 import { commanderArgParser, pickDefined } from '../../utils/options.js';
 import { patchMoveFilesCreateCommand } from './move-files-create.js';
+import { runMoveFilesInto } from './move-files-into.js';
 function collectOption(value, previous) {
     previous.push(value);
     return previous;
@@ -123,21 +124,34 @@ export async function patchMoveFilesCommand(projectRoot, fromIdentifier, toIdent
         }
     }
     const relativePatchesDir = relative(projectRoot, paths.patches) || 'patches';
-    info(`Planning ownership move in ${relativePatchesDir}/patches.json.`);
+    info(`Moving ownership in ${relativePatchesDir}/patches.json.`);
     info(`Move ${files.length} file(s) from ${source.filename} to ${target.filename}:`);
     note(formatFiles(files), 'Files');
     note(formatFiles(sourceAfter), `${source.filename} files after move`);
     note(formatFiles(targetAfter), `${target.filename} files after move`);
-    const dryRunSource = formatReExportCommand(source.filename, sourceAfter, ['--dry-run']);
-    const dryRunTarget = formatReExportCommand(target.filename, targetAfter, ['--dry-run']);
-    const applySource = formatReExportCommand(source.filename, sourceAfter, ['--yes']);
-    const applyTarget = formatReExportCommand(target.filename, targetAfter, []);
-    note(`${dryRunSource}\n${dryRunTarget}`, 'Preview commands');
-    note(`${applySource}\n${applyTarget}`, 'Apply commands');
-    info('Tip: to move files into a brand-new patch in one transaction (including ' +
-        'staged-dependency owner rewrites), re-run with --create --order <n> to create ' +
-        'the target patch and move the files in one step, or use "fireforge patch split".');
-    outro('Move plan complete - no changes made');
+    // Manual fallback (e.g. when the worktree cannot carry both patches'
+    // content right now): the equivalent re-export choreography, in
+    // EXECUTABLE order — the shrink must land before the grow, or the
+    // projected cross-patch lint refuses the pair with
+    // duplicate-new-file-creation (FORGE F4).
+    const applySource = formatReExportCommand(source.filename, sourceAfter, [
+        '--allow-shrink',
+        '--yes',
+    ]);
+    const applyTarget = formatReExportCommand(target.filename, targetAfter, ['--yes']);
+    note(`1. ${applySource}\n2. ${applyTarget}\n(the shrink must land first)`, 'Equivalent manual commands');
+    const config = await loadConfig(projectRoot);
+    await runMoveFilesInto({
+        enginePath: paths.engine,
+        patchesDir: paths.patches,
+        source,
+        target,
+        files,
+        sourceAfter,
+        targetAfter,
+        options,
+        config,
+    });
 }
 /**
  * Registers the preview-only `patch move-files` subcommand.

package/dist/src/commands/patch/rename.js

@@ -173,7 +173,10 @@ export async function patchRenameCommand(projectRoot, identifier, options = {})
     const nameChanging = options.to !== target.name;
     const descriptionChanging = options.description !== undefined && options.description !== target.description;
     if (!filenameChanging && !nameChanging && !descriptionChanging) {
-        info(`${target.filename}: name and description already match — nothing to change.`);
+        info(`${target.filename}: nothing to change — filename already "${target.filename}" ` +
+            `(slug of "${options.to}" is "${newSlug}"), name already "${target.name}"` +
+            (options.description !== undefined ? ', description already matches' : '') +
+            '.');
         outro(isDryRun ? 'Dry run complete — no changes made' : 'Patch rename (no-op)');
         return;
     }

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/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,7 @@ 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 { renderDefaultStatus, renderTestCoverageStatus, renderUnmanagedOnly, } from './status-output.js';
 /**
  * Renders raw worktree status as machine-parseable porcelain-style output.
  * Each line is: STATUS<tab>FILE
@@ -170,13 +171,25 @@ 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.');
         }
         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) => {
@@ -309,6 +322,7 @@ 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')
         .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 {};

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,11 @@
  * 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 { 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;
@@ -78,7 +79,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);