@hominis/fireforge 0.35.0 → 0.36.0

package/dist/src/commands/status.js

@@ -1,7 +1,9 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { Command } from 'commander';
 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 } from '../core/git-status.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 { loadPatchesManifest } from '../core/patch-manifest.js';
@@ -9,7 +11,7 @@ import { classifyFiles, } from '../core/status-classify.js';
 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, outro, warn } from '../utils/logger.js';
+import { info, intro, isMachineOutputMode, outro, setMachineOutputMode, warn, } from '../utils/logger.js';
 import { renderDefaultStatus, renderUnmanagedOnly, } from './status-output.js';
 /**
  * Renders raw worktree status as machine-parseable porcelain-style output.
@@ -20,19 +22,15 @@ function renderRawStatus(files) {
         process.stdout.write(`${status.trim()}\t${file}\n`);
     }
 }
-const DEFAULT_MAX_UNTRACKED_FILES_PER_DIR = 5000;
-function resolveMaxUntrackedFilesPerDir() {
-    const raw = process.env['FIREFORGE_MAX_UNTRACKED_FILES'];
-    if (raw === undefined || raw.length === 0)
-        return DEFAULT_MAX_UNTRACKED_FILES_PER_DIR;
-    const parsed = Number.parseInt(raw, 10);
-    if (!Number.isFinite(parsed) || parsed <= 0) {
-        warn(`Ignoring FIREFORGE_MAX_UNTRACKED_FILES="${raw}" — expected a positive integer. Falling back to ${DEFAULT_MAX_UNTRACKED_FILES_PER_DIR}.`);
-        return DEFAULT_MAX_UNTRACKED_FILES_PER_DIR;
-    }
-    return parsed;
+// Resolved lazily at first use (shared with core/git-status): this module
+// is imported by the command manifest for EVERY command, so a
+// module-load-time parse printed the status-specific env warning during
+// `fireforge build` etc.
+let maxUntrackedFilesPerDir;
+function getMaxUntrackedFilesPerDir() {
+    maxUntrackedFilesPerDir ??= resolveMaxUntrackedFilesPerDir();
+    return maxUntrackedFilesPerDir;
 }
-const MAX_UNTRACKED_FILES_PER_DIR = resolveMaxUntrackedFilesPerDir();
 function renderTruncationBanner(truncations) {
     if (truncations.length === 0)
         return;
@@ -48,15 +46,17 @@ async function expandDirectoryEntries(files, engineDir) {
     for (const entry of files) {
         if (entry.file.endsWith('/') && entry.status.includes('?')) {
             const individualFiles = await getUntrackedFilesInDir(engineDir, entry.file);
-            if (individualFiles.length > MAX_UNTRACKED_FILES_PER_DIR) {
-                warn(`Untracked directory ${entry.file} contains ${individualFiles.length} files — only the first ${MAX_UNTRACKED_FILES_PER_DIR} will be classified. Consider adding a .gitignore entry.`);
+            const cap = getMaxUntrackedFilesPerDir();
+            if (individualFiles.length > cap) {
+                // Recorded once here, reported once by renderTruncationBanner —
+                // the previous per-directory warn duplicated the banner's content.
                 truncations.push({
                     dir: entry.file,
                     total: individualFiles.length,
-                    shown: MAX_UNTRACKED_FILES_PER_DIR,
+                    shown: cap,
                 });
             }
-            const limited = individualFiles.slice(0, MAX_UNTRACKED_FILES_PER_DIR);
+            const limited = individualFiles.slice(0, cap);
             for (const f of limited) {
                 expanded.push({ status: '??', file: f });
             }
@@ -161,130 +161,145 @@ async function assertEngineHasBaselineCommit(engineDir, options) {
  * @param options - Status display options
  */
 export async function statusCommand(projectRoot, options = {}) {
-    const modeCount = [options.raw, options.unmanaged, options.ownership, 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.');
-    }
-    if (!options.raw && !options.json) {
-        intro('FireForge Status');
+    const previousMachineOutputMode = isMachineOutputMode();
+    const shouldUseMachineOutput = options.json === true || options.raw === true;
+    // Machine modes own stdout exclusively: every diagnostic (clack warnings,
+    // withErrorHandling's styled errors, spinner steps) routes to stderr so
+    // `status --json | jq .` and `--raw` pipes always parse.
+    if (shouldUseMachineOutput) {
+        setMachineOutputMode(true);
     }
-    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) {
+    try {
+        const modeCount = [options.raw, options.unmanaged, options.ownership, 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.');
+        }
+        if (!options.raw && !options.json) {
+            intro('FireForge Status');
+        }
+        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
         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.');
         }
-        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.');
+        // 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.');
         }
-        return;
-    }
-    // Check if engine exists
-    if (!(await pathExists(paths.engine))) {
+        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.
         if (options.json) {
-            emitJsonError('engine-missing', 'Firefox source not found. Run "fireforge download" first.');
+            await renderJsonStatus(files, paths, projectRoot, config.binaryName);
+            return;
         }
-        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.');
+        // `--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;
         }
