@hominis/fireforge 0.49.2 → 0.51.0

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

@@ -14,18 +14,21 @@ import { join } from 'node:path';
 import { probeDisplaySleepState } from '../core/display-state.js';
 import { runMachTestSuite } from '../core/mach.js';
 import { parentExited } from '../core/parent-exit-watchdog.js';
-import { getActiveRunLogPath } from '../core/run-log.js';
+import { activeRunLogLine, getActiveRunLogPath } from '../core/run-log.js';
 import { changedPrefNoiseVerdictNote } from '../core/test-changed-prefs.js';
-import { buildHarnessCrashMessage, classifyHarnessRun, headedDisplayAsleepVerdictNote, headedNoOutputTimeoutHint, } from '../core/test-harness-crash.js';
+import { classifyHarnessRun, headedDisplayAsleepVerdictNote, } from '../core/test-harness-crash.js';
 import { reportTestHost, sampleTestHost, stampPerfHost } from '../core/test-host-state.js';
+import { forwardedRawLogPath, hasForwardedRawLog, readRawTestLog, } from '../core/test-raw-log.js';
+import { createStartMarkerTracker, vetoIncompletePass, } from '../core/test-run-completeness.js';
 import { retryAfterXpcshellSymlinkRepair } from '../core/test-xpcshell-retry.js';
 import { withXpcshellProfileDir } from '../core/xpcshell-profile-dir.js';
 import { TestFailureError } from '../errors/build.js';
-import { info, note, warn } from '../utils/logger.js';
+import { warn } from '../utils/logger.js';
 import { getPlatform } from '../utils/platform.js';
 import { maybeInjectAppdirArg } from './test-appdir.js';
 import { createHarnessTeardown } from './test-harness-teardown.js';
-import { emitHarnessVerdict, setVerdictRunAttribute } from './test-verdict.js';
+import { recordTestResults } from './test-results.js';
+import { setVerdictRunAttribute } from './test-verdict.js';
 /** Default bounded retry budget for recognized harness crashes. */
 export const DEFAULT_HARNESS_RETRIES = 2;
 /** Resolves the mach test command a suite dispatches to. */
