@hominis/fireforge 0.49.1 → 0.50.0

package/dist/src/core/patch-retired.js

@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Retired order slots: the placeholders `patch retire` leaves in
+ * `patches.json#retired` so a patch can leave the queue without opening a
+ * numeric gap or renumbering its successors.
+ *
+ * A slot is not a patch. It has no `.patch` file and no row in `patches`,
+ * so everything that applies, exports, lints or rebases the queue walks past
+ * it without knowing it exists. The one reader is the
+ * `patchPolicy.allowGaps: false` gap check, which counts a retired order as
+ * occupied. A patch that later takes the same order fills the slot, and
+ * {@link carryRetiredSlots} drops it on that write, so the manifest never
+ * holds a slot and a patch at one order.
+ */
+/**
+ * The retired slots of `current` that no patch in `patches` occupies, or
+ * undefined when none remain. Every manifest write that rebuilds the
+ * `patches` list routes the slots through here, so a slot survives the
+ * rewrite and a filled one does not.
+ *
+ * @param current - Manifest the slots come from (null or slot-free: none)
+ * @param patches - The rows the written manifest will hold
+ */
+export function carryRetiredSlots(current, patches) {
+    const slots = current?.retired;
+    if (slots === undefined || slots.length === 0)
+        return undefined;
+    const occupied = new Set(patches.map((patch) => patch.order));
+    const kept = slots
+        .filter((slot) => !occupied.has(slot.order))
+        .map((slot) => ({ ...slot }))
+        .sort((a, b) => a.order - b.order);
+    return kept.length > 0 ? kept : undefined;
+}
+/**
+ * Builds a manifest from `patches` that keeps `current`'s unfilled retired
+ * slots. The `retired` key is omitted entirely when no slot remains, so a
+ * queue that never retired anything writes the same JSON as before.
+ *
+ * @param current - Manifest the slots come from
+ * @param patches - The rows the written manifest will hold
+ */
+export function manifestWithRetiredSlots(current, patches) {
+    const retired = carryRetiredSlots(current, patches);
+    return {
+        version: 1,
+        patches,
+        ...(retired !== undefined ? { retired } : {}),
+    };
+}
+/** The set of order numbers held by retired slots. */
+export function retiredOrderSet(manifest) {
+    return new Set((manifest.retired ?? []).map((slot) => slot.order));
+}

package/dist/src/core/patch-subset.d.ts

@@ -0,0 +1,16 @@
+import type { PatchesManifest, PatchMetadata } from '../types/commands/index.js';
+/**
+ * Resolves a `--patches <name…>` subset against the manifest, matching each
+ * requested name tolerantly (exact filename, filename ± `.patch`, the bare
+ * order number, the manifest `name` field, or the slug). Accepts repeated
+ * values and comma lists. Throws listing the available patches when a
+ * requested name matches none, so a typo fails loud rather than silently
+ * judging nothing.
+ *
+ * @param manifest - The loaded patch manifest
+ * @param requested - Raw `--patches` values (each may be a comma list)
+ * @param refusalHint - Sentence inserted into the no-match refusal, naming
+ *   what the caller's flag selects
+ * @returns The matching manifest rows, de-duplicated, in request order
+ */
+export declare function selectPatchSubset(manifest: PatchesManifest, requested: readonly string[], refusalHint?: string): PatchMetadata[];

