@hominis/fireforge 0.49.2 → 0.51.0

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.
  *
@@ -185,9 +271,20 @@ export async function openRunLog(projectRoot, command, now = new Date()) {
  * One command runs per process, so a single slot is the whole lifetime.
  */
 let activeRunLog;
+/** Newlines written to the active log so far, for line references into it. */
+let activeRunLogNewlines = 0;
 /** Installs (or clears, with `undefined`) the run log for this process. */
 export function setActiveRunLog(log) {
     activeRunLog = log;
+    activeRunLogNewlines = 0;
+}
+/**
+ * The 1-based line of the active run log the next write starts on.
+ * Redaction rewrites within a line and never adds or drops one, so the
+ * number holds for the file on disk.
+ */
+export function activeRunLogLine() {
+    return activeRunLogNewlines + 1;
 }
 /** Absolute path of the active run log, or undefined when none is open. */
 export function getActiveRunLogPath() {
@@ -195,7 +292,12 @@ export function getActiveRunLogPath() {
 }
 /** Appends to the active run log. A no-op when none is open. */
 export function writeToActiveRunLog(chunk) {
-    activeRunLog?.write(chunk);
+    if (activeRunLog === undefined)
+        return;
+    for (let index = chunk.indexOf('\n'); index !== -1; index = chunk.indexOf('\n', index + 1)) {
+        activeRunLogNewlines += 1;
+    }
+    activeRunLog.write(chunk);
 }
 /**
  * Closes and clears the active run log. Resolves even when none is open.

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, type 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
@@ -181,6 +198,7 @@ export declare function extractSummaryCounts(output: string): HarnessSummaryCoun
 export declare function formatFireforgeVerdictLine(verdict: HarnessRunVerdict, shards?: {
     passed: number;
     total: number;
+    failed?: readonly string[];
 }): string;
 /**
  * Builds the operator-facing failure message for a green-looking summary

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

@@ -25,6 +25,7 @@
 import { hasKnownTeardownNoise } from './mach-known-noise-filter.js';
 import { truncateEvidence, unmarkedFailureEvidenceNote, } from './test-harness-verdict-notes.js';
 import { classifyProfileArgumentFailure } from './test-profile-files.js';
+import { formatIncompleteSuffix, formatShardsSuffix, } from './test-harness-signature.js';
 // The no-output-stall triage text lives in `test-stall-triage.ts` (it is
 // operator advice, not classification) and is re-exported here so the
 // command layer keeps importing its harness diagnostics from one module.
@@ -76,7 +77,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 +249,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 +257,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
@@ -659,13 +660,11 @@ function lastCapturedCount(output, pattern) {
 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 note = verdict.note !== undefined ? ` (${verdict.note})` : '';
-    if (verdict.kind === 'tests-ran-ok') {
-        return `FIREFORGE-VERDICT: PASS${counts}${shardSuffix}${note}`;
-    }
+    const tail = `${formatShardsSuffix(shards)}${verdict.note !== undefined ? ` (${verdict.note})` : ''}`;
+    if (verdict.kind === 'tests-ran-ok')
+        return `FIREFORGE-VERDICT: PASS${counts}${tail}`;
     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}${formatIncompleteSuffix(verdict.incomplete)}${tail}`;
 }
 /**
  * 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,32 @@ export interface HarnessCrashSignature {
     /** The concrete output line the recognition was based on. */
     line: string;
 }
+/**
+ * The verdict line's `started=<n>/<m> first-unstarted=<path>
+ * [started-source=<src>]` keys, or nothing when every file started.
+ */
+export declare function formatIncompleteSuffix(evidence: IncompleteRunEvidence | undefined): string;
+/** The verdict line's `shards=<p>/<t> [failed-shards=<labels>]` keys of a sharded run. */
+export declare function formatShardsSuffix(shards: {
+    passed: number;
+    total: number;
+    failed?: readonly string[];
+} | undefined): 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;
+    /**
+     * Which evidence the start count came from, stamped with a short count:
+     * the structured raw log, the streamed output, or the capped capture.
+     */
+    startedSource?: 'raw' | 'stream' | 'capture';
+    /** 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,27 @@
  * 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.
+ */
+/**
+ * The verdict line's `started=<n>/<m> first-unstarted=<path>
+ * [started-source=<src>]` keys, or nothing when every file started.
  */
-export {};
+export function formatIncompleteSuffix(evidence) {
+    if (evidence?.firstUnstarted === undefined)
+        return '';
+    const source = evidence.startedSource === undefined ? '' : ` started-source=${evidence.startedSource}`;
+    return ` started=${evidence.started}/${evidence.requested} first-unstarted=${evidence.firstUnstarted}${source}`;
+}
+/** The verdict line's `shards=<p>/<t> [failed-shards=<labels>]` keys of a sharded run. */
+export function formatShardsSuffix(shards) {
+    if (shards === undefined)
+        return '';
+    const failed = shards.failed !== undefined && shards.failed.length > 0
+        ? ` failed-shards=${shards.failed.join(',')}`
+        : '';
+    return ` shards=${shards.passed}/${shards.total}${failed}`;
+}

package/dist/src/core/test-raw-log.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The mozlog structured ("raw") log of one mach test dispatch.
+ *
+ * Everything else FireForge reads from a run is human text: the
+ * `TEST_START`/`TEST_END` lines and the `Unexpected results:` summary, in two
+ * dialects, out of a capture that keeps only its last 2 MB. A gate that
+ * wants to name the files a run failed had to regex that text, and agent-
+ * quiet mozbuild drops `TEST_START` from it altogether. The raw log is the
+ * record the summary itself is computed from: one JSON object per line,
+ * with `test_start`, `test_status` and `test_end` actions naming each test
+ * by its manifest id.
+ *
+ * It is requested per dispatch with mozlog's `--log-raw=<path>`, which
+ * `mach test`, `mach mochitest` and `mach xpcshell-test` all accept, only
+ * when a run asks for per-file results (`--results`, `--shard-size`).
+ */
+import type { StartMarkers } from './test-run-completeness.js';
+/** One test file's outcome, from its `test_end` and failing `test_status` records. */
+export interface RawTestResult {
+    /** The test id mozlog reports (a manifest-relative path). */
+    test: string;
+    /** `test_end` status (`OK`, `PASS`, `FAIL`, `ERROR`, `TIMEOUT`, `CRASH`, `SKIP`). */
+    status: string;
+    /** Expected status; equal to `status` when mozlog omitted it. */
+    expected: string;
+    /** True when the file ended unexpectedly or any subtest did. */
+    unexpected: boolean;
+    /** Subtests that reported an unexpected status. */
+    unexpectedSubtests: number;
+    /** Wall time between `test_start` and `test_end`, when both carried a time. */
+    durationMs?: number;
+}
+/** Everything one raw log says about the run. */
+export interface RawTestLog {
+    /** Files in `test_end` order. A started file with no end is not listed. */
+    results: RawTestResult[];
+    /** Start markers for the completeness veto: every `test_start` id. */
+    markers: StartMarkers;
+    /** Started tests that never ended (a crash or a cut-off run). */
+    unfinished: string[];
+}
+/**
+ * Parses a mozlog raw log. Unknown actions and malformed lines are skipped,
+ * so a log truncated by a crash still yields the files that finished.
+ *
+ * @param text - The raw log's contents
+ */
+export declare function parseRawTestLog(text: string): RawTestLog;
+/**
+ * Reads and parses a raw log. Returns undefined when the file is missing or
+ * unreadable (the harness never started, or the engine's mach ignored the
+ * flag), so callers fall back to the streamed text.
+ *
+ * @param path - The `--log-raw` destination
+ */
+export declare function readRawTestLog(path: string): Promise<RawTestLog | undefined>;
+/**
+ * The `--log-raw` destination the operator already forwarded with
+ * `--mach-arg`, when it names a file. FireForge then reads that file instead
+ * of adding its own flag, so the operator's log is not replaced.
+ *
+ * @param args - The dispatch's extra mach arguments
+ */
+export declare function forwardedRawLogPath(args: readonly string[]): string | undefined;
+/** True when the dispatch arguments already carry any `--log-raw`. */
+export declare function hasForwardedRawLog(args: readonly string[]): boolean;

package/dist/src/core/test-raw-log.js

@@ -0,0 +1,122 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The mozlog structured ("raw") log of one mach test dispatch.
+ *
+ * Everything else FireForge reads from a run is human text: the
+ * `TEST_START`/`TEST_END` lines and the `Unexpected results:` summary, in two
+ * dialects, out of a capture that keeps only its last 2 MB. A gate that
+ * wants to name the files a run failed had to regex that text, and agent-
+ * quiet mozbuild drops `TEST_START` from it altogether. The raw log is the
+ * record the summary itself is computed from: one JSON object per line,
+ * with `test_start`, `test_status` and `test_end` actions naming each test
+ * by its manifest id.
+ *
+ * It is requested per dispatch with mozlog's `--log-raw=<path>`, which
+ * `mach test`, `mach mochitest` and `mach xpcshell-test` all accept, only
+ * when a run asks for per-file results (`--results`, `--shard-size`).
+ */
+import { readFile } from 'node:fs/promises';
+function parseRecord(line) {
+    if (!line.startsWith('{'))
+        return undefined;
+    try {
+        const parsed = JSON.parse(line);
+        return typeof parsed === 'object' && parsed !== null ? parsed : undefined;
+    }
+    catch {
+        // A line cut off by a killed harness is not a record.
+        return undefined;
+    }
+}
+/**
+ * Parses a mozlog raw log. Unknown actions and malformed lines are skipped,
+ * so a log truncated by a crash still yields the files that finished.
+ *
+ * @param text - The raw log's contents
+ */
+export function parseRawTestLog(text) {
+    const results = [];
+    const started = [];
+    const startTimes = new Map();
+    const subtestFailures = new Map();
+    for (const line of text.split(/\r?\n/)) {
+        const record = parseRecord(line.trim());
+        if (record === undefined || typeof record.test !== 'string')
+            continue;
+        const test = record.test;
+        if (record.action === 'test_start') {
+            started.push(test);
+            if (typeof record.time === 'number')
+                startTimes.set(test, record.time);
+            continue;
+        }
+        if (record.action === 'test_status' && typeof record.expected === 'string') {
+            // mozlog sets `expected` on a status record only when it differs.
+            subtestFailures.set(test, (subtestFailures.get(test) ?? 0) + 1);
+            continue;
+        }
+        if (record.action !== 'test_end' || typeof record.status !== 'string')
+            continue;
+        const expected = typeof record.expected === 'string' ? record.expected : record.status;
+        const unexpectedSubtests = subtestFailures.get(test) ?? 0;
+        const start = startTimes.get(test);
+        results.push({
+            test,
+            status: record.status,
+            expected,
+            unexpected: expected !== record.status || unexpectedSubtests > 0,
+            unexpectedSubtests,
+            ...(start !== undefined && typeof record.time === 'number'
+                ? { durationMs: record.time - start }
+                : {}),
+        });
+    }
+    const ended = new Set(results.map((result) => result.test));
+    return {
+        results,
+        markers: {
+            started,
+            skipped: results.filter((r) => r.status === 'SKIP').map((r) => r.test),
+        },
+        unfinished: started.filter((test) => !ended.has(test)),
+    };
+}
+/**
+ * Reads and parses a raw log. Returns undefined when the file is missing or
+ * unreadable (the harness never started, or the engine's mach ignored the
+ * flag), so callers fall back to the streamed text.
+ *
+ * @param path - The `--log-raw` destination
+ */
+export async function readRawTestLog(path) {
+    try {
+        return parseRawTestLog(await readFile(path, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The `--log-raw` destination the operator already forwarded with
+ * `--mach-arg`, when it names a file. FireForge then reads that file instead
+ * of adding its own flag, so the operator's log is not replaced.
+ *
+ * @param args - The dispatch's extra mach arguments
+ */
+export function forwardedRawLogPath(args) {
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index] ?? '';
+        const value = arg.startsWith('--log-raw=')
+            ? arg.slice('--log-raw='.length)
+            : arg === '--log-raw'
+                ? args[index + 1]
+                : undefined;
+        if (value !== undefined)
+            return value === '-' ? undefined : value;
+    }
+    return undefined;
+}
+/** True when the dispatch arguments already carry any `--log-raw`. */
+export function hasForwardedRawLog(args) {
+    return args.some((arg) => arg === '--log-raw' || arg.startsWith('--log-raw='));
+}