@@ -41,21 +44,21 @@ function machKindForSuite(suite) {
  * crashes up to the configured budget. Every attempt goes through the
  * stale-xpcshell-symlink repair path the single-run flow already used.
  */
-export async function runTestsWithRetries(ctx, paths) {
+export async function runTestsWithRetries(ctx, paths, label = paths.join(' ')) {
     // Pure mochitest dispatches keep their env byte-identical, since the profile
     // variable is xpcshell-harness-specific. Generic `mach
     // test` runs may include xpcshell paths, so they get the isolation too.
     if (ctx.suite === 'mochitest') {
-        return runTestsWithRetriesInner(ctx, paths, ctx.env);
+        return runTestsWithRetriesInner(ctx, paths, ctx.env, label);
     }
     // Fresh profile dir per harness invocation: shards isolate from each
     // other and from concurrent `fireforge test` processes. The crash /
     // symlink-repair retries inside one invocation reuse the same directory
     // on purpose (they are the same logical run and the harness
     // re-initialises the profile contents itself).
-    return withXpcshellProfileDir(ctx.env, (env) => runTestsWithRetriesInner(ctx, paths, env));
+    return withXpcshellProfileDir(ctx.env, (env) => runTestsWithRetriesInner(ctx, paths, env, label));
 }
-async function runTestsWithRetriesInner(ctx, paths, env) {
+async function runTestsWithRetriesInner(ctx, paths, env, label) {
     const extraArgs = [...ctx.baseExtraArgs];
     const appdirInjectionAttempted = await maybeInjectAppdirArg(ctx.engineDir, paths, ctx.objDir, extraArgs);
     const kind = machKindForSuite(ctx.suite);
@@ -63,9 +66,15 @@ async function runTestsWithRetriesInner(ctx, paths, env) {
     let attempts = 0;
     let result;
     let verdict;
+    let rawLog;
+    let logLine;
     for (;;) {
         attempts += 1;
-        result = await runTrackedMachTestSuite(ctx, kind, paths, extraArgs, env);
+        let tracker = createStartMarkerTracker();
+        const raw = rawLogDispatchArgs(ctx, extraArgs);
+        logLine = activeRunLogLine();
+        const dispatched = await runTrackedMachTestSuite(ctx, kind, paths, raw.args, env, tracker);
+        result = dispatched;
         // The parent that was reading this run is gone and the watchdog has
         // already killed the harness. Classifying the corpse would call it a
         // harness crash and retry it under nobody's supervision.
@@ -73,19 +82,32 @@ async function runTestsWithRetriesInner(ctx, paths, env) {
             throw new TestFailureError('The parent process exited while the harness was running; the harness tree was ' +
                 'terminated and the run ended without a result.', `mach ${kind}`, undefined, getActiveRunLogPath());
         }
+        const retryTracker = createStartMarkerTracker();
         result = await retryAfterXpcshellSymlinkRepair({
             engineDir: ctx.engineDir,
             objDir: ctx.objDir,
             result,
             classification: ctx.classification,
             normalizedPaths: paths,
-            extraArgs,
+            extraArgs: raw.args,
             env,
             kind,
             fullOutput: ctx.fullOutput,
+            onOutputChunk: (stream, chunk) => {
+                retryTracker.onChunk(stream, chunk);
+            },
         });
+        if (result !== dispatched)
+            tracker = retryTracker;
+        rawLog = raw.path === undefined ? undefined : await readRawTestLog(raw.path);
         const combined = `${result.stdout}\n${result.stderr}`;
-        verdict = classifyHarnessRun(result.exitCode, combined, paths);
+        // An exit-0 run is still not a pass when it stopped partway or
+        // reported unexpected results (see test-run-completeness.ts). The
+        // start count reads the structured raw log when the run wrote one, and
+        // the streamed markers otherwise, never the 2 MB capture tail.
+        verdict = vetoIncompletePass(classifyHarnessRun(result.exitCode, combined, paths), combined, paths, rawLog !== undefined && rawLog.markers.started.length > 0
+            ? { markers: rawLog.markers, source: 'raw' }
+            : { markers: tracker.markers(), source: 'stream' });
         if (verdict.kind !== 'harness-crash' || attempts >= maxAttempts)
             break;
         warn(`Harness crash detected (${verdict.signature?.reason ?? 'unknown shape'}): ` +
@@ -110,14 +132,45 @@ async function runTestsWithRetriesInner(ctx, paths, env) {
         if (note !== undefined)
             verdict = { ...verdict, note };
     }
-    return { result, verdict, attempts, appdirInjectionAttempted, displayState };
+    if (rawLog !== undefined) {
+        recordTestResults(rawLog.results, rawLog.unfinished, {
+            run: ctx.repetition ?? 1,
+            shard: label,
+            logLine,
+        });
+    }
+    return {
+        result,
+        verdict,
+        attempts,
+        appdirInjectionAttempted,
+        displayState,
+        ...(rawLog === undefined ? {} : { fileResults: rawLog.results }),
+    };
+}
+/** Sequence for raw-log file names, unique within the process. */
+let rawLogSequence = 0;
+/**
+ * The dispatch arguments with a `--log-raw` destination added, when this run
+ * collects per-file results. An operator's own forwarded `--log-raw <file>`
+ * is read instead of adding a second one.
+ */
+function rawLogDispatchArgs(ctx, extraArgs) {
+    if (ctx.rawLogDir === undefined)
+        return { args: [...extraArgs], path: undefined };
+    if (hasForwardedRawLog(extraArgs)) {
+        return { args: [...extraArgs], path: forwardedRawLogPath(extraArgs) };
+    }
+    rawLogSequence += 1;
+    const path = join(ctx.rawLogDir, `dispatch-${rawLogSequence}.raw.jsonl`);
+    return { args: [...extraArgs, `--log-raw=${path}`], path };
 }
 /**
  * One mach dispatch with its kill path attached: helper-pid tracking and
  * post-close reaping, the process-group announcement, and the parent-exit
  * watchdog for exactly as long as mach runs.
  */
-async function runTrackedMachTestSuite(ctx, kind, paths, extraArgs, env) {
+async function runTrackedMachTestSuite(ctx, kind, paths, extraArgs, env, tracker) {
     const teardown = createHarnessTeardown({
         objDir: ctx.objDir === undefined ? undefined : join(ctx.engineDir, ctx.objDir),
         pgidFile: ctx.pgidFile,
@@ -139,7 +192,14 @@ async function runTrackedMachTestSuite(ctx, kind, paths, extraArgs, env) {
             args: extraArgs,
             env,
             fullOutput: ctx.fullOutput,
-            teardown: teardown.hooks,
+            ...(ctx.outputPrefix === undefined ? {} : { outputPrefix: ctx.outputPrefix }),
+            teardown: {
+                ...teardown.hooks,
+                onOutputChunk: (stream, chunk) => {
+                    tracker.onChunk(stream, chunk);
+                    teardown.hooks.onOutputChunk?.(stream, chunk);
+                },
+            },
         });
     }
     finally {
@@ -170,88 +230,3 @@ async function probeDisplayStateForStall(verdict, headless) {
         return undefined;
     return probeDisplaySleepState(getPlatform());
 }
-const SHARD_STATUS_LABEL = {
-    'tests-ran-ok': 'PASS',
-    'test-failures': 'FAIL',
-    'harness-crash': 'CRASH',
-    'no-tests': 'NO-TESTS',
-    'harness-arguments': 'ARGUMENTS',
-};
-/**
- * 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-arguments'))
-        return { kind: 'harness-arguments' };
-    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. 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 = [];
-    for (const [index, group] of groups.entries()) {
-        info(`— Shard ${index + 1}/${groups.length}: ${group.label}`);
-        const outcome = await runTestsWithRetries(ctx, group.paths);
-        shards.push({ label: group.label, outcome });
-        if (outcome.verdict.kind === 'harness-crash' && outcome.verdict.signature) {
-            const base = buildHarnessCrashMessage(outcome.verdict.signature, outcome.attempts);
-            const hint = headedNoOutputTimeoutHint(outcome.verdict.signature, {
-                headless: ctx.headless,
-                platform: getPlatform(),
-                ...(outcome.displayState !== undefined ? { displayState: outcome.displayState } : {}),
-            });
-            warn(hint ? `${base}\n\n${hint}` : base);
-        }
-        else if (outcome.verdict.kind !== 'tests-ran-ok') {
-            const diagnosis = diagnoseShardFailure(outcome, group.label);
-            if (diagnosis)
-                warn(diagnosis);
-        }
-    }
-    const lines = shards.map(({ label, outcome }) => `${SHARD_STATUS_LABEL[outcome.verdict.kind].padEnd(8)} ${label}` +
-        (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');
-    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 TestFailureError(`${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', undefined, getActiveRunLogPath());
-    }
-}

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

@@ -0,0 +1,110 @@
+/**
+ * Sharded `fireforge test` runs: one harness invocation per shard, run in
+ * order on one harness instance, or on a pool of `--jobs <n>` instances.
+ *
+ * Each finished shard prints a `FIREFORGE-SHARD:` line, and the aggregate
+ * verdict names the shards that did not pass as `failed-shards=`. Before,
+ * the failing shards were named only in the prose of the aggregate error
+ * and the human summary box, so a wrapper that reruns failed shards had to
+ * parse a sentence that a reworded message would silently break.
+ *
+ * Under `--shard-size <n>` a shard is a chunk of n files, and the run is
+ * judged per file from each dispatch's raw log: `shards=` then counts files
+ * and `failed-shards=` names the files that failed.
+ */
+import { type HarnessRunVerdict } from '../core/test-harness-crash.js';
+import { type TestRunContext, type TestRunOutcome } from './test-run.js';
+/**
+ * One 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, keeping cross-file state
+ * behaviour within a directory run. A `--shard-size` chunk is a group of
+ * up to n files.
+ */
+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 {
+    label: string;
+    outcome: TestRunOutcome;
+    /** The shard's dispatch paths (per-file judging). */
+    paths?: string[];
+}
+/** Aggregate result of a sharded run, verdict emission deferred to the caller. */
+export interface ShardedRunSummary {
+    shards: ShardOutcome[];
+    passed: number;
+    total: number;
+    /** What did not pass: shard labels, or file paths when judged per file. */
+    failed: string[];
+    /** Aggregate classifier verdict. See {@link deriveAggregateShardVerdict}. */
+    aggregate: HarnessRunVerdict;
+}
+/** How {@link runShardedTests} schedules and judges its shards. */
+export interface ShardRunOptions {
+    /** Harness instances to run shards on at once (`--jobs`). Default 1. */
+    jobs?: number;
+    /**
+     * The context for instance `index` (0-based). Instance 0 must be the
+     * base context; others carry their own ports and output prefix.
+     */
+    contextFor?: (index: number) => Promise<TestRunContext> | TestRunContext;
+    /** Judge per file from the raw log (`--shard-size`). */
+    perFile?: boolean;
+}
+/**
+ * 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;
+/**
+ * The `FIREFORGE-SHARD:` line for one finished shard: the verdict it would
+ * have printed alone, plus `shard=<i>/<n>` and `path=<label>`. Never a
+ * `FIREFORGE-VERDICT:` line, so the run keeps exactly one.
+ */
+export declare function formatShardLine(shard: ShardOutcome, index: number, total: number, failedFiles?: readonly string[]): string;
+/**
+ * The files of one shard that did not pass, judged from its raw log. A file
+ * with no `test_end` failed (it never started, or never finished). Returns
+ * undefined when the shard wrote no raw log, so the caller judges the
+ * shard as a whole.
+ */
+export declare function failedFilesOf(shard: ShardOutcome): string[] | undefined;
+/**
+ * Runs each shard as its own 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. 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, options?: ShardRunOptions): 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 finalizeShardedOutcome(summary: ShardedRunSummary): void;
+/**
+ * Splits the dispatch paths of every group into consecutive chunks of at
+ * most `size` files (`--shard-size`). Order is kept, and a chunk never
+ * mixes groups' order: it is the flattened request, cut every `size`
+ * files.
+ */
+export declare function chunkShardGroups(groups: readonly ShardGroup[], size: number): ShardGroup[];
+/**
+ * Splits one combined request into `parts` contiguous chunks of near-equal
+ * size, in order (`--jobs` with `--no-shard`).
+ */
+export declare function splitContiguous(paths: readonly string[], parts: number): ShardGroup[];

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

@@ -0,0 +1,255 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Sharded `fireforge test` runs: one harness invocation per shard, run in
+ * order on one harness instance, or on a pool of `--jobs <n>` instances.
+ *
+ * Each finished shard prints a `FIREFORGE-SHARD:` line, and the aggregate
+ * verdict names the shards that did not pass as `failed-shards=`. Before,
+ * the failing shards were named only in the prose of the aggregate error
+ * and the human summary box, so a wrapper that reruns failed shards had to
+ * parse a sentence that a reworded message would silently break.
+ *
+ * Under `--shard-size <n>` a shard is a chunk of n files, and the run is
+ * judged per file from each dispatch's raw log: `shards=` then counts files
+ * and `failed-shards=` names the files that failed.
+ */
+import { getActiveRunLogPath, writeToActiveRunLog } from '../core/run-log.js';
+import { buildHarnessCrashMessage, formatFireforgeVerdictLine, headedNoOutputTimeoutHint, } from '../core/test-harness-crash.js';
+import { TestFailureError } from '../errors/build.js';
+import { info, note, warn } from '../utils/logger.js';
+import { getPlatform } from '../utils/platform.js';
+import { runTestsWithRetries } from './test-run.js';
+import { emitHarnessVerdict } from './test-verdict.js';
+const SHARD_STATUS_LABEL = {
+    'tests-ran-ok': 'PASS',
+    'test-failures': 'FAIL',
+    'harness-crash': 'CRASH',
+    'no-tests': 'NO-TESTS',
+    'harness-arguments': 'ARGUMENTS',
+};
+/**
+ * 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-arguments'))
+        return { kind: 'harness-arguments' };
+    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' };
+}
+/**
+ * The `FIREFORGE-SHARD:` line for one finished shard: the verdict it would
+ * have printed alone, plus `shard=<i>/<n>` and `path=<label>`. Never a
+ * `FIREFORGE-VERDICT:` line, so the run keeps exactly one.
+ */
+export function formatShardLine(shard, index, total, failedFiles) {
+    const body = formatFireforgeVerdictLine(shard.outcome.verdict).slice('FIREFORGE-VERDICT: '.length);
+    const files = failedFiles !== undefined && failedFiles.length > 0
+        ? ` failed-files=${failedFiles.join(',')}`
+        : '';
+    return `FIREFORGE-SHARD: ${body} shard=${index + 1}/${total} path=${shard.label.replace(/\s+/g, '_')}${files}`;
+}
+function writeShardLine(line) {
+    process.stdout.write(`${line}\n`);
+    writeToActiveRunLog(`${line}\n`);
+}
+/** True when a raw-log test id names the dispatched path. */
+function namesPath(test, path) {
+    return test === path || test.endsWith(`/${path}`) || path.endsWith(`/${test}`);
+}
+/**
+ * The files of one shard that did not pass, judged from its raw log. A file
+ * with no `test_end` failed (it never started, or never finished). Returns
+ * undefined when the shard wrote no raw log, so the caller judges the
+ * shard as a whole.
+ */
+export function failedFilesOf(shard) {
+    const results = shard.outcome.fileResults;
+    if (results === undefined || shard.paths === undefined)
+        return undefined;
+    return shard.paths.filter((path) => {
+        const result = results.find((entry) => namesPath(entry.test, path));
+        return result === undefined || result.unexpected;
+    });
+}
+function reportShardFailure(ctx, outcome, label, diagnoseShardFailure) {
+    if (outcome.verdict.kind === 'harness-crash' && outcome.verdict.signature) {
+        const base = buildHarnessCrashMessage(outcome.verdict.signature, outcome.attempts);
+        const hint = headedNoOutputTimeoutHint(outcome.verdict.signature, {
+            headless: ctx.headless,
+            platform: getPlatform(),
+            ...(outcome.displayState !== undefined ? { displayState: outcome.displayState } : {}),
+        });
+        warn(hint ? `${base}\n\n${hint}` : base);
+    }
+    else if (outcome.verdict.kind !== 'tests-ran-ok') {
+        const diagnosis = diagnoseShardFailure(outcome, label);
+        if (diagnosis)
+            warn(diagnosis);
+    }
+}
+/**
+ * Runs `count` items on up to `jobs` workers at once. Worker `w` handles
+ * the items it takes in order, and results keep item order.
+ */
+async function runPool(count, jobs, worker) {
+    const results = new Array(count);
+    let next = 0;
+    const workers = Array.from({ length: Math.max(1, Math.min(jobs, count)) }, async (_, w) => {
+        while (next < count) {
+            const item = next;
+            next += 1;
+            results[item] = await worker(item, w);
+        }
+    });
+    await Promise.all(workers);
+    return results;
+}
+/**
+ * Runs each shard as its own 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. 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, options = {}) {
+    const jobs = options.jobs ?? 1;
+    const contexts = new Map([[0, ctx]]);
+    const contextFor = async (index) => {
+        const known = contexts.get(index);
+        if (known !== undefined)
+            return known;
+        const made = options.contextFor === undefined ? ctx : await options.contextFor(index);
+        contexts.set(index, made);
+        return made;
+    };
+    let finished = 0;
+    const shards = await runPool(groups.length, jobs, async (index, workerIndex) => {
+        const group = groups[index];
+        const instance = await contextFor(workerIndex);
+        info(`— Shard ${index + 1}/${groups.length}${jobs > 1 ? ` [job ${workerIndex + 1}]` : ''}: ${group.label}`);
+        const outcome = await runTestsWithRetries(instance, group.paths, group.label);
+        // Perf power-source changes are recorded on the instance's context.
+        if (instance.powerChanged === true)
+            ctx.powerChanged = true;
+        const shard = { label: group.label, outcome, paths: group.paths };
+        reportShardFailure(instance, outcome, group.label, diagnoseShardFailure);
+        finished += 1;
+        writeShardLine(formatShardLine(shard, index, groups.length, options.perFile === true ? failedFilesOf(shard) : undefined));
+        reportProgress(finished, groups.length, jobs);
+        return shard;
+    });
+    return summarizeShards(shards, options.perFile === true);
+}
+function reportProgress(finished, total, jobs) {
+    if (jobs > 1)
+        info(`${finished}/${total} shard(s) finished.`);
+}
+/**
+ * Builds the summary box and the counts. Per-file judging counts every
+ * dispatched file of a shard that wrote a raw log; a shard without one
+ * counts as a whole.
+ */
+function summarizeShards(shards, perFile) {
+    const lines = shards.map(({ label, outcome }) => `${SHARD_STATUS_LABEL[outcome.verdict.kind].padEnd(8)} ${label}` +
+        (outcome.attempts > 1 ? `  (${outcome.attempts} attempts)` : ''));
+    const failingShards = shards.filter(({ outcome }) => outcome.verdict.kind !== 'tests-ran-ok');
+    let passed = shards.length - failingShards.length;
+    let total = shards.length;
+    let failed = failingShards.map(({ label }) => label);
+    if (perFile) {
+        passed = 0;
+        total = 0;
+        failed = [];
+        for (const shard of shards) {
+            const files = failedFilesOf(shard);
+            const ok = shard.outcome.verdict.kind === 'tests-ran-ok';
+            if (files === undefined) {
+                total += 1;
+                if (ok)
+                    passed += 1;
+                else
+                    failed.push(shard.label);
+                continue;
+            }
+            const dispatched = shard.paths ?? [];
+            total += dispatched.length;
+            // A red shard whose log names no failing file still failed: count
+            // every file of it, so a crash cannot read as all-green.
+            const red = files.length === 0 && !ok ? dispatched : files;
+            passed += dispatched.length - red.length;
+            failed.push(...red);
+        }
+    }
+    note(`${lines.join('\n')}\n\n${passed}/${total} ${perFile ? 'file(s)' : 'shard(s)'} passed`, 'Sharded Test Summary');
+    return { shards, passed, total, failed, 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,
+        failed: summary.failed.map((label) => label.replace(/\s+/g, '_')),
+    });
+    if (summary.passed < summary.total) {
+        throw new TestFailureError(`${summary.failed.length} of ${summary.total} sharded test run(s) did not pass: ` +
+            `${summary.failed.join(', ')}. ` +
+            'See the per-shard diagnosis above. Use --no-shard to reproduce the combined single-invocation behaviour.', 'mach test', undefined, getActiveRunLogPath());
+    }
+}
+/**
+ * Splits the dispatch paths of every group into consecutive chunks of at
+ * most `size` files (`--shard-size`). Order is kept, and a chunk never
+ * mixes groups' order: it is the flattened request, cut every `size`
+ * files.
+ */
+export function chunkShardGroups(groups, size) {
+    const paths = groups.flatMap((group) => group.paths);
+    const chunks = [];
+    for (let start = 0; start < paths.length; start += size) {
+        const chunk = paths.slice(start, start + size);
+        const first = chunk[0] ?? '';
+        chunks.push({
+            label: chunk.length === 1 ? first : `${first}+${chunk.length - 1}`,
+            paths: chunk,
+        });
+    }
+    return chunks;
+}
+/**
+ * Splits one combined request into `parts` contiguous chunks of near-equal
+ * size, in order (`--jobs` with `--no-shard`).
+ */
+export function splitContiguous(paths, parts) {
+    const count = Math.max(1, Math.min(parts, paths.length));
+    const groups = [];
+    let start = 0;
+    for (let index = 0; index < count; index += 1) {
+        const size = Math.ceil((paths.length - start) / (count - index));
+        const chunk = paths.slice(start, start + size);
+        start += size;
+        const first = chunk[0] ?? '';
+        groups.push({
+            label: chunk.length === 1 ? first : `${first}+${chunk.length - 1}`,
+            paths: chunk,
+        });
+    }
+    return groups;
+}

package/dist/src/commands/test-stale-gate.d.ts

@@ -28,7 +28,11 @@ import type { TestOptions } from '../types/commands/index.js';
  * a full-suite request would refuse a probe that touches no fixtures. The
  * stale-content refusal still applies to it unchanged.
  */
-export declare function enforceStaleBuildGate(projectRoot: string, engineDir: string, options: TestOptions, normalizedPaths: readonly string[]): Promise<void>;
+export declare function enforceStaleBuildGate(projectRoot: string, engineDir: string, options: TestOptions, normalizedPaths: readonly string[], 
+/** `quiet`: refuse only, without the exemption note (the pre-lock pass). */
+gate?: {
+    quiet?: boolean;
+}): Promise<void>;
 /**
  * Compiled-StaticComponents gate: refuses runs whose child process would
  * resolve a stale compiled component table. `components.conf` entries bake