package/dist/src/core/patch-subset.js

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The `--patches <name…>` subset resolver shared by `lint --per-patch`,
+ * `status` and `verify`. One matcher, so a name that selects a patch in
+ * one gate selects the same patch in the others.
+ */
+import { GeneralError } from '../errors/base.js';
+/** Every spelling an operator may use for one patch. */
+function patchAliases(p) {
+    const aliases = new Set([p.filename, p.filename.replace(/\.patch$/, ''), p.name]);
+    // The bare order number, both as the manifest records it and as the
+    // filename spells it (`2` and `002`). The refusal message offers stems,
+    // and an operator reading `102-ui-canvas-tiles.patch` in a lint finding
+    // reaches for `102` first.
+    aliases.add(String(p.order));
+    const match = /^(\d+)-([a-z]+)-(.+)\.patch$/.exec(p.filename);
+    if (match?.[1])
+        aliases.add(match[1]);
+    if (match?.[2] && match[3]) {
+        aliases.add(`${match[2]}-${match[3]}`);
+        aliases.add(match[3]);
+    }
+    return aliases;
+}
+function matchesPatch(p, name) {
+    const aliases = patchAliases(p);
+    const stem = name.replace(/\.patch$/, '');
+    return aliases.has(name) || aliases.has(stem) || aliases.has(`${stem}.patch`);
+}
+/**
+ * Resolves a `--patches <name…>` subset against the manifest, matching each
+ * requested name tolerantly (exact filename, filename ± `.patch`, the bare
+ * order number, the manifest `name` field, or the slug). Accepts repeated
+ * values and comma lists. Throws listing the available patches when a
+ * requested name matches none, so a typo fails loud rather than silently
+ * judging nothing.
+ *
+ * @param manifest - The loaded patch manifest
+ * @param requested - Raw `--patches` values (each may be a comma list)
+ * @param refusalHint - Sentence inserted into the no-match refusal, naming
+ *   what the caller's flag selects
+ * @returns The matching manifest rows, de-duplicated, in request order
+ */
+export function selectPatchSubset(manifest, requested, refusalHint = '') {
+    const normalizedRequests = requested
+        .flatMap((entry) => entry.split(','))
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+    const selected = [];
+    const seen = new Set();
+    for (const name of normalizedRequests) {
+        const found = manifest.patches.filter((p) => matchesPatch(p, name));
+        if (found.length === 0) {
+            const available = manifest.patches.map((p) => p.filename).join(', ');
+            throw new GeneralError(`No patch in the queue matches "${name}".${refusalHint ? ` ${refusalHint}` : ''} ` +
+                `Available patches: ${available}`);
+        }
+        for (const p of found) {
+            if (!seen.has(p.filename)) {
+                seen.add(p.filename);
+                selected.push(p);
+            }
+        }
+    }
+    return selected;
+}

package/dist/src/core/preflight-wait.d.ts

@@ -1,2 +1,22 @@
 /** Waits for a busy browser or port without changing or terminating its owner. */
 export declare function waitForPreflight(action: () => Promise<void>, seconds?: number): Promise<void>;
+/**
+ * Spends a `--wait-browser`/`--wait-port` budget BEFORE the engine session
+ * lock is taken, so a run queued behind a busy browser or port does not
+ * hold the lock (and every peer's build, test and re-export behind it)
+ * while it does nothing. The caller re-checks once under the lock.
+ *
+ * Never refuses on its own: when the budget runs out the run still joins
+ * the lock queue, and the single check under the lock decides. A peer's
+ * test run that holds the lock legitimately keeps its browser alive until
+ * it releases, and refusing here would turn that ordinary queue into a
+ * refusal the old in-lock wait never produced. Never terminates anything
+ * either: nothing is owned before the lock is won. A refusal whose note is
+ * in `clearNotes` (a stale browser the run is allowed to reap under the
+ * lock) counts as clear.
+ *
+ * @param action - The preflight probe, which throws `PreflightRefusalError` while busy
+ * @param seconds - The wait budget
+ * @param clearNotes - Refusal classes that do not need waiting out
+ */
+export declare function waitBeforeLock(action: () => Promise<void>, seconds: number | undefined, clearNotes?: readonly string[]): Promise<void>;

package/dist/src/core/preflight-wait.js

@@ -22,3 +22,41 @@ export async function waitForPreflight(action, seconds) {
         }
     }
 }
