@hominis/fireforge 0.40.0 → 0.42.0

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

@@ -10,14 +10,6 @@
  * warning (e.g. `"pending JavaScript error cleanup"`) do not start with
  * the prefix and should not trip the scanner.
  */
-/**
- * Line prefixes that signal an actual runtime error in a Firefox chrome
- * process. A hit on any of these patterns is a smoke failure unless the
- * line also matches the caller-supplied allowlist.
- *
- * Additions here should be conservative — false positives turn every
- * smoke run into noise for operators and every CI run into flake.
- */
 export declare const SMOKE_ERROR_PATTERNS: readonly RegExp[];
 /**
  * Returns `true` when `line` matches any pattern in

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

@@ -19,6 +19,7 @@
  * Additions here should be conservative — false positives turn every
  * smoke run into noise for operators and every CI run into flake.
  */
+import { toError } from '../utils/errors.js';
 export const SMOKE_ERROR_PATTERNS = [
     // Firefox chrome error lines — `JavaScript error: chrome://…, line N: TypeError: …`.
     /^\s*JavaScript error:/i,
@@ -79,7 +80,7 @@ export function compileAllowlistFromFile(body, sourcePath) {
             });
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
+            const message = toError(error).message;
             throw new Error(`Invalid allowlist regex at ${sourcePath}:${String(index + 1)}: ${message}`, {
                 cause: error,
             });
@@ -102,7 +103,7 @@ export function compileAllowlistFromStrings(sources) {
             });
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
+            const message = toError(error).message;
             throw new Error(`Invalid --console-allow regex at position ${String(index + 1)} ("${source}"): ${message}`, { cause: error });
         }
     });

package/dist/src/core/status-binary.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Binary-aware drift classification for patch-owned files (FORGE J3).
+ *
+ * The text classifier compares utf-8 decoded content against
+ * `computePatchedContent`, which cannot apply `GIT binary patch` bodies —
+ * so a binary file exported into a patch classified as `patch-owned-drift`
+ * forever, keeping the engine-clean gate permanently red with nothing
+ * actually un-durable. Binary sections DO carry the ground truth, though:
+ * `git diff --binary` always records full blob hashes on the section's
+ * `index <old>..<new>` line. Comparing the live file's `git hash-object`
+ * against the last owning section's new-side hash settles the
+ * classification exactly. Bodies without a usable hash (hand-written
+ * diffs, `Binary files … differ`) classify as `binary-unsupported` —
+ * an honest "cannot compare" instead of a false "not durable".
+ *
+ * Lives in its own module (not `status-classify.ts`) so the classifier
+ * stays within the per-file line budget and this module never has to
+ * import it back (dpdm-clean: the dependency edge points one way).
+ */
+import type { PatchedContentContext } from './patch-apply.js';
+/** Batched patch lookup, injected by callers that classify many files. */
+export type AffectingPatchLookup = Pick<PatchedContentContext, 'getAffectingPatches' | 'readPatchBody'>;
+/**
+ * Classification result for a binary comparison. Structurally assignable
+ * to `ClassifiedFile` without importing it (which would create a cycle
+ * with `status-classify.ts`).
+ */
+export interface BinaryClassifiedFile {
+    status: string;
+    file: string;
+    classification: 'patch-backed' | 'furnace' | 'patch-owned-drift' | 'binary-unsupported';
+    owner: string;
+}
+/**
+ * Classifies a single-owner file whose comparison is binary. Returns
+ * `null` when the comparison is NOT binary — the live file is text and
+ * (for deletions) the owning section is text — so the caller falls
+ * through to the existing utf-8 content comparison unchanged.
+ *
+ * @param args.fileMissing - True when the porcelain status reports the
+ *   file deleted (there are no live bytes to probe or hash).
+ */
+export declare function classifyBinaryOwnedFile(args: {
+    entry: {
+        status: string;
+        file: string;
+    };
+    engineDir: string;
+    patchesDir: string;
+    matchClassification: 'patch-backed' | 'furnace';
+    owner: string;
+    fileMissing?: boolean;
+    /** Batched lookup; when absent, falls back to per-file manifest queries. */
+    lookup?: AffectingPatchLookup;
+}): Promise<BinaryClassifiedFile | null>;