-        throw new GeneralError('Engine directory is not a git repository. Run "fireforge download" to initialize.');
-    }
-    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.
-    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;
+        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;
+        }
+        await renderDefaultStatus(files.length, buckets, projectRoot, config.binaryName);
     }
-    // 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;
+    finally {
+        if (isMachineOutputMode() !== previousMachineOutputMode) {
+            setMachineOutputMode(previousMachineOutputMode);
+        }
     }
-    await renderDefaultStatus(files.length, buckets, projectRoot, config.binaryName);
 }
 /** Registers the status command on the CLI program. */
 export function registerStatus(program, { getProjectRoot, withErrorHandling }) {
@@ -299,4 +314,3 @@ export function registerStatus(program, { getProjectRoot, withErrorHandling }) {
         await statusCommand(getProjectRoot(), options);
     }));
 }
-//# sourceMappingURL=status.js.map

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

@@ -27,4 +27,3 @@ export async function maybeInjectAppdirArg(engineDir, normalizedPaths, objDir, e
             return true;
     }
 }
-//# sourceMappingURL=test-appdir.js.map

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

@@ -7,7 +7,7 @@
  * `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 { buildHarnessCrashMessage, buildNoTestsRanMessage } from '../core/test-harness-crash.js';
+import { buildGreenSummaryRejectedMessage, buildHarnessCrashMessage, buildNoTestsRanMessage, } 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';
@@ -200,6 +200,20 @@ export function finalizeSingleRunOutcome(outcome, normalizedPaths, binaryName, p
         // zero TEST-START lines must fail, not pass.
         throw new GeneralError(buildNoTestsRanMessage(0, normalizedPaths));
     }
+    // A green-LOOKING summary rejected on crash/truncation evidence gets its
+    // own explanation instead of the generic exit-code message — the operator
+    // must see WHY the green counts were not trusted (0.35.0 green-wash
+    // field report: SIGSEGV at file 2 of 8, `Passed: 2 / Failed: 0`).
+    if (outcome.verdict.greenSummaryRejected) {
+        throw new GeneralError(buildGreenSummaryRejectedMessage(outcome.verdict.greenSummaryRejected, outcome.result.exitCode));
+    }
+    if (outcome.verdict.realFailureLine !== undefined) {
+        info(`First real test failure: ${outcome.verdict.realFailureLine}`);
+        if (outcome.verdict.secondaryHarnessSignature !== undefined) {
+            info(`Secondary harness noise also present: ${outcome.verdict.secondaryHarnessSignature.reason}; ` +
+                outcome.verdict.secondaryHarnessSignature.line);
+        }
+    }
     handleNonZeroTestExit(outcome.result, normalizedPaths, outcome.appdirInjectionAttempted, binaryName, postRebuildContext);
 }
 /**
@@ -211,6 +225,9 @@ export function diagnoseShardOutcome(outcome, path, binaryName, postRebuildConte
     if (outcome.verdict.kind === 'no-tests' && outcome.result.exitCode === 0) {
         return buildNoTestsRanMessage(0, [path]);
     }
+    if (outcome.verdict.greenSummaryRejected) {
+        return buildGreenSummaryRejectedMessage(outcome.verdict.greenSummaryRejected, outcome.result.exitCode);
+    }
     try {
         handleNonZeroTestExit(outcome.result, [path], outcome.appdirInjectionAttempted, binaryName, postRebuildContext);
         return undefined;
@@ -219,4 +236,3 @@ export function diagnoseShardOutcome(outcome, path, binaryName, postRebuildConte
         return error instanceof Error ? error.message : String(error);
     }
 }
-//# sourceMappingURL=test-diagnose.js.map

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

@@ -0,0 +1,15 @@
+import { loadConfig } from '../core/config.js';
+import type { TestOptions } from '../types/commands/index.js';
+import type { TestRunOutcome } from './test-run.js';
+type ProjectConfig = Awaited<ReturnType<typeof loadConfig>>;
+/** Rejects pathless `fireforge test` unless the operator selected a pathless mode. */
+export declare function assertPathlessTestMode(testPaths: readonly string[], options: TestOptions): void;
+/** Rejects invalid combinations for mode-like `fireforge test` options. */
+export declare function assertTestModeCombinations(testPaths: readonly string[], options: TestOptions, canaryPath: string | undefined): void;
+/** Resolves the canary path from CLI or config. */
+export declare function resolveCanaryPath(options: TestOptions, projectConfig: ProjectConfig): string | undefined;
+/** Returns the configured canary no-output budget, defaulting to 60 seconds. */
+export declare function canaryTimeoutSeconds(projectConfig: ProjectConfig): number;
+/** Emits or throws the one-word canary verdict. */
+export declare function reportCanaryOutcome(outcome: TestRunOutcome): void;
+export {};

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

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { loadConfig } from '../core/config.js';
+import { GeneralError } from '../errors/base.js';
+import { success } from '../utils/logger.js';
+/** Rejects pathless `fireforge test` unless the operator selected a pathless mode. */
+export function assertPathlessTestMode(testPaths, options) {
+    if (testPaths.length === 0 &&
+        options.auto !== true &&
+        options.doctor !== true &&
+        options.canary === undefined) {
+        throw new GeneralError(buildPathlessTestMessage());
+    }
+}
+/** Rejects invalid combinations for mode-like `fireforge test` options. */
+export function assertTestModeCombinations(testPaths, options, canaryPath) {
+    if (options.auto === true && testPaths.length > 0) {
+        throw new GeneralError('`fireforge test --auto` is valid only when no explicit paths are provided.');
+    }
+    if (options.canary !== undefined && testPaths.length > 0) {
+        throw new GeneralError('`fireforge test --canary` runs one canary path; do not pass positional test paths.');
+    }
+    if (options.canary !== undefined && canaryPath === undefined) {
+        throw new GeneralError('No test canary path is configured.\n\n' +
+            'Pass `fireforge test --canary <path>` or set `test.canaryPath` in fireforge.json.');
+    }
+}
+/** Resolves the canary path from CLI or config. */
+export function resolveCanaryPath(options, projectConfig) {
+    if (options.canary === undefined || options.canary === false)
+        return undefined;
+    if (typeof options.canary === 'string')
+        return options.canary;
+    return projectConfig.test?.canaryPath;
+}
+/** Returns the configured canary no-output budget, defaulting to 60 seconds. */
+export function canaryTimeoutSeconds(projectConfig) {
+    return projectConfig.test?.canaryTimeoutSeconds ?? 60;
+}
+/** Emits or throws the one-word canary verdict. */
+export function reportCanaryOutcome(outcome) {
+    if (outcome.verdict.kind === 'tests-ran-ok') {
+        success('Canary: green');
+        return;
+    }
+    if (outcome.verdict.kind === 'harness-crash' &&
+        outcome.verdict.signature?.reason.includes('no-output timeout')) {
+        throw new GeneralError(`Canary: hang\n\n${outcome.verdict.signature.line}`);
+    }
+    if (outcome.verdict.kind === 'harness-crash') {
+        throw new GeneralError(`Canary: crash\n\n${outcome.verdict.signature ? outcome.verdict.signature.line : 'Harness crashed before the canary completed.'}`);
+    }
+    throw new GeneralError('Canary: crash\n\nThe canary did not complete green; see mach output above.');
+}
+function buildPathlessTestMessage() {
+    return ('`fireforge test` now requires an explicit test path unless you choose a pathless mode.\n\n' +
+        'Use one of:\n' +
+        '  - `fireforge test <engine-relative test path>` for focused runs\n' +
+        "  - `fireforge test --auto` to forward mach's own auto-selection mode\n" +
+        '  - `fireforge test --doctor` to run the Marionette preflight only\n' +
+        '  - `fireforge test --canary` to run the configured short harness canary');
+}

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

@@ -0,0 +1,4 @@
+import { Command } from 'commander';
+import type { CommandContext } from '../types/cli.js';
+/** Registers the test command on the CLI program. */
+export declare function registerTest(program: Command, { getProjectRoot, withErrorHandling }: CommandContext): void;

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

@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { Command } from 'commander';
+import { withEngineSessionLock } from '../core/engine-session-lock.js';
+import { GeneralError } from '../errors/base.js';
+import { commanderArgParser, pickDefined } from '../utils/options.js';
+import { testCommand } from './test.js';
+import { DEFAULT_HARNESS_RETRIES } from './test-run.js';
+/** Registers the test command on the CLI program. */
+export function registerTest(program, { getProjectRoot, withErrorHandling }) {
+    program
+        .command('test [paths...]')
+        .description('Run tests via mach test')
+        .option('--headless', 'Run tests in headless mode')
+        .option('--build', 'Run incremental UI build before testing')
+        .option('--auto', 'Forward mach test --auto. Valid only when no explicit paths are provided.')
+        .option('--allow-stale-build', 'Allow tests to run even when packageable engine files changed since the last successful FireForge build')
+        .option('--kill-stale-marionette', 'Terminate a recognized stale browser process holding the Marionette port before running tests')
+        .option('--canary [path]', 'Run one short browser-chrome harness canary. Uses test.canaryPath from fireforge.json when no path is supplied.')
+        .option('--doctor', 'Run a marionette handshake preflight before tests (exit 1 on FAIL). With no paths, runs the preflight only.')
+        .option('--mach-arg <arg>', 'Forward this argument verbatim to `mach test` (repeatable). Escape valve for upstream xpcshell/mochitest flags FireForge does not model.', (value, acc) => {
+        acc.push(value);
+        return acc;
+    }, [])
+        .option('--harness-retries <n>', `Retry budget for recognized harness crashes (resource-monitor tracebacks, pre-test hangs, post-green shutdown re-entry). 0 disables retries. Default: ${String(DEFAULT_HARNESS_RETRIES)}.`, commanderArgParser((raw) => {
+        const n = Number.parseInt(raw, 10);
+        if (!Number.isFinite(n) || n < 0 || n > 10) {
+            throw new GeneralError(`--harness-retries must be an integer in 0..10 (got "${raw}")`);
+        }
+        return n;
+    }))
+        .option('--generic-mach-test', 'Force dispatch through generic `mach test` instead of the suite-specific `mach xpcshell-test` / `mach mochitest` a single-suite run auto-selects (the suite-specific commands skip the mozlog resource monitor that crashes `mach test` on some hosts).')
+        .option('--no-shard', 'Run multiple test paths in one combined mach invocation instead of sequential per-file shards (isolated instances do not exercise cross-file state, so use this to reproduce cross-file pollution bugs)')
+        .option('--perf-samples <path>', 'Publish a perf-sample artifact path to the harness via <BINARYNAME>_PERF_SAMPLE_JSON (resolved against the project root)')
+        .option('--marionette-port <port>', 'Override the Marionette control port (default 2828) for the stale-browser probe, the --doctor preflight, and (unless --mach-arg includes --flavor=xpcshell) auto-forwarded mach args: --setpref=marionette.port=<n> (browser listener) and --marionette=127.0.0.1:<n> (mochitest client). Omits the client flag when --mach-arg already sets --marionette. Use when 2828 is busy or CI assigns another port.', commanderArgParser((raw) => {
+        const n = Number.parseInt(raw, 10);
+        if (!Number.isFinite(n) || n < 1 || n > 65535) {
+            throw new GeneralError(`--marionette-port must be an integer in 1..65535 (got "${raw}")`);
+        }
+        return n;
+    }))
+        .addHelpText('after', [
+        '',
+        '[paths...] semantics: a directory argument selects EXACTLY that',
+        'directory. FireForge enumerates the test files of exactly that',
+        'directory and passes the explicit file list to mach, because mach',
+        'resolves test paths by string prefix and a bare directory name',
+        'silently sweeps in sibling directories sharing the prefix (e.g.',
+        'foo also running foo-extras) — an explicit file list cannot',
+        'prefix-match anything. The directory still runs as ONE mach',
+        'invocation (one browser instance), so cross-file state carries',
+        'within it. When prefix-named siblings exist, the excluded',
+        'directories are listed with their test-file counts; pass them as',
+        'separate paths to include them.',
+        '',
+        'Multiple path arguments shard into sequential isolated harness',
+        'runs (one browser instance per argument) by default, which does',
+        'not exercise cross-argument state; --no-shard restores the',
+        'combined single-instance invocation.',
+    ].join('\n'))
+        .action(withErrorHandling(async (paths, options) => {
+        const projectRoot = getProjectRoot();
+        await withEngineSessionLock(projectRoot, 'test', () => testCommand(projectRoot, paths, pickDefined(options)));
+    }));
+}

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

@@ -53,16 +53,32 @@ export interface TestRunOutcome {
  * stale-xpcshell-symlink repair path the single-run flow already used.
  */
 export declare function runTestsWithRetries(ctx: TestRunContext, paths: string[]): Promise<TestRunOutcome>;
+/**
+ * One sequential harness invocation of a sharded run: a requested path
+ * argument and the mach paths dispatched for it. A file argument is a
+ * group of one; a directory argument groups its enumerated test files so
+ * the whole directory still runs in ONE browser instance (cross-file
+ * state carries within a directory run exactly like the pre-enumeration
+ * behavior).
+ */
+export interface ShardGroup {
+    /** The path argument as the operator passed it (display label). */
+    label: string;
+    /** The mach dispatch paths for this argument. */
+    paths: string[];
+}
 /** Per-shard summary entry. */
 export interface ShardOutcome {
-    path: string;
+    label: string;
     outcome: TestRunOutcome;
 }
 /**
- * Runs each requested path as its own sequential harness invocation and
- * prints an aggregate report. Per-shard failures are diagnosed via
- * `diagnoseShardFailure` (which receives the throwing diagnosis chain from
- * the command layer) but downgraded to warnings so every shard runs; a
- * single aggregate error is thrown at the end when any shard did not pass.
+ * Runs each requested path argument as its own sequential harness
+ * invocation (a directory argument's enumerated files stay together in
+ * one invocation — see {@link ShardGroup}) and prints an aggregate
+ * report. Per-shard failures are diagnosed via `diagnoseShardFailure`
+ * (which receives the throwing diagnosis chain from the command layer)
+ * but downgraded to warnings so every shard runs; a single aggregate
+ * error is thrown at the end when any shard did not pass.
  */
-export declare function runShardedTests(ctx: TestRunContext, paths: string[], diagnoseShardFailure: (outcome: TestRunOutcome, path: string) => string | undefined): Promise<void>;
+export declare function runShardedTests(ctx: TestRunContext, groups: ShardGroup[], diagnoseShardFailure: (outcome: TestRunOutcome, label: string) => string | undefined): Promise<void>;