+/**
+ * Spends a `--wait-browser`/`--wait-port` budget BEFORE the engine session
+ * lock is taken, so a run queued behind a busy browser or port does not
+ * hold the lock (and every peer's build, test and re-export behind it)
+ * while it does nothing. The caller re-checks once under the lock.
+ *
+ * Never refuses on its own: when the budget runs out the run still joins
+ * the lock queue, and the single check under the lock decides. A peer's
+ * test run that holds the lock legitimately keeps its browser alive until
+ * it releases, and refusing here would turn that ordinary queue into a
+ * refusal the old in-lock wait never produced. Never terminates anything
+ * either: nothing is owned before the lock is won. A refusal whose note is
+ * in `clearNotes` (a stale browser the run is allowed to reap under the
+ * lock) counts as clear.
+ *
+ * @param action - The preflight probe, which throws `PreflightRefusalError` while busy
+ * @param seconds - The wait budget
+ * @param clearNotes - Refusal classes that do not need waiting out
+ */
+export async function waitBeforeLock(action, seconds, clearNotes = []) {
+    try {
+        await waitForPreflight(async () => {
+            try {
+                await action();
+            }
+            catch (error) {
+                if (error instanceof PreflightRefusalError && clearNotes.includes(error.note))
+                    return;
+                throw error;
+            }
+        }, seconds);
+    }
+    catch (error) {
+        if (!(error instanceof PreflightRefusalError))
+            throw error;
+        info(`Still busy after the ${seconds ?? 0}-second wait; joining the lock queue and re-checking once under the lock.`);
+    }
+}

package/dist/src/core/rebase-from-version.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Resolves the "from" side of a `fireforge rebase` source move.
+ *
+ * The rebase target is the working `firefox.version` pin, which
+ * `fireforge source set` has already moved. The tree the queue was last
+ * applied to is the previous pin: the `firefox` block of `fireforge.json`
+ * as committed in the project repository. Patch `sourceVersion` stamps are
+ * a poor stand-in: patches untouched since an older hop keep their older
+ * stamp, so the oldest stamp can trail the real previous tree by several
+ * releases. The stamps are only the fallback, for a project that is not a
+ * git checkout or whose committed pin already equals the target.
+ */
+import type { FirefoxProduct } from '../types/config.js';
+/** A `firefox.version` / `firefox.product` pair. */
+export interface FirefoxPin {
+    version: string;
+    product?: FirefoxProduct;
+}
+/** Where the rebase's "from" label came from. */
+export interface RebaseFromVersion extends FirefoxPin {
+    /** `committed-pin`: the project's committed `fireforge.json`; `patch-stamps`: the oldest stamp. */
+    origin: 'committed-pin' | 'patch-stamps';
+}
+/** Tally of the queue's `sourceVersion` stamps, oldest first. */
+export interface PatchStampSpread {
+    versions: string[];
+    counts: Map<string, number>;
+}
+/**
+ * Reads the `firefox` pin from `fireforge.json` as committed at the project
+ * repository's HEAD. `HEAD:./fireforge.json` resolves relative to the
+ * project root, so a project nested inside a larger repository works too.
+ * Returns `undefined` when there is no repository, no commit, no committed
+ * config, or no valid pin in it.
+ */
+export declare function readCommittedFirefoxPin(projectRoot: string): Promise<FirefoxPin | undefined>;
+/** Counts the queue's stamps and orders them semantically (a lexical sort put 153.10.0esr before 153.2.0esr). */
+export declare function tallyPatchStamps(stamps: readonly string[]): PatchStampSpread;
+/** `"317 at 153.0esr, 5 at 153.3.0esr"`. */
+export declare function formatPatchStampSpread(spread: PatchStampSpread): string;
+/**
+ * Picks the rebase's "from": the committed pin when it differs from the
+ * target, otherwise the oldest patch stamp (`oldestStampProduct` is that
+ * stamp's recorded product, when any patch carries one).
+ */
+export declare function resolveRebaseFromVersion(target: string, committed: FirefoxPin | undefined, spread: PatchStampSpread, oldestStampProduct: FirefoxProduct | undefined): RebaseFromVersion;

package/dist/src/core/rebase-from-version.js