package/dist/src/core/status-binary.js

@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Binary-aware drift classification for patch-owned files (FORGE J3).
+ *
+ * The text classifier compares utf-8 decoded content against
+ * `computePatchedContent`, which cannot apply `GIT binary patch` bodies —
+ * so a binary file exported into a patch classified as `patch-owned-drift`
+ * forever, keeping the engine-clean gate permanently red with nothing
+ * actually un-durable. Binary sections DO carry the ground truth, though:
+ * `git diff --binary` always records full blob hashes on the section's
+ * `index <old>..<new>` line. Comparing the live file's `git hash-object`
+ * against the last owning section's new-side hash settles the
+ * classification exactly. Bodies without a usable hash (hand-written
+ * diffs, `Binary files … differ`) classify as `binary-unsupported` —
+ * an honest "cannot compare" instead of a false "not durable".
+ *
+ * Lives in its own module (not `status-classify.ts`) so the classifier
+ * stays within the per-file line budget and this module never has to
+ * import it back (dpdm-clean: the dependency edge points one way).
+ */
+import { join } from 'node:path';
+import { toError } from '../utils/errors.js';
+import { readText } from '../utils/fs.js';
+import { verbose } from '../utils/logger.js';
+import { hashObjectBatch, isBinaryFile } from './git-file-ops.js';
+import { findPatchesAffectingFile } from './patch-manifest.js';
+import { parseDiffSections } from './patch-parse.js';
+/** Finds the LAST diff section affecting `file` across the owning patches, in queue order. */
+async function findLastAffectingSection(patchesDir, file, lookup) {
+    // The lookup shares one manifest load + memoized body reads across the
+    // whole classification batch; the fallback keeps single-file callers
+    // (and existing direct tests) working without a context.
+    const patches = lookup !== undefined
+        ? lookup.getAffectingPatches(file)
+        : (await findPatchesAffectingFile(patchesDir, file)).map(({ patch }) => patch);
+    let last;
+    for (const patch of patches) {
+        const body = lookup !== undefined ? await lookup.readPatchBody(patch) : await readText(patch.path);
+        for (const section of parseDiffSections(body)) {
+            if (section.targetPath === file || section.sourcePath === file) {
+                last = section;
+            }
+        }
+    }
+    return last;
+}
+/**
+ * Classifies a single-owner file whose comparison is binary. Returns
+ * `null` when the comparison is NOT binary — the live file is text and
+ * (for deletions) the owning section is text — so the caller falls
+ * through to the existing utf-8 content comparison unchanged.
+ *
+ * @param args.fileMissing - True when the porcelain status reports the
+ *   file deleted (there are no live bytes to probe or hash).
+ */
+export async function classifyBinaryOwnedFile(args) {
+    const { entry, engineDir, patchesDir, matchClassification, owner } = args;
+    const fileMissing = args.fileMissing === true;
+    const unsupported = () => ({
+        ...entry,
+        classification: 'binary-unsupported',
+        owner,
+    });
+    // Until the comparison is KNOWN to be binary, every failure defers to
+    // the existing text path (`return null`) — classifying a text file as
+    // `binary-unsupported` because a probe failed would hide real drift.
+    let section;
+    try {
+        if (!fileMissing) {
+            const liveBinary = await isBinaryFile(engineDir, entry.file);
+            if (!liveBinary)
+                return null;
+        }
+        section = await findLastAffectingSection(patchesDir, entry.file, args.lookup);
+    }
+    catch (error) {
+        if (fileMissing)
+            return null;
+        verbose(`Classifying ${entry.file} as binary-unsupported because the binary probe failed: ${toError(error).message}`);
+        return unsupported();
+    }
+    try {
+        if (section === undefined) {
+            // Claimed in filesAffected but no diff section touches the file.
+            // A missing file keeps the existing deletion logic; a live binary
+            // has nothing recorded to compare against.
+            return fileMissing ? null : unsupported();
+        }
+        if (!section.isBinary) {
+            // Text section: deletions settle fine through the text path; a
+            // live binary against a text body has no comparable recording.
+            return fileMissing ? null : unsupported();
+        }
+        if (section.isDeletedFile) {
+            return {
+                ...entry,
+                classification: fileMissing ? matchClassification : 'patch-owned-drift',
+                owner,
+            };
+        }
+        if (fileMissing) {
+            // The last binary section expects the file to exist.
+            return { ...entry, classification: 'patch-owned-drift', owner };
+        }
+        if (section.indexNewHash !== undefined) {
+            const fullPath = join(engineDir, entry.file);
+            const live = (await hashObjectBatch(engineDir, [fullPath])).get(fullPath);
+            if (live !== undefined) {
+                // Prefix-compare: recorded hashes may be abbreviated (≥7 chars).
+                const matches = live.startsWith(section.indexNewHash) || section.indexNewHash.startsWith(live);
+                return {
+                    ...entry,
+                    classification: matches ? matchClassification : 'patch-owned-drift',
+                    owner,
+                };
+            }
+        }
+        return unsupported();
+    }
+    catch (error) {
+        verbose(`Classifying ${entry.file} as binary-unsupported because the binary comparison failed: ${toError(error).message}`);
+        return unsupported();
+    }
+}

