@hominis/fireforge 0.40.0 → 0.42.0

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

@@ -11,8 +11,11 @@ import { buildGreenSummaryRejectedMessage, buildHarnessCrashMessage, buildNoTest
 import { buildHarnessEarlyExitMessage, classifyHarnessEarlyExit, completePostRebuildFailureContext, prependPostRebuildFailureContext, } from '../core/test-harness-output.js';
 import { GeneralError } from '../errors/base.js';
 import { BuildError } from '../errors/build.js';
+import { toError } from '../utils/errors.js';
 import { info } from '../utils/logger.js';
 import { getPlatform } from '../utils/platform.js';
+import { escapeRegex } from '../utils/regex.js';
+import { emitHarnessVerdict } from './test-verdict.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' +
@@ -51,7 +54,15 @@ function hasStaleBuildArtifactsSignal(output) {
  * failures surface the right diagnosis.
  */
 function hasForkModuleSignal(output, binaryName) {
-    const pattern = new RegExp(`Failed to load resource:\\/\\/\\/modules\\/${binaryName.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\$&')}\\/`, 'i');
+    // `binaryName` comes from fireforge.json, and config validation
+    // (`config-validate.ts:59-70`) bars only `..`, path separators, NUL and
+    // absolute paths — regex metacharacters get through. The inline escape
+    // this replaced wrote its character class as `[.*+?^${}()|[\\]\\\\]`,
+    // which closes early after the escaped backslash, so it escaped nothing:
+    // `my.browser` matched `myXbrowser`, and an unbalanced `(` or `[` threw a
+    // SyntaxError out of the failure-diagnosis path, replacing the real test
+    // failure with an opaque regex error.
+    const pattern = new RegExp(`Failed to load resource:\\/\\/\\/modules\\/${escapeRegex(binaryName)}\\/`, 'i');
     return pattern.test(output);
 }
 function buildForkModuleMessage(binaryName) {
@@ -115,7 +126,12 @@ function buildMochitestHttp3ServerMessage() {
         'This is an upstream Firefox harness interaction; FireForge can only diagnose it.');
 }
 /**
+ * Maps a non-zero mach exit to the most specific actionable diagnosis the
+ * captured output supports, throwing it as a domain error.
  *
+ * The branch order is load-bearing: narrower signals are checked before
+ * broader ones so, for example, a fork-owned module failure is not reported as
+ * a stale build (2026-04-21 eval Finding #14).
  */
 function handleNonZeroTestExit(result, normalizedPaths, appdirInjectionAttempted, binaryName, postRebuildContext) {
     if (result.exitCode === 0 || result.exitCode === 130)
@@ -181,6 +197,18 @@ function handleNonZeroTestExit(result, normalizedPaths, appdirInjectionAttempted
  * the regular non-zero-exit diagnosis chain.
  */
 export function finalizeSingleRunOutcome(outcome, normalizedPaths, binaryName, postRebuildContext, headless = false) {
+    // The FIREFORGE-VERDICT line is the LAST stdout write of the run, on the
+    // pass return and every throw path alike — written raw (not via clack,
+    // whose renderer drops output under non-TTY capture) so harness-verdict
+    // consumers grep one stable line instead of mach internals.
+    try {
+        applySingleRunOutcome(outcome, normalizedPaths, binaryName, postRebuildContext, headless);
+    }
+    finally {
+        emitHarnessVerdict(outcome.verdict);
+    }
+}
+function applySingleRunOutcome(outcome, normalizedPaths, binaryName, postRebuildContext, headless) {
     if (outcome.verdict.kind === 'harness-crash' && outcome.verdict.signature) {
         const base = buildHarnessCrashMessage(outcome.verdict.signature, outcome.attempts);
         const hint = headedNoOutputTimeoutHint(outcome.verdict.signature, {
@@ -243,7 +271,7 @@ export function diagnoseShardOutcome(outcome, path, binaryName, postRebuildConte
         return undefined;
     }
     catch (error) {
-        const diagnosis = error instanceof Error ? error.message : String(error);
+        const diagnosis = toError(error).message;
         const blocks = formatFailureBlocks(outcome.verdict.realFailureBlocks);
         return blocks !== undefined ? `${blocks}\n${diagnosis}` : diagnosis;
     }

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

@@ -29,8 +29,16 @@ export interface HarnessClassification {
  * 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<{
+export declare function classifyBeforeDispatch(engineDir: string, normalizedPaths: string[], options?: {
+    allowMixed?: boolean;
+}): Promise<{
     classification: HarnessClassification;
     xpcshellOnly: boolean;
 }>;
+/**
+ * Prints the `--build-only` completion guidance: the union build is
+ * recorded as the packaging-coverage claim, so each harness half can now
+ * run build-less without tripping the stale/coverage gate.
+ */
+export declare function reportBuildOnlyCompletion(classification: HarnessClassification, normalizedPaths: readonly string[]): void;
 export {};

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

@@ -2,12 +2,14 @@
 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';
+import { info, success } from '../utils/logger.js';
+import { emitHarnessVerdict } from './test-verdict.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.buildOnly !== true &&
         options.canary === undefined) {
         throw new GeneralError(buildPathlessTestMessage());
     }
@@ -24,6 +26,10 @@ export function assertTestModeCombinations(testPaths, options, canaryPath) {
         throw new GeneralError('No test canary path is configured.\n\n' +
             'Pass `fireforge test --canary <path>` or set `test.canaryPath` in fireforge.json.');
     }
+    if (options.buildOnly === true &&
+        (options.doctor === true || options.canary !== undefined || options.auto === true)) {
+        throw new GeneralError('`fireforge test --build-only` builds and exits without dispatching tests; it cannot be combined with --doctor, --canary, or --auto.');
+    }
 }
 /** Resolves the canary path from CLI or config. */
 export function resolveCanaryPath(options, projectConfig) {
@@ -39,18 +45,25 @@ export function canaryTimeoutSeconds(projectConfig) {
 }
 /** 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}`);
+    // Written raw as the run's last stdout line on green and throw paths
+    // alike — see the FIREFORGE-VERDICT contract in test-harness-crash.ts.
+    try {
+        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.');
     }
-    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.'}`);
+    finally {
+        emitHarnessVerdict(outcome.verdict);
     }
-    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' +
@@ -91,13 +104,33 @@ function buildMixedHarnessMessage(classification) {
  * 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) {
+export async function classifyBeforeDispatch(engineDir, normalizedPaths, options) {
     const classification = await classifyTestHarnesses(engineDir, normalizedPaths);
     if (classification.xpcshell.length > 0 && classification.nonXpcshell.length > 0) {
-        throw new GeneralError(buildMixedHarnessMessage(classification));
+        // `--build-only` never dispatches, so a mixed request is legal there —
+        // packaging the union is the whole point (FORGE J9).
+        if (options?.allowMixed !== true) {
+            throw new GeneralError(buildMixedHarnessMessage(classification));
+        }
     }
     return {
         classification,
         xpcshellOnly: normalizedPaths.length > 0 && classification.nonXpcshell.length === 0,
     };
 }
+/**
+ * Prints the `--build-only` completion guidance: the union build is
+ * recorded as the packaging-coverage claim, so each harness half can now
+ * run build-less without tripping the stale/coverage gate.
+ */
+export function reportBuildOnlyCompletion(classification, normalizedPaths) {
+    info('Build complete. The recorded packaging coverage includes every requested path.');
+    if (classification.xpcshell.length > 0 && classification.nonXpcshell.length > 0) {
+        info('Run each harness separately without --build:');
+        info(`  fireforge test ${classification.xpcshell.join(' ')}`);
+        info(`  fireforge test ${classification.nonXpcshell.join(' ')}`);
+    }
+    else if (normalizedPaths.length > 0) {
+        info(`Run: fireforge test ${normalizedPaths.join(' ')}`);
+    }
+}

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

@@ -1,10 +1,49 @@
 // 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 { addWaitLockOption, commanderArgParser, pickDefined, resolveWaitLockSeconds, } from '../utils/options.js';
+import { GeneralError, LockContentionError } from '../errors/base.js';
+import { addWaitLockOption, commanderArgParser, pickDefined, resolveWaitLockSeconds, stringListOption, } from '../utils/options.js';
 import { testCommand } from './test.js';
 import { DEFAULT_HARNESS_RETRIES } from './test-run.js';
+import { emitFailVerdict, resetVerdictEmission, verdictEmitted } from './test-verdict.js';
+const TEST_HELP_TEXT = [
+    '',
+    '[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.',
+    '',
+    'Machine-readable verdict: every run (single, sharded, --canary,',
+    '--doctor) ends with exactly one raw stdout line',
+    '  FIREFORGE-VERDICT: PASS|FAIL [reason=crash|test-failures|',
+    '  no-tests|preflight|inconclusive|lock-timeout] [checks=<n>]',
+    '  [unexpected=<n>] [shards=<p>/<t>]',
+    'The status follows the harness classifier, not the raw exit code:',
+    'a crash-classified run says FAIL reason=crash even at exit 0, and',
+    'a green-summary-override pass says PASS despite a non-zero mach',
+    'exit. reason=preflight covers any failure before the harness ran',
+    '(missing/stale build, invalid paths, port conflicts, config',
+    'errors); reason=inconclusive means engine/ changed while the',
+    'tests ran, so the harness result cannot be trusted;',
+    'reason=lock-timeout means the run never started because another',
+    'engine-mutating command held the lock past the wait budget. A sharded',
+    'aggregate reason is the most structural failing shard (crash,',
+    'then no-tests, then test-failures). Count keys are omitted when',
+    'the embedded summary did not print them. Key on this line',
+    'instead of mach internals.',
+].join('\n');
 /** Registers the test command on the CLI program. */
 export function registerTest(program, { getProjectRoot, withErrorHandling }) {
     const test = program
@@ -12,16 +51,15 @@ export function registerTest(program, { getProjectRoot, withErrorHandling }) {
         .description('Run tests via mach test')
         .option('--headless', 'Run tests in headless mode')
         .option('--build', 'Run incremental UI build before testing')
+        .option('--build-only', 'Run the scoped pre-test build (packaging exactly [paths...], mixed harnesses allowed) and exit without dispatching tests — one build covers both harness halves, then run each half without --build')
+        .option('--extend-coverage', 'With --build/--build-only and explicit paths, union those paths into the recorded test-packaging coverage instead of replacing it, so an earlier scoped build stays covered. Refused when the build anchor moved (engine HEAD, mozconfig, or a previously fingerprinted packageable file changed).')
         .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('--allow-stale-components', 'Run tests despite components.conf changes that only a full "fireforge build" compiles in (the packaged child process will resolve the OLD StaticComponents table)')
-        .option('--kill-stale-marionette', 'Terminate a recognized stale browser process holding the Marionette port before running tests')
+        .option('--kill-stale-marionette', 'Terminate a recognized stale browser from this objdir or one 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('--mach-arg <arg>', 'Forward this argument verbatim to `mach test` (repeatable). Escape valve for upstream xpcshell/mochitest flags FireForge does not model.', ...stringListOption())
         .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) {
@@ -39,27 +77,21 @@ export function registerTest(program, { getProjectRoot, withErrorHandling }) {
         }
         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'));
+        .addHelpText('after', TEST_HELP_TEXT);
     addWaitLockOption(test).action(withErrorHandling(async (paths, options) => {
         const projectRoot = getProjectRoot();
-        await withEngineSessionLock(projectRoot, 'test', () => testCommand(projectRoot, paths, pickDefined(options)), { waitLockSeconds: resolveWaitLockSeconds(options.waitLock) });
+        // The engine session lock is acquired outside testCommand's own
+        // exactly-one-verdict guarantee, so a lock failure must emit here or
+        // the run ends with no FIREFORGE-VERDICT line at all.
+        resetVerdictEmission();
+        try {
+            await withEngineSessionLock(projectRoot, 'test', () => testCommand(projectRoot, paths, pickDefined(options)), { waitLockSeconds: resolveWaitLockSeconds(options.waitLock) });
+        }
+        catch (error) {
+            if (!verdictEmitted()) {
+                emitFailVerdict(error instanceof LockContentionError ? 'lock-timeout' : 'preflight');
+            }
+            throw error;
+        }
     }));
 }

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

@@ -74,13 +74,39 @@ export interface ShardOutcome {
     label: string;
     outcome: TestRunOutcome;
 }
+/** Aggregate result of a sharded run, verdict emission deferred to the caller. */
+export interface ShardedRunSummary {
+    shards: ShardOutcome[];
+    passed: number;
+    total: number;
+    /** Aggregate classifier verdict — see {@link deriveAggregateShardVerdict}. */
+    aggregate: HarnessRunVerdict;
+}
+/**
+ * Derives the aggregate classification for a sharded run: all-green is
+ * `tests-ran-ok`; otherwise the most structural failure wins — a crashed
+ * shard makes the whole run `harness-crash`, then `no-tests`, then plain
+ * `test-failures` — so the aggregate `reason=` keeps the classifier-driven
+ * contract instead of collapsing every failure to `test-failures`.
+ */
+export declare function deriveAggregateShardVerdict(shards: ShardOutcome[]): HarnessRunVerdict;
 /**
  * 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.
+ * but downgraded to warnings so every shard runs. The aggregate verdict
+ * line and the aggregate error are NOT produced here — the caller runs
+ * the engine-generation integrity check first and then calls
+ * {@link finalizeShardedOutcome}, so a run invalidated by a concurrent
+ * `engine/` mutation can never print `PASS` before the check fails.
+ */
+export declare function runShardedTests(ctx: TestRunContext, groups: ShardGroup[], diagnoseShardFailure: (outcome: TestRunOutcome, label: string) => string | undefined): Promise<ShardedRunSummary>;
+/**
+ * Emits the aggregate FIREFORGE-VERDICT line for a sharded run, then
+ * throws the aggregate error when any shard did not pass — the same
+ * emit-then-throw shape as `finalizeSingleRunOutcome`. Called only after
+ * the engine-generation check succeeded.
  */
-export declare function runShardedTests(ctx: TestRunContext, groups: ShardGroup[], diagnoseShardFailure: (outcome: TestRunOutcome, label: string) => string | undefined): Promise<void>;
+export declare function finalizeShardedOutcome(summary: ShardedRunSummary): void;

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

@@ -19,6 +19,7 @@ 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';
+import { emitHarnessVerdict } from './test-verdict.js';
 /** Default bounded retry budget for recognized harness crashes. */
 export const DEFAULT_HARNESS_RETRIES = 2;
 /** Resolves the capturing mach dispatcher for a suite. */
@@ -78,14 +79,34 @@ const SHARD_STATUS_LABEL = {
     'harness-crash': 'CRASH',
     'no-tests': 'NO-TESTS',
 };
+/**
+ * Derives the aggregate classification for a sharded run: all-green is
+ * `tests-ran-ok`; otherwise the most structural failure wins — a crashed
+ * shard makes the whole run `harness-crash`, then `no-tests`, then plain
+ * `test-failures` — so the aggregate `reason=` keeps the classifier-driven
+ * contract instead of collapsing every failure to `test-failures`.
+ */
+export function deriveAggregateShardVerdict(shards) {
+    const kinds = new Set(shards.map(({ outcome }) => outcome.verdict.kind));
+    if (kinds.has('harness-crash'))
+        return { kind: 'harness-crash' };
+    if (kinds.has('no-tests'))
+        return { kind: 'no-tests' };
+    if (kinds.has('test-failures'))
+        return { kind: 'test-failures' };
+    return { kind: 'tests-ran-ok' };
+}
 /**
  * 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.
+ * but downgraded to warnings so every shard runs. The aggregate verdict
+ * line and the aggregate error are NOT produced here — the caller runs
+ * the engine-generation integrity check first and then calls
+ * {@link finalizeShardedOutcome}, so a run invalidated by a concurrent
+ * `engine/` mutation can never print `PASS` before the check fails.
  */
 export async function runShardedTests(ctx, groups, diagnoseShardFailure) {
     const shards = [];
@@ -111,8 +132,24 @@ export async function runShardedTests(ctx, groups, diagnoseShardFailure) {
         (outcome.attempts > 1 ? `  (${outcome.attempts} attempts)` : ''));
     const failing = shards.filter(({ outcome }) => outcome.verdict.kind !== 'tests-ran-ok');
     note(`${lines.join('\n')}\n\n${shards.length - failing.length}/${shards.length} shard(s) passed`, 'Sharded Test Summary');
-    if (failing.length > 0) {
-        throw new BuildError(`${failing.length} of ${shards.length} sharded test run(s) did not pass: ` +
+    return {
+        shards,
+        passed: shards.length - failing.length,
+        total: shards.length,
+        aggregate: deriveAggregateShardVerdict(shards),
+    };
+}
+/**
+ * Emits the aggregate FIREFORGE-VERDICT line for a sharded run, then
+ * throws the aggregate error when any shard did not pass — the same
+ * emit-then-throw shape as `finalizeSingleRunOutcome`. Called only after
+ * the engine-generation check succeeded.
+ */
+export function finalizeShardedOutcome(summary) {
+    emitHarnessVerdict(summary.aggregate, { passed: summary.passed, total: summary.total });
+    if (summary.passed < summary.total) {
+        const failing = summary.shards.filter(({ outcome }) => outcome.verdict.kind !== 'tests-ran-ok');
+        throw new BuildError(`${failing.length} of ${summary.total} sharded test run(s) did not pass: ` +
             `${failing.map(({ label }) => label).join(', ')}. ` +
             'See the per-shard diagnosis above. Use --no-shard to reproduce the combined single-invocation behaviour.', 'mach test');
     }

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

@@ -0,0 +1,32 @@
+import type { HarnessRunVerdict } from '../core/test-harness-crash.js';
+/**
+ * Reason codes the emission layer can put on a `FIREFORGE-VERDICT: FAIL`
+ * line. The first three mirror the harness classifier; `preflight` covers
+ * every failure before harness classification (missing/stale builds,
+ * invalid paths, port conflicts, config errors, spawn failures),
+ * `inconclusive` marks a run whose harness result exists but cannot be
+ * trusted because `engine/` changed (or became unprobeable one-sidedly)
+ * while the tests ran, and `lock-timeout` marks a run that never started
+ * because the engine session lock stayed contended past the wait budget.
+ */
+export type FireforgeVerdictReason = 'crash' | 'no-tests' | 'test-failures' | 'preflight' | 'inconclusive' | 'lock-timeout';
+/**
+ * Re-arms the verdict sink for a new run. Called at `testCommand` entry so
+ * repeated programmatic invocations (and tests) each get their own
+ * exactly-one-line guarantee.
+ */
+export declare function resetVerdictEmission(): void;
+/** True once this run has written its `FIREFORGE-VERDICT:` line. */
+export declare function verdictEmitted(): boolean;
+/**
+ * Emits the classifier-derived verdict for a completed harness run, with
+ * the aggregate `shards=<passed>/<total>` suffix for sharded runs.
+ */
+export declare function emitHarnessVerdict(verdict: HarnessRunVerdict, shards?: {
+    passed: number;
+    total: number;
+}): void;
+/** Emits the pathless `--doctor` PASS verdict. */
+export declare function emitPassVerdict(): void;
+/** Emits a FAIL verdict carrying an emission-layer reason code. */
+export declare function emitFailVerdict(reason: FireforgeVerdictReason): void;

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

@@ -0,0 +1,48 @@
+import { formatFireforgeVerdictLine } from '../core/test-harness-crash.js';
+import { setStdoutSealed } from '../utils/logger.js';
+let emitted = false;
+/**
+ * Re-arms the verdict sink for a new run. Called at `testCommand` entry so
+ * repeated programmatic invocations (and tests) each get their own
+ * exactly-one-line guarantee.
+ */
+export function resetVerdictEmission() {
+    emitted = false;
+    setStdoutSealed(false);
+}
+/** True once this run has written its `FIREFORGE-VERDICT:` line. */
+export function verdictEmitted() {
+    return emitted;
+}
+/**
+ * Writes the run's single verdict line — raw stdout (clack's renderer can
+ * drop output under non-TTY capture), first write wins. Every later call
+ * is a no-op: the writer closest to the harness result runs first, so the
+ * fallback layers (the engine-generation guard, the preflight wrapper)
+ * can emit unconditionally without risking a second line. Writing also
+ * seals stdout: the verdict must stay the run's LAST stdout write, so all
+ * subsequent logger output — including the CLI-boundary error/cancel
+ * rendering after an emit-then-throw path — routes to stderr.
+ */
+function writeVerdictLine(line) {
+    if (emitted)
+        return;
+    emitted = true;
+    process.stdout.write(`${line}\n`);
+    setStdoutSealed(true);
+}
+/**
+ * Emits the classifier-derived verdict for a completed harness run, with
+ * the aggregate `shards=<passed>/<total>` suffix for sharded runs.
+ */
+export function emitHarnessVerdict(verdict, shards) {
+    writeVerdictLine(formatFireforgeVerdictLine(verdict, shards));
+}
+/** Emits the pathless `--doctor` PASS verdict. */
+export function emitPassVerdict() {
+    writeVerdictLine('FIREFORGE-VERDICT: PASS');
+}
+/** Emits a FAIL verdict carrying an emission-layer reason code. */
+export function emitFailVerdict(reason) {
+    writeVerdictLine(`FIREFORGE-VERDICT: FAIL reason=${reason}`);
+}

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

@@ -1,6 +1,15 @@
 import type { TestOptions } from '../types/commands/index.js';
 /**
  * Runs the test command to execute mach tests.
+ *
+ * Owns the run's exactly-one-`FIREFORGE-VERDICT:`-line guarantee: the sink
+ * is re-armed at entry, and any failure that reaches this boundary without
+ * an inner writer having emitted — the preflight ladder (missing engine or
+ * build, config errors, stale-build and port gates, missing paths), and a
+ * harness process that failed to start — emits `FAIL reason=preflight`,
+ * since no harness classification exists for such a run. Writers closer to
+ * the harness (doctor, canary, single, sharded, the engine-generation
+ * guard) emit first and win.
  * @param projectRoot - Root directory of the project
  * @param testPaths - Test file or directory paths
  * @param options - Test options