@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Resolves the "from" side of a `fireforge rebase` source move.
+ *
+ * The rebase target is the working `firefox.version` pin, which
+ * `fireforge source set` has already moved. The tree the queue was last
+ * applied to is the previous pin: the `firefox` block of `fireforge.json`
+ * as committed in the project repository. Patch `sourceVersion` stamps are
+ * a poor stand-in: patches untouched since an older hop keep their older
+ * stamp, so the oldest stamp can trail the real previous tree by several
+ * releases. The stamps are only the fallback, for a project that is not a
+ * git checkout or whose committed pin already equals the target.
+ */
+import { exec } from '../utils/process.js';
+import { compareFirefoxVersions, isObject, isValidFirefoxProduct, isValidFirefoxVersion, } from '../utils/validation.js';
+/**
+ * Reads the `firefox` pin from `fireforge.json` as committed at the project
+ * repository's HEAD. `HEAD:./fireforge.json` resolves relative to the
+ * project root, so a project nested inside a larger repository works too.
+ * Returns `undefined` when there is no repository, no commit, no committed
+ * config, or no valid pin in it.
+ */
+export async function readCommittedFirefoxPin(projectRoot) {
+    const result = await exec('git', ['show', 'HEAD:./fireforge.json'], { cwd: projectRoot }).catch(() => undefined);
+    if (result?.exitCode !== 0)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(result.stdout);
+    }
+    catch {
+        return undefined;
+    }
+    const firefox = isObject(parsed) ? parsed['firefox'] : undefined;
+    if (!isObject(firefox))
+        return undefined;
+    const version = firefox['version'];
+    if (typeof version !== 'string' || !isValidFirefoxVersion(version))
+        return undefined;
+    const product = firefox['product'];
+    return typeof product === 'string' && isValidFirefoxProduct(product)
+        ? { version, product }
+        : { version };
+}
+/** Counts the queue's stamps and orders them semantically (a lexical sort put 153.10.0esr before 153.2.0esr). */
+export function tallyPatchStamps(stamps) {
+    const counts = new Map();
+    for (const stamp of stamps)
+        counts.set(stamp, (counts.get(stamp) ?? 0) + 1);
+    return { versions: [...counts.keys()].sort(compareFirefoxVersions), counts };
+}
+/** `"317 at 153.0esr, 5 at 153.3.0esr"`. */
+export function formatPatchStampSpread(spread) {
+    return spread.versions.map((v) => `${spread.counts.get(v)} at ${v}`).join(', ');
+}
+/**
+ * Picks the rebase's "from": the committed pin when it differs from the
+ * target, otherwise the oldest patch stamp (`oldestStampProduct` is that
+ * stamp's recorded product, when any patch carries one).
+ */
+export function resolveRebaseFromVersion(target, committed, spread, oldestStampProduct) {
+    if (committed !== undefined && committed.version !== target) {
+        return { ...committed, origin: 'committed-pin' };
+    }
+    const oldest = spread.versions[0] ?? target;
+    return {
+        version: oldest,
+        ...(oldestStampProduct !== undefined ? { product: oldestStampProduct } : {}),
+        origin: 'patch-stamps',
+    };
+}

package/dist/src/core/run-log.d.ts

@@ -43,6 +43,26 @@ export declare function getRunLogDir(projectRoot: string): string;
  * @returns The sink, or undefined when no log could be opened
  */
 export declare function openRunLog(projectRoot: string, command: string, now?: Date): Promise<RunLog | undefined>;