package/dist/src/core/status-classify.d.ts

@@ -34,8 +34,13 @@
  *   cross-patch conflicts silently rolled into the `unmanaged` bucket
  *   in `--json`, which misled scripts built on top of the JSON view
  *   into treating the file as routine local drift.
+ * - `binary-unsupported`: the file's comparison is binary and the owning
+ *   patch body records no usable blob hash to compare against — an
+ *   honest "binary — comparison unsupported" instead of a permanent
+ *   false `patch-owned-drift`. Deliberately NOT in the default
+ *   `--check` fail set; opt in with `--fail-on binary-unsupported`.
  */
-export type FileClassification = 'patch-backed' | 'patch-owned-drift' | 'unmanaged' | 'branding' | 'furnace' | 'conflict';
+export type FileClassification = 'patch-backed' | 'patch-owned-drift' | 'unmanaged' | 'branding' | 'furnace' | 'conflict' | 'binary-unsupported';
 export interface StatusFile {
     status: string;
     file: string;

package/dist/src/core/status-classify.js

@@ -7,12 +7,13 @@
  * under the per-file line budget as the number of buckets grows.
  */
 import { join } from 'node:path';
+import { mapWithConcurrency } from '../utils/concurrency.js';
 import { toError } from '../utils/errors.js';
 import { readText } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
 import { isBrandingManagedPath } from './branding.js';
-import { computePatchedContent } from './patch-apply.js';
-import { loadPatchesManifest } from './patch-manifest.js';
+import { createPatchedContentContext } from './patch-apply.js';
+import { classifyBinaryOwnedFile } from './status-binary.js';
 /**
  * Builds the file → owning-patch-filenames multimap from manifest rows.
  * Single source of truth for cross-patch claim detection — status
@@ -71,10 +72,27 @@ export function isGeneratedBrandingPath(file, binaryName) {
  * deletion the patch does not expect, or a failed comparison) reports
  * `patch-owned-drift`.
  */
-async function classifySingleOwnerFile(entry, engineDir, patchesDir, matchClassification, owner) {
+async function classifySingleOwnerFile(entry, engineDir, patchesDir, matchClassification, owner, ctx) {
+    // Binary comparisons cannot go through the utf-8 content path below —
+    // binary patch bodies parse to zero hunks, so the patched-content
+    // computation returned HEAD content unchanged and the comparison
+    // reported `patch-owned-drift` forever (FORGE J3). Settle by blob hash,
+    // or classify explicitly as `binary-unsupported` when no hash exists.
+    const binaryResult = await classifyBinaryOwnedFile({
+        entry,
+        engineDir,
+        patchesDir,
+        matchClassification,
+        owner,
+        fileMissing: getPrimaryStatusCode(entry.status) === 'D',
+        lookup: ctx,
+    });
+    if (binaryResult !== null) {
+        return binaryResult;
+    }
     if (getPrimaryStatusCode(entry.status) === 'D') {
         // Deleted file: content matches only if the patch expects deletion
-        const expected = await computePatchedContent(patchesDir, engineDir, entry.file);
+        const expected = await ctx.computePatched(entry.file);
         return {
             ...entry,
             classification: expected === null ? matchClassification : 'patch-owned-drift',
@@ -84,7 +102,7 @@ async function classifySingleOwnerFile(entry, engineDir, patchesDir, matchClassi
     // File exists on disk — compare actual vs expected
     try {
         const [expected, actual] = await Promise.all([
-            computePatchedContent(patchesDir, engineDir, entry.file),
+            ctx.computePatched(entry.file),
             readText(join(engineDir, entry.file)),
         ]);
         return {
@@ -112,7 +130,11 @@ async function classifySingleOwnerFile(entry, engineDir, patchesDir, matchClassi
  * machine consumers about the nature of the drift.
  */
 export async function classifyFiles(files, engineDir, patchesDir, binaryName, furnacePrefixes) {
-    const manifest = await loadPatchesManifest(patchesDir);
+    // One manifest load + patch discovery + memoized body reads for the
+    // whole batch — the previous per-file computation re-ran all three for
+    // every dirty file (O(dirtyFiles × patches) redundant IO on a broad
+    // engine edit session, FORGE K1).
+    const ctx = await createPatchedContentContext(patchesDir, engineDir);
     // Build a multimap from file path → list of claiming patch
     // filenames so we can detect cross-patch ownership conflicts. The
     // previous `Set<string>` captured only whether a path was claimed,
@@ -120,75 +142,81 @@ export async function classifyFiles(files, engineDir, patchesDir, binaryName, fu
     // branch where the expected-vs-actual content comparison then routed
     // them into `unmanaged` when the content didn't match either owner's
     // expectation.
-    const patchClaims = manifest ? buildPatchClaims(manifest.patches) : new Map();
-    const results = [];
-    for (const entry of files) {
-        const owners = patchClaims.get(entry.file);
-        const primaryCode = getPrimaryStatusCode(entry.status);
-        // Branding paths are tool-managed for generated edits, but a brand-new
-        // unowned branding asset must not disappear from `status --unmanaged`.
-        // The Hominis Firefox 152 side-grade added Assets.car under the active
-        // branding tree; classifying every branding path before checking
-        // ownership hid that new patch candidate as "branding" even though no
-        // patch claimed it yet.
-        const isUnownedNewFile = owners === undefined && (primaryCode === '?' || primaryCode === 'A');
-        if (isBrandingManagedPath(entry.file, binaryName) &&
-            (!isUnownedNewFile || isGeneratedBrandingPath(entry.file, binaryName))) {
-            results.push({ ...entry, classification: 'branding' });
-            continue;
-        }
-        // Furnace-managed component paths
-        if (furnacePrefixes.size > 0) {
-            let isFurnace = false;
-            for (const prefix of furnacePrefixes) {
-                if (entry.file.startsWith(prefix)) {
-                    isFurnace = true;
-                    break;
-                }
-            }
-            if (isFurnace) {
-                // A furnace path claimed by exactly one patch gets the same
-                // expected-vs-actual comparison as any other single-owner path:
-                // after a `furnace deploy` of an edited component the deployed
-                // copy has content the owning patch's body lacks, and the old
-                // unconditional short-circuit silently bucketed that drift as
-                // `furnace`. Multi-owner and unowned furnace paths keep the
-                // short-circuit — the ownership table independently flags
-                // filesAffected conflicts.
-                if (owners && owners.length === 1 && owners[0] !== undefined) {
-                    results.push(await classifySingleOwnerFile(entry, engineDir, patchesDir, 'furnace', owners[0]));
-                }
-                else {
-                    results.push({ ...entry, classification: 'furnace' });
-                }
-                continue;
+    const patchClaims = buildPatchClaims(ctx.manifestPatches);
+    const deps = {
+        engineDir,
+        patchesDir,
+        binaryName,
+        furnacePrefixes,
+        patchClaims,
+        ctx,
+    };
+    // Bounded pool over per-file classification (each single-owner file
+    // spawns git); order preserved by the mapper. Per-file failures settle
+    // inside classifySingleOwnerFile's catch, so one bad file never rejects
+    // the batch.
+    return mapWithConcurrency(files, CLASSIFY_CONCURRENCY, (entry) => classifyEntry(entry, deps));
+}
+/** Concurrency bound for per-file classification (matches import's guard). */
+const CLASSIFY_CONCURRENCY = 8;
+/** Classifies one status entry; extracted so the pool worker stays flat. */
+async function classifyEntry(entry, deps) {
+    const { engineDir, patchesDir, binaryName, furnacePrefixes, patchClaims, ctx } = deps;
+    const owners = patchClaims.get(entry.file);
+    const primaryCode = getPrimaryStatusCode(entry.status);
+    // Ownership is a structural invariant and takes precedence over the
+    // content-management bucket. Otherwise a branding/Furnace prefix hides a
+    // multi-patch claim from status --check/--json even though --ownership
+    // reports the same path as CONFLICT.
+    if (owners && owners.length >= 2) {
+        return {
+            ...entry,
+            classification: 'conflict',
+            claimedBy: [...owners],
+        };
+    }
+    // Branding paths are tool-managed for generated edits, but a brand-new
+    // unowned branding asset must not disappear from `status --unmanaged`.
+    // The Hominis Firefox 152 side-grade added Assets.car under the active
+    // branding tree; classifying every branding path before checking
+    // ownership hid that new patch candidate as "branding" even though no
+    // patch claimed it yet.
+    const isUnownedNewFile = owners === undefined && (primaryCode === '?' || primaryCode === 'A');
+    if (isBrandingManagedPath(entry.file, binaryName) &&
+        (!isUnownedNewFile || isGeneratedBrandingPath(entry.file, binaryName))) {
+        return { ...entry, classification: 'branding' };
+    }
+    // Furnace-managed component paths
+    if (furnacePrefixes.size > 0) {
+        let isFurnace = false;
+        for (const prefix of furnacePrefixes) {
+            if (entry.file.startsWith(prefix)) {
+                isFurnace = true;
+                break;
             }
         }
-        // Multiple patches claim this file — surface the cross-patch
-        // ownership conflict regardless of whether the current content
-        // matches any single claim. `--ownership` reports the same state
-        // as `CONFLICT`; `--json` must agree so machine consumers of the
-        // two views see the same truth.
-        if (owners && owners.length >= 2) {
-            results.push({
-                ...entry,
-                classification: 'conflict',
-                claimedBy: [...owners],
-            });
-            continue;
-        }
-        // Not in any patch → unmanaged
-        if (!owners) {
-            results.push({ ...entry, classification: 'unmanaged' });
-            continue;
-        }
-        // File is claimed by exactly one patch — compare content.
-        const owner = owners[0];
-        if (owner === undefined) {
-            results.push({ ...entry, classification: 'unmanaged' });
-            continue;
+        if (isFurnace) {
+            // A furnace path claimed by exactly one patch gets the same
+            // expected-vs-actual comparison as any other single-owner path:
+            // after a `furnace deploy` of an edited component the deployed
+            // copy has content the owning patch's body lacks, and the old
+            // unconditional short-circuit silently bucketed that drift as
+            // `furnace`. Multi-owner and unowned furnace paths keep the
+            // short-circuit.
+            if (owners && owners.length === 1 && owners[0] !== undefined) {
+                return classifySingleOwnerFile(entry, engineDir, patchesDir, 'furnace', owners[0], ctx);
+            }
+            return { ...entry, classification: 'furnace' };
         }
-        results.push(await classifySingleOwnerFile(entry, engineDir, patchesDir, 'patch-backed', owner));
     }
-    return results;
+    // Not in any patch → unmanaged
+    if (!owners) {
+        return { ...entry, classification: 'unmanaged' };
+    }
+    // File is claimed by exactly one patch — compare content.
+    const owner = owners[0];
+    if (owner === undefined) {
+        return { ...entry, classification: 'unmanaged' };
+    }
+    return classifySingleOwnerFile(entry, engineDir, patchesDir, 'patch-backed', owner, ctx);
 }

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

@@ -28,8 +28,15 @@ export interface HarnessCrashSignature {
     reason: string;
     line: string;
 }
+/** Numeric counts parsed from the harness's embedded result summary. */
+export interface HarnessSummaryCounts {
+    /** Total checks the suite ran (`Ran N checks`), when the summary prints one. */
+    checks?: number;
+    /** Unexpected-result count (`Unexpected results: N`), when the summary prints one. */
+    unexpected?: number;
+}
 /** Result of {@link classifyHarnessRun}. */
-export interface HarnessRunVerdict {
+export interface HarnessRunVerdict extends HarnessSummaryCounts {
     kind: HarnessRunClassification;
     signature?: HarnessCrashSignature;
     /** First concrete test-failure evidence line, when available. */
@@ -146,6 +153,30 @@ export declare function detectHarnessCrashSignature(output: string): HarnessCras
  *    (`greenSummaryRejected`) and fails.
  */
 export declare function classifyHarnessRun(exitCode: number, output: string, requestedPaths: readonly string[]): HarnessRunVerdict;
+/**
+ * Parses the numeric counts from the harness's embedded result summary
+ * (`Ran N checks` / `Unexpected results: N`). The LAST occurrence of each
+ * wins — a multi-suite run prints one summary per suite and the final one
+ * covers the aggregate the operator sees. Absent counts are omitted (the
+ * `FIREFORGE-VERDICT:` contract: an absent key means "summary did not
+ * print it", never zero).
+ */
+export declare function extractSummaryCounts(output: string): HarnessSummaryCounts;
+/**
+ * Formats the machine-readable `FIREFORGE-VERDICT:` line — the stable,
+ * greppable last line every `fireforge test` run prints so harness-verdict
+ * consumers stop regexing mach internals. The status follows THIS
+ * classifier, never 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. Count keys are omitted when
+ * the embedded summary did not print them. Sharded aggregate lines carry
+ * a trailing `shards=<passed>/<total>` instead of counts (counts belong
+ * to a single embedded suite summary).
+ */
+export declare function formatFireforgeVerdictLine(verdict: HarnessRunVerdict, shards?: {
+    passed: number;
+    total: number;
+}): string;
 /**
  * Builds the operator-facing failure message for a green-looking summary
  * that was rejected on crash or truncation evidence (never trusted as a

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

@@ -447,20 +447,21 @@ export function detectHarnessCrashSignature(output) {
  *    (`greenSummaryRejected`) and fails.
  */
 export function classifyHarnessRun(exitCode, output, requestedPaths) {
+    const counts = extractSummaryCounts(output);
     const realFailures = realUnexpectedFailureLines(output);
     const firstRealFailure = realFailures[0];
     const failureBlocks = collectUnexpectedFailureBlocks(output);
     const secondaryHarnessSignature = firstRealFailure !== undefined ? detectSecondaryHarnessNoise(output) : undefined;
     const signature = detectHarnessCrashSignature(output);
     if (signature) {
-        return { kind: 'harness-crash', signature };
+        return { kind: 'harness-crash', signature, ...counts };
     }
     const ranTests = hasExecutionSignal(output);
     if (!ranTests && requestedPaths.length > 0) {
-        return { kind: 'no-tests' };
+        return { kind: 'no-tests', ...counts };
     }
     if (exitCode === 0) {
-        return { kind: 'tests-ran-ok' };
+        return { kind: 'tests-ran-ok', ...counts };
     }
     // Exit codes follow the corrected verdict: a run whose embedded summary
     // completed green is a pass even when the wrapper exit code went
@@ -483,6 +484,7 @@ export function classifyHarnessRun(exitCode, output, requestedPaths) {
             completeness.neverEnded.length > 0) {
             return {
                 kind: 'test-failures',
+                ...counts,
                 ...(firstRealFailure !== undefined ? { realFailureLine: firstRealFailure } : {}),
                 ...(failureBlocks.length > 0 ? { realFailureBlocks: failureBlocks } : {}),
                 ...(secondaryHarnessSignature !== undefined ? { secondaryHarnessSignature } : {}),
@@ -493,15 +495,68 @@ export function classifyHarnessRun(exitCode, output, requestedPaths) {
                 },
             };
         }
-        return { kind: 'tests-ran-ok', greenSummaryOverride: true };
+        return { kind: 'tests-ran-ok', greenSummaryOverride: true, ...counts };
     }
     return {
         kind: 'test-failures',
+        ...counts,
         ...(firstRealFailure !== undefined ? { realFailureLine: firstRealFailure } : {}),
         ...(failureBlocks.length > 0 ? { realFailureBlocks: failureBlocks } : {}),
         ...(secondaryHarnessSignature !== undefined ? { secondaryHarnessSignature } : {}),
     };
 }
+/**
+ * Parses the numeric counts from the harness's embedded result summary
+ * (`Ran N checks` / `Unexpected results: N`). The LAST occurrence of each
+ * wins — a multi-suite run prints one summary per suite and the final one
+ * covers the aggregate the operator sees. Absent counts are omitted (the
+ * `FIREFORGE-VERDICT:` contract: an absent key means "summary did not
+ * print it", never zero).
+ */
+export function extractSummaryCounts(output) {
+    const checks = lastCapturedCount(output, /\bRan (\d+) checks?\b/g);
+    const unexpected = lastCapturedCount(output, /\bUnexpected results:\s*(\d+)\b/g);
+    return {
+        ...(checks !== undefined ? { checks } : {}),
+        ...(unexpected !== undefined ? { unexpected } : {}),
+    };
+}
+/** Last captured integer for `pattern` in `output`, if any occurrence matches. */
+function lastCapturedCount(output, pattern) {
+    let last;
+    for (const match of output.matchAll(pattern)) {
+        const captured = match[1];
+        if (captured !== undefined) {
+            last = Number.parseInt(captured, 10);
+        }
+    }
+    return last;
+}
+/**
+ * Formats the machine-readable `FIREFORGE-VERDICT:` line — the stable,
+ * greppable last line every `fireforge test` run prints so harness-verdict
+ * consumers stop regexing mach internals. The status follows THIS
+ * classifier, never 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. Count keys are omitted when
+ * the embedded summary did not print them. Sharded aggregate lines carry
+ * a trailing `shards=<passed>/<total>` instead of counts (counts belong
+ * to a single embedded suite summary).
+ */
+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}` : '';
+    if (verdict.kind === 'tests-ran-ok') {
+        return `FIREFORGE-VERDICT: PASS${counts}${shardSuffix}`;
+    }
+    const reason = verdict.kind === 'harness-crash'
+        ? 'crash'
+        : verdict.kind === 'no-tests'
+            ? 'no-tests'
+            : 'test-failures';
+    return `FIREFORGE-VERDICT: FAIL reason=${reason}${counts}${shardSuffix}`;
+}
 /**
  * Builds the operator-facing failure message for a green-looking summary
  * that was rejected on crash or truncation evidence (never trusted as a

package/dist/src/core/test-path-scope.js

@@ -39,6 +39,7 @@ async function collectTestFiles(dir, relPrefix) {
         entries = await readdir(dir, { withFileTypes: true });
     }
     catch {
+        // An unreadable directory contributes no test files to the scope.
         return [];
     }
     for (const entry of entries) {
@@ -57,6 +58,7 @@ async function isDirectorySafe(path) {
         return (await stat(path)).isDirectory();
     }
     catch {
+        // A path that cannot be stat'd is not a directory for scoping purposes.
         return false;
     }
 }