+/**
+ * Tees a run log into a caller-chosen copy (`--keep-log`,
+ * {@link LOG_KEEP_ENV_VAR}) that retention never prunes.
+ *
+ * `.fireforge/logs/` keeps twenty logs per command kind for EVERY session
+ * on the checkout, so on a shared checkout a log named by a verdict line
+ * can be gone within the hour, and a failure recorded only by its log path
+ * cannot be read later. The copy is written live, line for line with the
+ * same redaction, rather than copied at the end: a killed run keeps what it
+ * had written, like the primary log does.
+ *
+ * The primary path stays the one `log=` names. When the primary could not
+ * be opened the copy stands in for it.
+ *
+ * @param log - The primary run log, if one opened
+ * @param flag - The `--keep-log` value, if any
+ * @param command - Command kind, naming a copy that has no primary
+ * @returns A sink writing to both, or whichever one opened
+ */
+export declare function keepRunLogCopy(log: RunLog | undefined, flag: string | undefined, command: string): Promise<RunLog | undefined>;
 /** Installs (or clears, with `undefined`) the run log for this process. */
 export declare function setActiveRunLog(log: RunLog | undefined): void;
 /** Absolute path of the active run log, or undefined when none is open. */

package/dist/src/core/run-log.js

@@ -20,8 +20,8 @@
  * exactly the behaviour that existed before this module.
  */
 import { createWriteStream } from 'node:fs';
-import { mkdir, readdir, unlink } from 'node:fs/promises';
-import { join } from 'node:path';
+import { mkdir, readdir, stat, unlink } from 'node:fs/promises';
+import { basename as basenameOf, dirname, join, resolve } from 'node:path';
 import { Writable } from 'node:stream';
 import { toError } from '../utils/errors.js';
 import { verbose } from '../utils/logger.js';
@@ -107,11 +107,27 @@ async function pruneRunLogs(dir, command) {
  */
 export async function openRunLog(projectRoot, command, now = new Date()) {
     const dir = getRunLogDir(projectRoot);
-    let stream;
     const path = join(dir, `${command}-${fileSafeTimestamp(now)}.log`);
     try {
         await mkdir(dir, { recursive: true });
         await pruneRunLogs(dir, command);
+    }
+    catch (error) {
+        verbose(`Run log unavailable (${path}): ${toError(error).message}`);
+        return undefined;
+    }
+    return openRunLogSink(path);
+}
+/**
+ * Opens one redacting log file at `path`, creating its directory.
+ *
+ * @param path - Absolute file path
+ * @returns The sink, or undefined when the file could not be opened
+ */
+async function openRunLogSink(path) {
+    let stream;
+    try {
+        await mkdir(dirname(path), { recursive: true });
         stream = createWriteStream(path, { flags: 'a' });
     }
     catch (error) {
@@ -172,6 +188,76 @@ export async function openRunLog(projectRoot, command, now = new Date()) {
         },
     };
 }
+/** Environment variable naming where every run's log is also kept. */
+const LOG_KEEP_ENV_VAR = 'FIREFORGE_LOG_KEEP';
+/**
+ * Where a run's kept copy goes: `--keep-log <path>` when given, else
+ * {@link LOG_KEEP_ENV_VAR}, else nowhere. A value that ends in a path
+ * separator or names an existing directory receives the log under its own
+ * `.fireforge/logs/` basename, so a session-wide directory collects one
+ * file per run. Any other value is the file itself. Relative values resolve
+ * against the caller's working directory.
+ *
+ * @param flag - The `--keep-log` value, if any
+ * @param basename - The run log's own file name
+ * @returns The absolute destination, or undefined when none was asked for
+ */
+async function resolveRunLogKeepPath(flag, basename) {
+    const raw = flag ?? process.env[LOG_KEEP_ENV_VAR]?.trim();
+    if (raw === undefined || raw.length === 0)
+        return undefined;
+    const target = resolve(raw);
+    let directory = /[\\/]$/.test(raw);
+    if (!directory) {
+        try {
+            directory = (await stat(target)).isDirectory();
+        }
+        catch {
+            directory = false;
+        }
+    }
+    return directory ? join(target, basename) : target;
+}
+/**
+ * Tees a run log into a caller-chosen copy (`--keep-log`,
+ * {@link LOG_KEEP_ENV_VAR}) that retention never prunes.
+ *
+ * `.fireforge/logs/` keeps twenty logs per command kind for EVERY session
+ * on the checkout, so on a shared checkout a log named by a verdict line
+ * can be gone within the hour, and a failure recorded only by its log path
+ * cannot be read later. The copy is written live, line for line with the
+ * same redaction, rather than copied at the end: a killed run keeps what it
+ * had written, like the primary log does.
+ *
+ * The primary path stays the one `log=` names. When the primary could not
+ * be opened the copy stands in for it.
+ *
+ * @param log - The primary run log, if one opened
+ * @param flag - The `--keep-log` value, if any
+ * @param command - Command kind, naming a copy that has no primary
+ * @returns A sink writing to both, or whichever one opened
+ */
+export async function keepRunLogCopy(log, flag, command) {
+    const basename = log === undefined ? `${command}-${fileSafeTimestamp(new Date())}.log` : basenameOf(log.path);
+    const keepPath = await resolveRunLogKeepPath(flag, basename);
+    if (keepPath === undefined || keepPath === log?.path)
+        return log;
+    const copy = await openRunLogSink(keepPath);
+    if (copy === undefined)
+        return log;
+    if (log === undefined)
+        return copy;
+    return {
+        path: log.path,
+        write: (chunk) => {
+            log.write(chunk);
+            copy.write(chunk);
+        },
+        close: async () => {
+            await Promise.all([log.close(), copy.close()]);
+        },
+    };
+}
 /**
  * The run log for the command currently executing, if any.
  *

package/dist/src/core/run-profile.d.ts

@@ -17,6 +17,13 @@ export interface RunProfileRequest {
     profile?: string | undefined;
     /** `--temp-profile`: launch with a fresh directory removed afterwards. */
     tempProfile?: boolean | undefined;
+    /**
+     * Whether a named `profile` launches with `-purgecaches` (default `true`).
+     * A UI build does not change the build id the profile's startup cache is
+     * keyed on, so without it a kept profile runs the chrome scripts an
+     * earlier build cached. Temporary profiles start without a cache.
+     */
+    purgeCaches?: boolean | undefined;
     /**
      * Whether this is a `--smoke-exit` run. A smoke run with neither flag gets
      * a temporary profile: the step exists to prove what the build does on a

package/dist/src/core/run-profile.js

@@ -68,7 +68,13 @@ export async function resolveRunProfile(request) {
     }
     if (request.profile !== undefined) {
         const dir = resolve(request.profile);
-        return { args: ['-profile', dir], dir, temporary: false, dispose: NO_PROFILE.dispose };
+        const purge = request.purgeCaches === false ? [] : ['-purgecaches'];
+        return {
+            args: ['-profile', dir, ...purge],
+            dir,
+            temporary: false,
+            dispose: NO_PROFILE.dispose,
+        };
     }
     if (request.tempProfile !== true && !request.smoke) {
         return NO_PROFILE;

package/dist/src/core/smoke-patterns.d.ts

@@ -17,6 +17,11 @@
  * allowlisted hits separately from raw error matches for its summary.
  */
 export declare function matchesSmokeError(line: string): boolean;
+/**
+ * Returns `true` when `line` is console output from the browser rather than
+ * mach's own timestamped log. A blank line is neither.
+ */
+export declare function isBrowserConsoleLine(line: string): boolean;
 /**
  * One compiled allowlist entry with its provenance retained so the smoke
  * summary can attribute hits per entry. An entry that silently

package/dist/src/core/smoke-patterns.js

@@ -56,6 +56,19 @@ export function matchesSmokeError(line) {
     }
     return false;
 }
+/**
+ * Mach's own log lines carry an elapsed-time prefix (` 0:00.42 <message>`),
+ * the first of which echoes the browser command line. They prove mach ran,
+ * not that the browser printed anything.
+ */
+const MACH_LOG_LINE = /^\s*\d+:\d{2}\.\d{2} /;
+/**
+ * Returns `true` when `line` is console output from the browser rather than
+ * mach's own timestamped log. A blank line is neither.
+ */
+export function isBrowserConsoleLine(line) {
+    return line.trim() !== '' && !MACH_LOG_LINE.test(line);
+}
 /** `# max-hits: N` on its own comment line, case-insensitive. */
 const MAX_HITS_DIRECTIVE = /^#\s*max-hits:\s*(\S+)\s*$/i;
 function parseMaxHitsDirective(raw, at) {

package/dist/src/core/test-harness-crash.d.ts

@@ -22,7 +22,7 @@
  * reporting phantom test failures (or phantom passes).
  */
 export type { HarnessCrashSignature } from './test-harness-signature.js';
-import type { HarnessCrashSignature } from './test-harness-signature.js';
+import type { HarnessCrashSignature, IncompleteRunEvidence } from './test-harness-signature.js';
 export { headedDisplayAsleepVerdictNote, headedNoOutputTimeoutHint } from './test-stall-triage.js';
 /** How a completed harness run should be interpreted. */
 export type HarnessRunClassification = 'tests-ran-ok' | 'test-failures' | 'harness-crash' | 'harness-arguments' | 'no-tests';
@@ -71,6 +71,12 @@ export interface HarnessRunVerdict extends HarnessSummaryCounts {
      * only. The status and reason keys are unaffected.
      */
     note?: string;
+    /**
+     * Set when a mach-exit-0 run was refused its pass because it is
+     * incomplete or reported unexpected results. See
+     * `test-run-completeness.ts`.
+     */
+    incomplete?: IncompleteRunEvidence;
 }
 /** Why a green-looking embedded summary was not trusted. */
 export interface GreenSummaryRejection {
@@ -81,6 +87,7 @@ export interface GreenSummaryRejection {
     /** Files whose `TEST_START` has no matching end marker. */
     neverEnded: string[];
 }
+export declare const SHUTDOWN_REENTRY_PATTERN: RegExp;
 /**
  * Strips non-signal noise from captured output before crash-signature
  * matching: resource-monitor degradation warnings, and traceback blocks
@@ -108,6 +115,16 @@ export declare function findCrashMarkerLine(output: string): string | undefined;
  * Exported for direct unit testing.
  */
 export declare function hasCompletedGreenSummary(output: string): boolean;
+/** Basename shape of a mozbuild-manifest test implementation file. */
+export declare const TEST_FILE_BASENAME_PATTERN: RegExp;
+/**
+ * Start/end execution markers, both log dialects: the structured mozlog
+ * `TEST_START`/`TEST_END` pair and the human browser-chrome
+ * `TEST-START`/`TEST-OK` pair. `TEST-UNEXPECTED-*` end shapes are
+ * irrelevant here, since any such line already fails the green-summary check
+ * before completeness is consulted.
+ */
+export declare const START_MARKER_PATTERN: RegExp;
 /**
  * Cross-checks run completeness against the requested test files: every
  * requested file must produce a start marker, and every started test must

package/dist/src/core/test-harness-crash.js

@@ -76,7 +76,7 @@ const FAIL_LINE_PATTERN = /^.*\bTEST-(?!KNOWN-FAIL\b)[A-Z-]*FAIL\b.*$/gm;
  * test failure, pointing the reader at the wrong line.
  */
 const ASSERTION_LINE_PATTERN = /^.*(?:Assertion failure:|MOZ_ASSERT\(|###!!! ASSERTION).*$/gm;
-const SHUTDOWN_REENTRY_PATTERN = /Application shut down \(without crashing\) in the middle of a test/i;
+export const SHUTDOWN_REENTRY_PATTERN = /Application shut down \(without crashing\) in the middle of a test/i;
 const FOCUS_STALL_PATTERN = /must wait for focus/i;
 const TRACEBACK_PATTERN = /Traceback \(most recent call last\)/;
 const NO_OUTPUT_TIMEOUT_PATTERN = /timed out after \d+ seconds with no output/i;
@@ -248,7 +248,7 @@ export function hasCompletedGreenSummary(output) {
     return hasGreenShapedSummary(output) && findCrashMarkerLine(output) === undefined;
 }
 /** Basename shape of a mozbuild-manifest test implementation file. */
-const TEST_FILE_BASENAME_PATTERN = /^(?:browser|test)_.*\.m?js$/;
+export const TEST_FILE_BASENAME_PATTERN = /^(?:browser|test)_.*\.m?js$/;
 /**
  * Start/end execution markers, both log dialects: the structured mozlog
  * `TEST_START`/`TEST_END` pair and the human browser-chrome
@@ -256,7 +256,7 @@ const TEST_FILE_BASENAME_PATTERN = /^(?:browser|test)_.*\.m?js$/;
  * irrelevant here, since any such line already fails the green-summary check
  * before completeness is consulted.
  */
-const START_MARKER_PATTERN = /\bTEST[-_]START\b[:| ]*\s*(\S+)?/;
+export const START_MARKER_PATTERN = /\bTEST[-_]START\b[:| ]*\s*(\S+)?/;
 const END_MARKER_PATTERN = /\bTEST[-_]END\b|\bTEST-OK\b/;
 /**
  * Cross-checks run completeness against the requested test files: every
@@ -660,12 +660,14 @@ export function formatFireforgeVerdictLine(verdict, shards) {
     const counts = (verdict.checks !== undefined ? ` checks=${verdict.checks}` : '') +
         (verdict.unexpected !== undefined ? ` unexpected=${verdict.unexpected}` : '');
     const shardSuffix = shards ? ` shards=${shards.passed}/${shards.total}` : '';
+    const { started: n, requested: m, firstUnstarted: first } = verdict.incomplete ?? {};
+    const truncation = first === undefined ? '' : ` started=${n}/${m} first-unstarted=${first}`;
     const note = verdict.note !== undefined ? ` (${verdict.note})` : '';
     if (verdict.kind === 'tests-ran-ok') {
         return `FIREFORGE-VERDICT: PASS${counts}${shardSuffix}${note}`;
     }
     const reason = verdict.kind === 'harness-crash' ? 'crash' : verdict.kind;
-    return `FIREFORGE-VERDICT: FAIL reason=${reason}${counts}${shardSuffix}${note}`;
+    return `FIREFORGE-VERDICT: FAIL reason=${reason}${counts}${truncation}${shardSuffix}${note}`;
 }
 /**
  * Builds the operator-facing failure message for a green-looking summary

package/dist/src/core/test-harness-signature.d.ts

@@ -8,6 +8,10 @@
  * graph rather than the emitted code, and a shared leaf is a truer
  * description of the relationship than either direction of the cycle was:
  * neither module owns this type more than the other.
+ *
+ * {@link IncompleteRunEvidence} lives here for the same reason:
+ * `test-run-completeness.ts` produces it from helpers in
+ * `test-harness-crash.ts`, whose verdict type carries it.
  */
 /** A recognized harness-crash shape with its evidence line. */
 export interface HarnessCrashSignature {
@@ -16,3 +20,16 @@ export interface HarnessCrashSignature {
     /** The concrete output line the recognition was based on. */
     line: string;
 }
+/** Why an exit-0 run that would have read as a pass was failed instead. */
+export interface IncompleteRunEvidence {
+    /** Requested test files that produced a start (or skip) marker. */
+    started: number;
+    /** Requested test files the run could account for (test-file-shaped paths). */
+    requested: number;
+    /** First requested file, in dispatch order, that never started. */
+    firstUnstarted?: string;
+    /** The harness's "shut down in the middle of a test" line, when present. */
+    shutdownLine?: string;
+    /** The summary's non-zero `Unexpected results:` count, when it printed one. */
+    unexpected?: number;
+}

package/dist/src/core/test-harness-signature.js

@@ -9,5 +9,9 @@
  * graph rather than the emitted code, and a shared leaf is a truer
  * description of the relationship than either direction of the cycle was:
  * neither module owns this type more than the other.
+ *
+ * {@link IncompleteRunEvidence} lives here for the same reason:
+ * `test-run-completeness.ts` produces it from helpers in
+ * `test-harness-crash.ts`, whose verdict type carries it.
  */
 export {};